bug(graph): file anchors omit heading-owned documentation relations

[styler-ai]

Why

A full scan can extract an explicit repository link from Markdown and persist it as a documents relation whose source is the enclosing heading entity. The document file remains selectable, but file-outbound traversal returns an exact zero because the edge is not adjacent to that file. This breaks the normal file-first agent funnel and makes valid documentation traceability appear absent.

A document with no supported static reference has a different problem: an exact zero gives no indication whether extraction completed and proved there were no candidates, or whether coverage is missing. The graph must distinguish those states without inventing implementation links from prose.

What Changes

• Make the owning document file the canonical source of each admitted static documents relation.
• Retain heading entities and exact occurrence spans as provenance and slice evidence.
• Deduplicate one logical file-to-target relation while preserving repeated occurrences across headings.
• Add a closed trusted no_candidates state for complete Markdown extraction with zero supported static targets.
• Normalize that state through the existing schema-18 complete-zero document coverage row; add no schema or migration.
• Advance the derived-index projection contract so RC1 databases refresh stale heading-owned relations before RC2 reads trust them.
• Retain typed unresolved reasons for admitted references that cannot resolve.
• Add real full-scan CLI/MCP file-outbound, source-inbound, unresolved, and no-candidate regressions to mandatory platform and release CI.

Capabilities

• file-anchored-document-relations: known documentation files traverse directly to proven static repository targets.
• explicit-document-zero-coverage: complete extraction with no supported candidate is graph-visible and distinct from unresolved, partial, failed, ignored, or stale coverage.

Architecture Diagrams

• Canonical documentation relation projection
• Classified documentation and worktree navigation

Release Scope

ProjectAtlas v0.4.5-rc2 correctness fix across the existing Markdown projection, normalized graph storage, bounded relation service, CLI/MCP adapters, and mandatory release proof.

Non-Goals

• Infer semantic implementation links from prose, similarity, topic overlap, or model output.
• Connect one long document to every file it mentions non-statically or resembles conceptually.
• Remove headings, exact spans, typed ambiguity, unresolved reasons, or content classification.
• Add a graph database, schema migration, new crate, new MCP tool, embeddings, or document framework.
• Treat no_candidates as proof that the document has no implementation; it proves only that complete extraction found no supported static target.

Pre-Mortem

Likely failure modes:

1. File anchoring loses heading provenance or repeated occurrences.
2. A broad heuristic creates noisy prose-to-source fan-out.
3. Schema-18 complete-zero compatibility changes unrelated coverage rows or trusts stale RC1 projection semantics.
4. File-outbound works while target-inbound, unresolved reasons, or classified selection drifts.
5. Focused unit tests pass while a real full scan still returns a misleading exact zero.

Mitigations:

• Retain and verify exact occurrences while deduplicating only the logical file-to-target edge. (OpenSpec tasks: 3.1, 4.1)
• Admit only existing exact static candidates and cover long-prose negative behavior. (OpenSpec tasks: 3.1, 3.2, 3.4, 4.1)
• Prove schema-18 normalization, filtered discovery, corruption refusal, projection-contract refresh, and reopen behavior. (OpenSpec tasks: 2.1, 2.2, 2.3, 4.1)
• Verify outbound/inbound symmetry, unresolved outcomes, classified endpoints, and bounded adapter compatibility. (OpenSpec tasks: 3.3, 4.1, 4.2)
• Run real full-scan CLI/MCP and packaged holistic regressions before publication. (OpenSpec tasks: 4.2, 4.3, 4.4)

OpenSpec Tasks

1. Contract And Architecture

• 1.1 Map issue bug(graph): file anchors omit heading-owned documentation relations #461 to this change, synchronize its objective checklist, and keep RC2 scope limited to exact file-scoped document traversal plus explicit zero-candidate coverage.
• 1.2 Update the focused classified-documentation graph and publication/failure diagrams only where file ownership or normalized zero-candidate coverage changes the durable flow; render every changed Mermaid block and inspect it visually and semantically.

2. Core And SQLite Coverage Foundation

• 2.1 Add the closed no_candidates core coverage state with zero-count invariants, trusted semantics, serialization, health counts, and negative contract tests.
• 2.2 Normalize no_candidates through the existing schema-18 complete-zero row, reconstruct it only from exact zero-count invariants, and distinguish positive-complete versus zero-candidate discovery filters without changing relation storage.
• 2.3 Prove schema-18 write/read/reopen, positive-complete and zero-candidate filter separation, constraint and corruption refusal, rollback/recovery, query-plan ownership, cancellation, and bounded SQLite work.

3. Canonical Document Projection And Navigation

• 3.1 Make the owning document file the canonical source of every admitted static documents relation while retaining exact heading entities, occurrence spans, resolution dependencies, typed unresolved reasons, and self-edge rejection.
• 3.2 Emit no_candidates only for complete zero-candidate Markdown extraction and preserve partial, failed, ignored, oversized, quarantined, stale, and admitted-but-unresolved behavior.
• 3.3 Update detailed relation composition so file-outbound documents and target-inbound documented_by remain one canonical bounded fact with classified endpoints, exact next calls, pagination, occurrence, selection, cancellation, and output compatibility.
• 3.4 Preserve full/incremental equivalence after add, edit, rename, delete, case, fragment, ignore, and failed-publication transitions without speculative prose or similarity edges.

4. Mandatory Regression And Release Proof

• 4.1 Add production-shaped projection, core, SQLite, and service tests for heading-contained file traversal, repeated-target deduplication, exact occurrences, inbound symmetry, unresolved outcomes, no-static-target coverage, and long-prose negative behavior.
• 4.2 Add real CLI/MCP full-scan regressions for exact-root file-outbound, source-inbound, unresolved, no-candidate, wrong-root, missing-index, and no-implicit-mutation behavior; wire them into mandatory CI and the packaged holistic RC E2E.
• 4.3 Run focused tests, cargo fmt --check, cargo check --workspace --all-targets --all-features, warnings-denied workspace Clippy, full workspace/all-feature and doc tests, warnings-denied docs, strict OpenSpec, IssueOps checklist parity, ProjectAtlas lint, and representative high-reference performance/query-plan checks with explicit timeouts.
• 4.4 Update durable graph, database, upgrade, agent-integration, release, privacy, and failure guidance; resolve or disposition every live review/automated finding and verify the exact packaged RC2 behavior without displacing v0.4.4 Latest.
• 4.5 Review the final implementation against the architecture diagrams, update the diagrams or implementation until they agree, or reconfirm the reasoned N/A.