portfolio-optimiser/shared/examples/nav-golden-hierarchy

nav-golden-hierarchy — hierarchical navigation golden

Fixture class nav-golden (commons-owned, per the D4 step-0 split): bundle/ in, expected-read-context.md out. Unlike the ingest-golden class (ingest-spec §11, extraction-shaped: manifest.json → expected-bundle/), a nav-golden case is bundle → read-context — the only shape that can express the load-bearing property "two conformant implementations MUST produce an identical read-context from the same bundle" (method-spec §3 Step 1).

This positive case exercises every decision the Q3 navigation contract pins:

Decision (method-spec §3 Step 1)	How this bundle exercises it
Hierarchy allowed; escape, not depth, forbidden	a/, a/b/ are navigated; nothing escapes
Link syntax: leading / = bundle root, else relative	index.md: relative overview.md + root-relative /a/index.md; a/index.md: relative b/index.md + root-relative /overview.md
Depth-first, first-seen order	render order is overview → doc-a → doc-b
Dedup on resolved path	/overview.md (from a/) resolves to the already-seen overview.md → one entry
Cycle termination	a/b/index.md links back to /a/index.md (already seen) → stops
One segment per level	each index links only its immediate children
Missing index.md binds the root alone	c/ has no index.md and nothing links c/orphan.md; it is simply unreachable, not an error
Verdict exclusion = type check per reached file, recursive	a/verdict-nested.md is reached but excluded
Flat render regardless of depth	nested concepts render as the same ## {type}: {title} sections; no level heading; nested index bodies are navigation, not content, and are not rendered

Traversal trace: index.md (its body is the leading summary) → overview.md → /a/index.md → a/doc-a.md → a/verdict-nested.md (reached, excluded) → a/b/index.md → a/b/doc-b.md → /a/index.md (seen, deduped) → /overview.md (seen, deduped). Unreachable: c/orphan.md.

Serialization the gate compares against: the root index body verbatim, then each non-index concept as ## {type}: {title} + blank line + the file body, sections separated by one blank line, file ending in exactly one trailing newline. The spec does not pin whitespace beyond this shape; a gate MAY compare byte-exact or after trailing-whitespace normalization. Only the root index body is the summary — nested index bodies (a/index.md, a/b/index.md) are navigation and do not appear.