feat(retrieval): bound graph boost and explain misses [roadmap:retrieval-diagnostics]

[tcballard]

Summary

Implements decisions/roadmaps/retrieval-diagnostics.md.

Adds:

• a fixed 0.85 lexical floor so relationship-graph popularity can only break lexical near-ties
• decided diagnose <query> <target> for deterministic named-target miss traces
• additive explain fields, contract documentation, index invalidation, and boundary tests

Roadmap / ADR Trace

Roadmap:

• decisions/roadmaps/retrieval-diagnostics.md

Requirements:

• decisions/requirements/rac-floor-ratio-boost-gate.md
• decisions/requirements/rac-explain-miss-diagnostics.md

Relevant ADRs:

• decisions/decisions/adr-002-ai-optional.md
• decisions/decisions/adr-007-json-contract-stability.md
• decisions/decisions/adr-037-token-boundary-search-matching.md
• decisions/decisions/adr-038-body-text-search-tier.md
• decisions/decisions/adr-066-deterministic-grounding-eval.md
• decisions/decisions/adr-078-deterministic-relevance-ranking.md

Scope

Included

• clamp graph contribution to zero when a candidate's BM25 score is below 85% of the strongest lexical match
• retain lexical contribution and match membership for clamped candidates
• expose graph_floor_ratio and graph_gate in find --explain
• diagnose no-match, partial-match, filtering, rank, and result-window truncation for one named artifact
• invalidate persistent indexes through the scoring fingerprint
• mark the two requirements accepted and the roadmap achieved

Excluded

• embeddings, semantic ranking, or model-based diagnosis
• a configurable or corpus-specific floor ratio
• corpus-wide enumeration of missed artifacts
• changes to default find output when --explain is absent

Product / Architecture Decisions

• The graph signal remains part of ADR-078's deterministic RRF score, but only for candidates that clear an inclusive 0.85 lexical floor.
• Diagnostics reuse the production tokeniser, field matcher, filters, and ranking function. They do not maintain a parallel retrieval implementation.
• The scoring fingerprint includes graph_floor=0.85, so stale indexes rebuild instead of silently retaining the old ranking contract.
• Explain fields are additive under the existing schema version because the default response remains unchanged.

User-Facing Contract

CLI

decided diagnose "desktop persistence" RAC-01JY4M8X2QZ7 decisions/ --json
decided diagnose "desktop persistence" RAC-01JY4M8X2QZ7 decisions/ --limit 3

diagnose accepts the same type, tag, liveness, and traversal filters used by find.

Human Output

The trace names the target, outcome, reason, rank, matched and missing terms, and artifacts surfaced ahead when applicable.

JSON Output

The new payload reports query, target, outcome, reason, surface_limit, match_count, term evidence, rank, and the explained artifact. Existing find --json --explain components gain graph_floor_ratio and graph_gate.

Exit Codes

• 0: the named target was diagnosed
• 1: the target is missing or ambiguous
• 2: arguments or directory are invalid

Verification

Ran

• decided validate decisions/ — 451 valid artifacts, 0 invalid
• decided relationships decisions/ --validate — 2,694 relationships, 0 validation issues
• decided review decisions/ — no priority 1–2 findings; existing lower-priority review debt remains
• regenerated and independently verified the scoring-fingerprint index vectors
• JSON parse check for the changed index vector
• git diff --check

GitHub Actions is green. PR Checks run #502 passed, and Rust workflow run #174 passed the release workspace tests, strict Clippy, formatting, macOS and Windows runtime smokes, dependency policy, contract vectors, and live-corpus invariants.

Covered

• inclusive and just-below floor boundaries
• a graph-popular weak lexical candidate clamped in real ranking
• named-target required handling
• no-term, partial-term, outranked, and result-window-truncated diagnoses
• additive explain evidence and scoring-fingerprint invalidation

Review Path

Suggested order: resolve.rs, output and CLI wiring, CLI/unit tests, index fingerprint and contract vector, then corpus and user documentation.

Notes For Reviewer

The companion benchmark PR adds four black-box component cases and two downstream DecisionGrounding scenarios. It must consume a published v0.28.0 binary before its release-dependent checks can pass.