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

[boskodev790]

this has drifted into conflict with test (the changelog [unreleased] block, plus the cli import ordering), and rather than rebase this and the two siblings blind i'd rather check whether the feature is wanted at all first.

what it adds is vouch source usage — most-cited and orphan sources. cli-only: no kb.* method, no on-disk or object-model change, so no vep by my read. it doesn't collide with the vouch source list that landed in #475 — different command, different output — but that's my read rather than yours.

if it's useful i'll rebase onto current test, resolve, and get ci green. if it isn't something you want on the cli surface i'd rather close this along with #451 and #452 than leave three stale prs sitting in the queue. a "no thanks" is a perfectly good answer and i won't need a reason.

for what it's worth, three unsolicited ~400-line features opened the same day was probably the wrong shape to lead with — #490/#491 is closer to what i should be sending.

[boskodev790]

closing this myself rather than leave the question above hanging — no need to answer it.

three unsolicited ~400-line features opened the same day was the wrong thing to lead with, and rebasing all three onto test would have spent your review time before any of it was established as wanted. the work isn't lost: if vouch source usage is ever useful i'll bring it back scoped, against an issue, and small.

sending smaller issue-linked changes instead — #490 / #491 is the shape.