Navigate, Don't Address

Section	What it covers
Problem	Why centralized path references cause drift
Principle	Paths as navigation output, not input
What holds paths	Legitimate vs illegitimate path locations
Cross-references	How documents link to each other
Conventions	How naming rules cascade through the tree
Global defaults	The few universal conventions

#Problem

A centralized reference file (file-paths.md, 513 lines) defines where every type of document lives, how directories are named, and what structure each directory follows. Every skill and agent copies from it. The copies drift. Tree diagrams in content files contradict the actual directory contents. Structural descriptions in methods duplicate what the index already says. The reference file itself goes stale as the system evolves.

The root cause: treating paths as prescribed addresses that agents look up in a reference, rather than as navigation outcomes that agents discover by walking the index tree.

#Principle

Paths are outputs of navigation, not inputs from reference docs. The only "address book" is the index.md hierarchy itself. An agent that needs to find where foundations live doesn't consult a reference file — it reads patterns/index.md and sees foundations/ listed there. An agent that needs to create a new project doesn't look up the naming pattern in a centralized doc — it reads projects/index.md and sees the convention declared locally.

This eliminates the synchronization problem. There is no copy to go stale because there is no source to copy from. The index IS the truth, and navigation IS the lookup.

#What holds paths

Legitimately:

• index.md — lists its own children (paths to immediate contents). This is what indices DO.
• /read and /write SKILL.md — top-level routing logic (directory names: patterns/, projects/, foundations/, strategy/, personas/). This is the root of navigation.
• Frontmatter source: — provenance pointer to where content came from. Accepts HAAK-relative paths and external refs.

Illegitimately (remove or replace):

• Tree diagrams in content files — the index is SSOT
• ## Structure sections in methods or docs — the index is SSOT
• Backtick paths used as navigation aids — use [[Title]] links instead
• Centralized path reference files — absorbed into the index hierarchy

#Cross-references

Three mechanisms, each for a different purpose:

[[Title]] — in-text links between documents. Title-based, not path-based. Survives moves and renames. Bear resolves these as wiki links. Use for prose references: "as argued in [[Drift Resistance]]."

related: frontmatter — structured cross-references. Uses slugs (directory names), not full paths. The index tree resolves slug to path. Example: related: [drift-resistance, recursive-index] not related: [patterns/architecture/04_drift-resistance, ...].

source: frontmatter — provenance. Points to where content originated. Accepts both HAAK-relative paths (projects/<slug>/sources/2026-02-22-idea.md) and external refs ([external:~/path], [gdrive:DOC_ID]). The one frontmatter field that legitimately holds paths, because provenance IS an address.

#Conventions

Naming conventions cascade through the index hierarchy, following the same inheritance pattern as architecture 09 (recursive-index). Each index.md declares only LOCAL rules — conventions that differ from the parent. Children inherit everything not overridden.

A ## Conventions section in index.md declares the naming pattern for that directory's children. Conventions are hints for agents, not hard validation gates.

Example: projects/pr). Subdirectories of projects inherit this. personas/index.md declares <lastname>-<initials>/. Neither needs to restate that - separates words or that index.md` is always the entry point — those are global defaults.

#Global defaults

The few conventions universal enough to live outside any specific index:

• index.md is always the directory entry point
• - separates words in folder names; _ separates number prefixes in file names
• Frontmatter is required on content docs (schema in /write references/frontmatter-schema.md)
• license: MIT in frontmatter for all HAAK content

These live here (architecture 11) because they apply everywhere. Everything else is local.

---

haak · created 2026-02-22 · zach + claude

Architecture 11 — Navigate, Don't Address — 2026 — Zachary F. Mainen / HAAK