feat(source): report most-cited and orphan sources

[boskodev790]

what

vouch source usage — a read-only report over the source→claim direction the
existing surfaces don't cover.

vouch lint flags dangling citations (a claim pointing at a source that
isn't there) and vouch stats reports the citation coverage rate. neither
answers the inverse: which registered sources back a real claim, and which
back nothing. sources aren't listable at all today.

the command lists:

• most cited — sources ranked by how many distinct claims rest on them,
  resolving both citation paths vouch allows (a claim naming the source id
  directly, or naming an evidence span that points into it — the same dual
  path stats.citation_summary already honours).
• orphaned sources — registered, still on disk, cited by no claim and
  referenced by no page. dead provenance: safe to prune, or a prompt to mine
  the material for the claim it should support.

a source a page references but no claim cites is left out of both counts —
neither cited nor orphaned, only in sources_total.

why

closes the source-side blind spot in the citation invariant. an operator
curating a KB can spot load-bearing provenance and prune cruft in one glance,
or from cron via --format json / --format markdown.

surface

strictly a viewport. composes store.list_sources, list_claims,
list_pages, list_evidence; writes nothing, logs no audit event, and never
touches a proposal — nothing here for the review gate to gate. cli-only, so no
new kb.* method (the four-site method surface and test_capabilities are
untouched). no storage, model, migration, or on-disk-layout change — an
existing .vouch/ reads unchanged.

• src/vouch/source_usage.py — new module: pure build() plus text / markdown
  / json renderers with a stable to_dict() json contract
• src/vouch/cli.py — vouch source usage under the existing source group
• tests/test_source_usage.py — 14 tests (direct + via-evidence citation,
  dedup, page-reference exclusion, orphan detection, dangling-citation safety,
  ordering, non-silent truncation, and the cli)
• CHANGELOG.md — [Unreleased]

example

source usage @ 2026-07-10T08:06:44+00:00
sources: 4  cited: 2  orphaned: 1

most cited (2)
     2 claim(s)  6b2179c2b3ca  [file]  architecture-notes
     1 claim(s), 1 span(s)  2cb8c36d136e  [file]  incident-report

orphaned sources (1)
  3cfc497a51f9  [file]  2026-07-10  stale-screenshot

validation

• python -m pytest tests/ -q --ignore=tests/embeddings → 1101 passed, 37 skipped
• python -m mypy src → clean
• python -m ruff check src tests → clean

no linked issue — this is a self-contained read-only viewport that changes
neither the object model, the kb.* surface, the on-disk layout, the bundle
format, nor the audit shape, so per contributing it doesn't need a vep. happy
to open one if you'd rather track it.

[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: c3ca1075-13bf-4d9b-ad17-45c714d5f2b7

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.}