feat(cli): shared hook efficacy ledger + read-after-served adoption KPI

[RaghavChamadiya]

What

Turns the sessions.db injections table into a shared efficacy ledger for every augment hook surface, and adds the read-after-served adoption metric on top of it.

Ledger (core/sessions/staging.py, augment_cmd/decision_inject.py)

• New surface / category / chars columns, migrated in place by both writers (hook-side stdlib opener and the staging store), so sidecars created by either side first stay compatible.
• Decision injections tag their rows (decision / session_start / edit_notice); the Grep/Glob enrichments (rescue, triage, flood digest) now log each firing with its size.
• The decisions miner reads only decision-surface rows, so measurement rows from other surfaces never reach it; the edit-notice cap count is scoped the same way.

Read-after-served KPI (augment_cmd/served_reads.py, new)

• PostToolUse on repowise MCP tools records which file line-ranges a response actually served. Only fields carrying source bytes count (get_symbol bodies and range reads, get_answer symbol_bodies/quotes); skeletons and signatures do not, since a follow-up Read after those is expected.
• A later Read whose window is >=80% covered by served ranges logs one read_after_served row per file per session (chars=0, measurement only). Nothing is ever injected at that moment.
• The PostToolUse matcher widens to mcp__.*[Rr]epowise.*__.* (installer migrates existing installs in place; plugin hooks.json updated) so served content is observable at all.

Why

Served-then-read is the most diagnostic signal we have for whether MCP answers actually land: a Read of content the tools already served means the answer did not stick. This ledger lets that number, and the used-vs-ignored rate of every other hook enrichment, be tracked per session so guidance that gets ignored can eventually prune itself instead of accumulating as noise.

Notes

• Unknown tool-output shapes are skipped, never guessed, on every path.
• Hook path stays stdlib-only sqlite; any failure degrades to silence.
• Bookkeeping rides the existing per-session state file with hard caps (50 files / 40 ranges), and the ledger claim is the same atomic INSERT OR IGNORE that decision notices use.

Testing

• 11 new tests in tests/unit/cli/test_augment_served_reads.py: coverage math (union of disjoint serves, offset windows, partial coverage stays silent), once-per-file-per-session dedup, unknown-shape refusal on both the Read and MCP sides, search-surface logging with content-hash dedup, and legacy-sidecar migration through both writers.
• All affected suites pass (228 tests across augment, sessions, and hook-migration).

[repowise-bot]

✅ Health: 7.6 (unchanged)

📋 At a glance
5 hotspots touched · 6 new findings introduced · 5 co-change pairs left out · 1 file with recent fix history. Scoped to packages.

⚠️ Change risk: moderate _{(riskier than 64% of this repo's commits · raw 9.3/10)}
This change's risk is driven by:

• more lines added than baseline
• more scattered than baseline

🩹 Review priority _{(files here with the most recent bug-fix history — defects cluster, so review these first)}

• .../editor_integrations/claude_config.py — fixed 3× in the last ~6 months

🔎 More signals (2)

🔥 Hotspots touched (5)

• .../sessions/staging.py — 2 commits/90d, 4 dependents · primary owner: Raghav Chamadiya (100%)
• .../augment_cmd/decision_inject.py — 1 commits/90d, 3 dependents · primary owner: Raghav Chamadiya (100%)
• .../augment_cmd/command.py — 3 commits/90d, 1 dependents · primary owner: Raghav Chamadiya (100%)

2 more

• .../editor_integrations/claude_config.py — 7 commits/90d, 8 dependents · primary owner: Raghav Chamadiya (59%)
• .../augment_cmd/search.py — 1 commits/90d, 2 dependents · primary owner: Raghav Chamadiya (100%)

🔗 Hidden coupling (1 file)

• .../editor_integrations/claude_config.py co-changes with these files (not in this PR):
  • .../cli/test_mcp_config.py (4× — 🟢 routine)
  • .../cli/rewrite_hook.py (3× — 🟢 routine)
  • .../distill/test_rewrite_hook.py (3× — 🟢 routine)
  • docs/DISTILL.md (2× — 🟢 routine)
  • .../editor_integrations/claude.py (2× — 🟢 routine)

---

📊 Full report · ⭐ Star Repowise · 📥 Install bot · Last updated 2026-07-11 10:02 UTC
_{Silence on a single PR with [skip repowise] in the title · Per-repo toggle on repowise.dev/settings?tab=bot}