Feat/graph neighbors context expansion

[jsdevninja]

What changed

Adds graph-aware retrieval: kb.neighbors / vouch neighbors walks Relation edges and structural links (claim→entity, page→claim, supersede/contradict) from any claim, page, entity, or source. kb.context / vouch context gains optional --expand-graph to pull neighbors into context packs after search hits, tagged with backend: "graph". New module src/vouch/graph.py; wired through MCP, JSONL, HTTP, CLI, and capabilities.

Closes #184

Why

Search and context packs are FTS/embedding driven today. The KB already stores entities, relations, and lifecycle edges (e.g. supersede writes relation artifacts for graph traversal), but nothing used the graph at retrieval time. Agents asking about a topic often need linked entities, related decisions, and page-included claims — one hop from a hit but invisible to kb.search alone.

What might break

No breaking changes for existing .vouch/ directories.

VEP

Not required — additive read-only method plus optional context params. No object model or on-disk layout changes. A spec/methods.md entry can follow in a separate docs pass before 1.0.

Tests

• make check passes locally (lint + mypy + pytest)
• New / changed behaviour has a test
• CHANGELOG.md updated under ## [Unreleased]

Summary by CodeRabbit

Release Notes

• New Features

  • HTTP transport for serving vouch with bearer token authentication
  • Batch approval and proposal expiration workflows
  • Similarity warnings when proposing duplicate claims
  • Graph-based context expansion for richer retrieval
  • MCP adapters for Claude Code, Cline, Cursor, Windsurf, and Zed
  • Bidirectional Obsidian vault synchronization
  • Configurable retrieval backends (embedding/FTS5/substring)

• Bug Fixes

  • Claims now enforced to have at least one citation
  • Improved index consistency validation via fsck

• Documentation

  • Added project index and architecture documentation
  • Gittensor/SN74 integration guide
  • HTTP transport and adapter setup guides

[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: fcdc3e01-49e7-4f23-80b3-c9d601900b22

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

📝 Walkthrough

Walkthrough

Adds graph-aware retrieval, proposal lifecycle changes, HTTP/JSONL transport support, sync and diff commands, adapter installers, and documentation/tests across the KB toolchain.

Changes

KB retrieval, transport, and workflow expansion

Layer / File(s)	Summary
Storage, retrieval, and graph context src/vouch/storage.py, src/vouch/context.py, src/vouch/graph.py, src/vouch/embeddings/similarity.py, src/vouch/capabilities.py, src/vouch/models.py	KBStore validation, retrieval backend selection, graph traversal, similarity warnings, and advertised capabilities are updated together.
Proposals, health, stats, and migrations src/vouch/proposals.py, src/vouch/health.py, src/vouch/stats.py, src/vouch/migrations.py, src/vouch/sessions.py, src/vouch/onboarding.py	Proposal validation, approval/expiry, health checks, statistics, migrations, onboarding seeding, and session crystallization are extended with new result shapes and checks.
CLI, JSONL, and HTTP transport src/vouch/cli.py, src/vouch/server.py, src/vouch/jsonl_server.py, src/vouch/http_server.py, src/vouch/logging_config.py	The CLI, JSONL server, HTTP server, logging, and server tool surfaces are expanded with JSON output, progress reporting, and HTTP transport support.
Sync, bundles, diff, and install tooling src/vouch/bundle.py, src/vouch/sync.py, src/vouch/vault_sync.py, src/vouch/diff.py, src/vouch/install_adapter.py	Bundle validation, sync flows, vault mirroring, diffing, and adapter installation are implemented with matching CLI hooks.
Adapters, docs, and plans adapters/*, docs/*, proposals/*, skills/*, ROADMAP.md, README.md, CHANGELOG.md	Adapter manifests, install docs, roadmap notes, proposals, and design plans are updated to describe the new CLI and transport surfaces.
Validation, benchmarks, and UI tests/*, benchmarks/*, web/index.html	Test, benchmark, and static UI changes cover the new storage, transport, sync, and workflow behavior.

Sequence Diagram(s)

No additional diagram.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~90+ minutes

Possibly related issues

• proposal: adopt vouch as gittensor's review-gated decision memory #132: Adds the gittensor onboarding template, seeding code, docs, and CLI init/template plumbing that match the issue’s KB seeding objective.
• feat: HTTP transport with bearer-token auth and SSE streaming for vouch serve #153: Implements HTTP transport, bearer-token auth, and the HTTP server surface described by the issue.
• feat: review-gate policy engine — conditional auto-approve, block, and escalation rules [VEP] #162: Updates proposal approval and review-gate behavior in the same lifecycle surface as the issue’s approval workflow.

Possibly related PRs

• vouchdev/vouch#24: Both PRs change src/vouch/bundle.py to strengthen tar member path safety during bundle import.
• vouchdev/vouch#79: Both PRs update lifecycle-aware retrieval behavior and FTS status synchronization for claims.
• vouchdev/vouch#136: Both PRs implement proposal expiry end to end with CLI, JSONL, and core proposal logic.

Suggested reviewers

• plind-junior

Poem

🐇 I hopped through graphs and tokens bright,
and sniffed out claims by moonlit light.
The KB now syncs, the gates now speak,
with stats and diffs for every peek.
I thump for HTTP and careful lore—
fresh carrots for the review burrow floor.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

[jsdevninja]

@plind-junior Please review

[plind-junior]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 552eeec4bd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".