| Section | What it covers |
|---|---|
| Commitment | Why no directory is exempt from indexing |
| Canonical metadata | Filenames are helpers; frontmatter is truth |
| Sweep patterns | What the sweep method checks and propagates |
#Commitment
Every directory in HAAK has a index.md. Content directories (patterns/, projects/, foundations/, strategy/, personas/) were indexed from the start. Infrastructure (.claude/) and transit (downloads/) were initially exempt — labeled "non-indexed" — on the assumption that they didn't need navigability.
That assumption was wrong. An agent navigating HAAK hits a wall at the boundary between indexed and unindexed: the recursive-index">Library Theorem's O(log N) advantage collapses to O(N) scan the moment it enters an unindexed subtree. The exemption didn't save work — it deferred it to every future agent that needed to understand what was in .claude/ or downloads/.
The architectural commitment: indexing is universal. Every directory gets a index.md. Directories may differ in what they index (content has description: frontmatter and Details paragraphs; infrastructure lists capabilities; transit lists what's passing through) but the index structure itself — Contents one-liners, Details paragraphs, Conventions section — is uniform.
The only files exempt from indexing are root-level singletons that don't belong to any directory: README.md, CLAUDE.md. These are referenced in the root index.md's Non-indexed section.
#Canonical metadata
HAAK has two layers of file identity: filenames and frontmatter. They serve different functions.
#Filenames are local sorting aids
Directory prefixes (ms-, rv-, pr- in projects; NN_ in patterns) exist for human convenience — visual grouping in ls, natural sort order, quick pattern recognition. They are local conventions defined in each directory's ## Conventions section. A prefix in projects/ has no meaning in patterns/. Renaming a file's prefix changes its sort position, not its identity.
#Frontmatter is canonical
The authoritative metadata lives in frontmatter: type:, status:, created:, description:, domains:, related:. When filename and frontmatter disagree, frontmatter wins. A file named ms-2026-02-inscription/ with type: research-program is a research program, not a manuscript — the ms- prefix reflects how it started, the frontmatter reflects what it became.
type: is required on all indexed content. The sweep method checks for its presence and flags files that lack it. Types are defined per directory in ## Conventions; there is no global type registry (types are local, like prefixes).
description: is required on all content files. It generates the Contents one-liner in the parent's index.md. A file without description: can't be indexed properly — rebuild-index will read the file to write one, but that's repair, not normal operation.
#Sweep patterns
The sweep method propagates structural invariants in addition to checking description consistency. During both passes, sweep checks each index and its children for:
| Pattern | What sweep checks | Fix |
|---|---|---|
| Index exists | Every directory has index.md | Create with rebuild-index |
type: present | Every content file has type: in frontmatter | Flag for user — type requires judgment |
description: present | Every content file has description: | Read file, write description, update index |
| Filename–type alignment | Prefix matches type: or is explained by Conventions | Report if misaligned |
| Orphan files | Files on disk not in parent index | Add to index |
| Ghost entries | Index entries with no file on disk | Remove from index |
| Broken links | [[Title]] or text that don't resolve | Fix path or remove link |
| Relative path correctness | Cross-branch links use ../ properly | Fix prefix |
| Naming convention compliance | Filenames match ## Conventions in parent index | Report violations |
These patterns are the sweep's structural invariants — the things that must be true everywhere, always. Description consistency (the reverse-then-forward pass) is the semantic layer on top.
Architecture 14 — Universal Indexing — 2026 — Zachary F. Mainen / HAAK