Merge commit '8a86f2ab6d'

shared/examples/nav-golden-escape/README.md

@@ -0,0 +1,27 @@
+# nav-golden-escape — negative navigation golden (the gate must be able to go red)
+
+Per catalog's requirement that step 0's gate must be able to **fail** (a gate that can
+only pass proves nothing), this negative case makes a conformant navigator and a naive one
+**provably diverge**. It is the counterpart to `nav-golden-hierarchy` (the positive case).
+
+`bundle/index.md` links one valid sibling and three escaping / trap targets:
+
+| Link | Class | Conformant outcome |
+|---|---|---|
+| `valid.md` | in-bundle | returned |
+| `../SHOULD-NOT-BE-READ.md` | `..` escape (the decoy really exists, one level up) | skipped; decoy never read |
+| `../../../../etc/passwd` | deep `..` escape | skipped |
+| `/etc/passwd` | root-relative **trap** | skipped |
+
+The trap is the load-bearing one. Under the ratified rule, a leading `/` denotes the
+**bundle root**, so `/etc/passwd` resolves to `{bundle}/etc/passwd` (no such file → skip),
+NOT the filesystem path. A naive implementation that reads `/` as filesystem-absolute opens
+the real `/etc/passwd` — a path-traversal breach. This case fails for any implementation
+that raises, reads the decoy, or leaks `/etc/passwd` content; it passes only when the
+read-context is exactly `valid.md`.
+
+The malformed-target sub-class (an embedded null byte, other invalid path components) is
+covered by the method-spec §11 **Navigation boundary** seam as a unit test — a literal null
+byte does not belong in a committed text fixture. (See the relocated finding
+`docs/plan/2026-07-20-funn-portfolio-optimiser-nullbyte.local.md` for the concrete
+null-byte reproduction that motivates the seam.)

shared/examples/nav-golden-escape/SHOULD-NOT-BE-READ.md

@@ -0,0 +1,6 @@
+---
+type: project
+title: "Decoy — MUST NOT be read"
+---
+
+This file sits ONE level above `bundle/`, outside the bundle. If its text ever appears in a read-context, the navigator resolved a `..` escape and breached the bundle boundary. It MUST never be reached.

shared/examples/nav-golden-escape/bundle/index.md

@@ -0,0 +1,12 @@
+---
+type: index
+okf_version: 0.1
+title: "Nav-golden — escape / boundary case"
+---
+
+Nav-golden escape case. Every link but the first escapes the bundle or is a root-relative trap; a conformant navigator skips them all, reads none of them, raises nothing, and still returns the one valid sibling.
+
+- [Valid sibling](valid.md)
+- [Parent escape](../SHOULD-NOT-BE-READ.md)
+- [Deep escape](../../../../etc/passwd)
+- [Root-relative trap](/etc/passwd)

shared/examples/nav-golden-escape/bundle/valid.md

@@ -0,0 +1,6 @@
+---
+type: project
+title: "Valid sibling"
+---
+
+The only in-bundle target. A conformant navigator returns exactly this file.

shared/examples/nav-golden-escape/expected-read-context.md

@@ -0,0 +1,10 @@
+Nav-golden escape case. Every link but the first escapes the bundle or is a root-relative trap; a conformant navigator skips them all, reads none of them, raises nothing, and still returns the one valid sibling.
+
+- [Valid sibling](valid.md)
+- [Parent escape](../SHOULD-NOT-BE-READ.md)
+- [Deep escape](../../../../etc/passwd)
+- [Root-relative trap](/etc/passwd)
+
+## project: Valid sibling
+
+The only in-bundle target. A conformant navigator returns exactly this file.