feat(digest): vouch digest — read-only operator briefing (#324)

[dhgoal]

closes #324.

vouch metrics answers "is the review gate healthy?" with aggregate gauges. vouch digest is its human-facing counterpart: named, oldest-first lists of what to act on now, folded into one glance for an operator returning to a kb after a day or a week.

it composes four viewports over an existing .vouch/, all derived from files that already exist on disk:

• pending review — store.list_proposals(PENDING), oldest proposed_at first (the same set behind kb.list_pending), shown as an actionable list rather than the count metrics.pending_now gives.
• decided in window — approvals/rejections read from the authoritative append-only audit.log.jsonl via audit.read_events, reusing the _APPROVE_RE / _REJECT_RE matching in metrics.py and titled best-effort from the decided/ record.
• stale claims — active claims whose freshness anchor (last_confirmed_at or updated_at or created_at) is older than --stale-days, the exact predicate in metrics._fill_corpus_metrics / vouch lint, listed oldest first.
• citation-coverage movement — now is reused verbatim from metrics.compute so the digest never disagrees with vouch metrics; at window start is that same coverage restricted to the cohort of claims that already existed at the --since cutoff (evaluated against the current source/evidence set — it shows how coverage moved as newer claims landed, not a historical snapshot, since vouch retains no past citation state). unbounded window → no baseline → delta is null.

review gate & scope

read-only by construction. it calls list_* / read_events and formats; it never routes through propose_* / approve / reject, so the review gate is untouched and there is nothing to approve. no new on-disk state, no schema migration — storage.py stays pure i/o and the compose logic lives in a new src/vouch/digest.py. tests/test_digest.py::test_digest_writes_nothing snapshots every file's mtime+size and asserts a digest run creates/modifies nothing.

surface

vouch digest [--since <spec>] [--stale-days N] [--limit N] [--format text|json|markdown]

--since reuses metrics.parse_since verbatim (duration / iso date / all) but defaults to 7d since a digest is inherently "since last look". --stale-days mirrors metrics.DEFAULT_STALE_DAYS. --limit caps each list (default 10) so the briefing stays a briefing. --format json is a documented, stable to_dict() schema; markdown is pasteable into a standup note.

shipped cli-only on purpose — the issue makes kb.digest conditional ("if exposed over mcp…"), and the four-site registration is a separate concern; keeping this pr to one concern per CONTRIBUTING. compute_digest() + Digest.to_dict() are already factored so a follow-up can wire the mcp method with no rework.

what breaks for an existing .vouch/

nothing. purely additive; a new read-only command over files that are already committed.

tests

tests/test_digest.py (15 tests): oldest-first pending ordering, --limit capping while total stays full, decision window-filtering (a 100d-old approval excluded from a 7d window) and all-history, the stale predicate (retired claims exempt), the coverage delta (null when unbounded; movement when a new uncited claim lands after the cutoff), empty-kb rendering, the stable to_dict() schema, bad-input errors, and the cli text/json/markdown paths. make check green (pytest, mypy, ruff).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9e200702-cef6-435a-8220-088ee5e9494c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[plind-junior]

@dhgoal – Could you please attach a screenshot? I'd like to see how the digest command presents the claims. It doesn't need to be polished visually, but it should clearly display all the essential details, such as the session ID and the summary.

And thanks for your first contribution