feat(agent): add bounded graph discovery and orientation

[forhappy]

Summary

• add the versioned, bounded natural-discovery contract used consistently by CLI JSON/text and MCP
• expose explicit direction, scope, ambiguity, source anchors, deterministic limits, and coherent truncation diagnostics
• make GRAPH_REPORT.md begin with a bounded Agent Orientation carrying graph health, build identity, evidence-backed anchors, and injection-safe Markdown
• update installed integrations so focused work starts with one Compass query; first-session or broad orientation reads only Agent Orientation before querying and opening minimal cited source
• add relationship-aware indexed recall for daily workflow questions across in-memory, Store, and SQLite backends
• preserve directional multigraph evidence and exact omissions whenever bounded work completes
• add bounded batch reads and a request-local immutable Store cache for practical large-repository latency
• integrate main shared lexical normalization and opt-in BM25 profiling without weakening the discovery contract

Why

Compass already advised agents to query the graph first, but the public result and report surfaces did not provide one typed, bounded, provenance-rich context model. Broad lexical scoring also missed compositional workflow questions such as checkpoint creation and repository-state recording. This change makes Compass usable as a local context layer for coding assistants while keeping correctness, determinism, ambiguity, graph health, and resource limits explicit.

Agent workflow

1. Run compass init, install the detected or explicitly selected agent integration with compass install, and keep compass watch running in a second terminal; use compass update . if watch is unavailable or failed.
2. For a focused task, run one bounded compass query first. For a first session or broad repository orientation, read only the bounded Agent Orientation at the start of compass-out/GRAPH_REPORT.md, then query.
3. Check direction, ambiguity, graph completeness, domain truncation, and pagination.
4. Retry ambiguous seeds with an exact node ID and follow next=<cursor> using --cursor <cursor> only when exhaustive scope is required.
5. Open only cited source anchors and verify decisive claims. Treat inferred, incomplete, or truncated evidence as uncertainty rather than proof.

The Compass skill and native platform rules changed to install this workflow consistently. They are local instruction assets written by compass install; they do not grant permissions, call a model, or replace source verification.

Compatibility

The discovery and orientation schemas and CLI options are additive. Legacy Store snapshots remain readable with explicitly degraded relationship recall. Updated persistent indexes and SQLite query caches are versioned and rebuilt rather than silently reinterpreted. Migration and compatibility notes are included. Legacy traversal and CompassQL routing remain available.

Main reconciliation

Merged origin/main at 5c816045 in merge commit 01946f2a. Conflict resolution:

• retained the Plan 013 MCP output dependency while updating all workspace path versions to 0.3.7
• centralized the branch verb morphology in the new shared model lexical normalizer
• combined opt-in BM25 candidate diagnostics with bounded traversal ambiguity, direction, completion, and omission reporting
• routed bounded structural resolution through the evidence-aware ranker while preserving ambiguity for evidence-equivalent leaders

GitHub reports the PR mergeable.

Validation completed after merge

• cargo test -p compass-model -p compass-query -p compass-mcp --lib --tests --locked
  • model contract suites pass
  • query unit/integration suites, 21 Store-engine tests, and the reviewed 500-query relevance corpus pass
  • MCP unit and code-query/coverage integration suites pass
• cargo test -p compass-cli --lib --locked: 78/78
• cargo test -p compass-cli --test install_cli --locked: 24/24 platform install, upgrade, plugin-load, and uninstall cases
• strict Clippy for compass-model, compass-query, compass-mcp, and compass-cli across all targets/features
• cargo fmt --all and diff checks
• frozen Entire oracles: CondenseSession and SaveStep are unambiguous rank-1 results on a fresh immutable Store artifact
• exact cache A/B: median latency improved 17.3% and 14.9%; median RSS increased 3.5% and 6.3%; semantic outputs were byte-identical
• post-merge CI repair d7edd6c3: explicit opaque cursor and text-budget guidance plus atomic OpenCode/Kilo preflight; local unit, install integration, formatting, and strict Clippy gates pass
• post-merge query calibration 5d0fd9e1: exact-first immutable Store/SQLite parity, bounded multi-concept intersections, predicate-prioritized recall, production-aware behavior ranking, and explicit exact-name completeness
• cargo test -p compass-query --all-targets --locked: 118 unit tests plus every query integration target pass, including 21 immutable Store parity tests and the reviewed 500-query relevance corpus
• python3 -m unittest discover -s benchmarks/performance/tests -p 'test_*.py': 195/195
• release-binary strict replay on seven independently materialized candidate graph/store artifacts: 14/14 top-1, direction, ambiguity, source-anchor, bounded-work, and Rust semantic-digest checks pass

Qualification status

The sealed legacy baseline covers seven pinned repositories with 14 fresh workloads and 10/10 samples per workload. Warm MCP parity is explicitly unavailable on that legacy revision because its generic MCP response has no typed structuredContent; the harness does not synthesize a semantically incomparable digest.

Angular is excluded, not passed: both the initial 1,800-second build and the bounded 3,600-second recovery timed out while actively materializing, and neither produced a valid graph/store artifact.

The final sealed seven-repository run completed on pushed HEAD 2a4a3cde: 28/28 workload results pass, all 280/280 measured samples are eligible, every sample has top-1 and recall@10 = 1, ambiguity checks pass, and all graph inputs were read-only reuse. Warm p50 improved in 13/14 rows (median 1.66%) and warm p95 improved in 10/14 (median 2.08%); Rails route recognition remains a disclosed noisy p95 outlier. The harness correctly reports only suite-mismatch against the legacy baseline because the reviewed oracle manifest changed, so no cross-suite latency/RSS ratios are promoted. Sealed evidence: plan013-after-final-v3/run.json sha256 f32f0896f4995c843dc0fe31948433a2b05e48801efa746ac06e3b867d291324.