Zachary F. Mainen · HAAK · Architecture 01 · March 2026

Hierarchy Rationale

Why HAAK uses directory hierarchy with flat domain tags, rather than pure flat-with-tags.

Why HAAK uses directory hierarchy with flat domain tags, rather than pure flat-with-tags.

#The alternative considered

Flat structure where all documents live at one level, organized entirely by tags. No type-based directories. This is how Bear works natively and how many Zettelkasten systems operate.

Arguments for flat: simpler mental model, no directory moves on reclassification, tags are the only organizing principle. The handwritten note (Feb 19) proposed this: "use tags and flat structure rather than a hierarchy."

#Why hierarchy

#Obsidian compatibility

Obsidian vaults are directory trees. Graph view groups by folder. The file explorer is the primary navigation. Properties panel reads YAML frontmatter but folder structure provides the first-level organization that makes a vault navigable at scale. A flat vault with 200+ files and only tags would require graph filtering or search for every navigation — no browsable structure.

#Types are stable, not cross-cutting

HAAK's types (foundation, policy, process, feature, project, persona) are mutually exclusive — a document is exactly one type. Mutually exclusive categories map cleanly to directories. Tags work best for cross-cutting concerns (domains, status, maturity) where a document belongs to multiple categories simultaneously. Process-architecture established this split: types → directories, domains → tags.

#Existing infrastructure assumes hierarchy

  • /write mvdir — renames and moves with automatic cross-reference fixing. This makes hierarchy non-brittle — reclassification is a single command, not a manual reference hunt.
  • /run-audit rebuild — generates index.md per directory. Hierarchy gives these indices meaning.
  • Recursive processes — peer-review has rounds (R1/, R2/), projects have subfolders (01-lib-theory-1-2-formalization/), each with index.md. These are naturally hierarchical.
  • Flat Index Principle (file-structure policy rule 11) — flexibility within hierarchy. Subfolders are flat and named, not rigidly nested. Structure emerges from work.

#Bear compatibility is preserved

Bear uses flat + tags natively. /bear-sync maps HAAK's hierarchy to Bear tags: #haak/foundations/shadow-ecosystem. Bear sees flat notes with hierarchical tags — the best of both worlds. The hierarchy lives in the filesystem; Bear gets the tag projection.

#The hybrid model

Types         → directories    (mutually exclusive, stable)
Domains       → frontmatter    (cross-cutting, many-to-many)
Wiki links    → [[Title]]      (navigable prose references)
Flat indices  → index.md    (flexibility within hierarchy)

Types-as-directories gives navigability. Domains-as-tags gives compositionality. Wiki links give prose-level cross-referencing. Flat indices give flexibility within each directory. This is the settled design.

#Origin

Handwritten note (Feb 19 2026, IMG_8979) proposed flat + tags. Assessment against existing architecture showed hierarchy is load-bearing — Obsidian, /write mvdir, /run-audit rebuild, recursive processes, and the type system all depend on it. The hybrid model (hierarchy for types, tags for domains) was already implemented by process-architecture; this document provides the rationale.

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

Architecture 01 — Hierarchy Rationale — 2026 — Zachary F. Mainen / HAAK