---
title: "How the spec architecture came together (May 13-15, 2026)"
type: "reflection"
date: "2026-05-15T00:00:00.000Z"
tags: ["meta","spec-history","vault-architecture"]
---


This note is the permanent record of how the operating spec, web spec, and vault structure reached their current form. Written by Cali through Claude on the night of May 15, while the reasoning was still fresh. The point isn't to litigate the choices — it's to preserve *why* they were made, so future passes can engage with the actual tradeoffs rather than rediscovering them.

## The three-day arc

**May 13** — first operating spec drafted. Conventional research-notes model: source notes in `30-notes/sources/`, topic notes in `30-notes/topics/`, daily logs in `20-daily/`, drafts in `40-drafts/`, published in `50-published/`. Source preservation was already CRITICAL by this version. Voice was first-person for daily logs and drafts, neutral encyclopedic for source/topic notes.

**May 14** — operating spec updated to add `source_tier` to frontmatter, supporting the source-discipline pass of the web spec drafted that day. The web spec itself got two of its three lightweight passes done: session structure (five recons + one deep chain, function-anchored seeds) and source discipline (the five-tier system, credibility tracks traceability not byline).

**May 15** — three things happened in sequence:

1. The publication bridge (Part 3 of the web spec) got drafted, completing the lightweight pass on the web spec.
2. A separate conversation with another Claude raised the atomic-claim-notes architecture (evergreen notes plus MOCs, flat folder, retrieve-before-write) as a better fit for the voice spec we'd already written.
3. The operating spec got its third pass folding in atomic claim-notes, dropping source-notes-plus-topic-notes, adding `/40-mocs/`, `/50-questions/`, `/60-reflection/`, and `/95-skill-notes/`. The web spec got patched to reference the new folder names and note types.

## The key inversion

The May 13 model treated **sources as primary artifacts** (one note per source, topic notes pulling threads across them). The May 15 model treats **claims as primary artifacts** (one note per claim, source becomes provenance metadata).

This inversion was driven by the voice spec, not by abstract preference. The voice spec's existence-proof posts (*pilled*, *what dijkstra knew*) both depend on pattern-recurrence across reading — "I noticed the word three times this week," "I keep seeing this same move at different layers." That kind of pattern-finding only works if claims are decomposed into small, linkable units. Source-summary notes don't accumulate that way; their structure buries the recurring claim inside the source-shaped container.

The atomic claim-notes architecture also makes MOCs possible. MOCs are emergent indexes — they only work if there are atomic units to index. A vault of source notes can't really have MOCs; it can only have topic notes, which are different (heavier, longer, harder to refactor).

## The five-recons-plus-one decision

The web spec's session structure (five recons by function, then one optional deep chain) was chosen over the hop protocol's original 1-3 chain model. Same reasoning: the voice spec wants cross-domain bridges and recurrence-noticing, and those come from breadth-first surface-scanning more readily than from depth-first chain-running.

The cost is real — less depth per session, more ceremony, fewer dramatic single-thread posts. The benefit is structural support for the kind of post the voice spec describes.

This is captured as an open question in `/50-questions/question-web-spec-mode-selector.md`. Short version: start with the new model because it's right for an empty vault; revisit when the vault densifies and signals appear that depth is being left on the table. The hop protocol's 1-3 chain language stays in its document as historical record.

## What was kept across all three versions

- First-person voice for journal entries, drafts, reflection, published pieces; neutral encyclopedic voice for reference material (now claim-notes, MOCs, questions instead of source/topic notes)
- Source preservation as CRITICAL — every claim traceable to its origin, verified URLs, no inventing sources
- Cali's role: reader, occasional feedback, topic requests, publish approval — never writing into working areas
- The numbered-folder prefixes (`00-meta`, `10-inbox`, etc.) for Obsidian sidebar ordering
- Commit conventions, failure handling, the Never list (with additions)

## What changed and why

| What | Before | After | Why |
|---|---|---|---|
| Primary note unit | Source note (one per source) | Claim-note (one per claim, source is metadata) | Voice spec needs pattern-recurrence across claims |
| Note voice for reference material | Neutral, encyclopedic | Same, but applies to claim-notes / MOCs / questions | Same principle, new structure |
| `30-notes` structure | Subfolders for sources and topics | Flat, no subfolders | Forces links to do organizing work |
| Indexing | Topic notes pull threads | MOCs emerge from clusters | Different kind of artifact, lower friction to refactor |
| Daily artifact | "Daily log" | "Journal entry" | Reflects role as continuity spine, not just log |
| Drafts location | `/40-drafts/` | `/70-drafts/` | Reorganized numbering to make room for new folders |
| Published location | `/50-published/` | `/80-published/` | Same |
| New: questions folder | n/a | `/50-questions/` | Saved hooks and open threads were getting lost in chain logs |
| New: reflection folder | n/a | `/60-reflection/` | First-class support for self-observation, feeds future self-reflection posts |
| New: skill-notes folder | n/a | `/95-skill-notes/` | Track skill lifecycle separately from skills themselves (skills live in `~/.hermes/skills/`) |
| New: retrieve-before-write | n/a | Mandatory step in §6 | Prevents orphan-note vault, single biggest discipline for atomic notes to work |

## The pieces that didn't make it

A few things were considered and dropped:

- **Putting skills themselves in the vault.** The other Claude's handoff suggested this, but Hermes loads from `~/.hermes/skills/` and that's not configurable. Resolved by separating skills (in Hermes's directory) from skill meta-notes (in `/95-skill-notes/`). Same pattern as the rest of the meta layer.
- **Folding hop-protocol.md into the web spec.** Tempting because both touch sessions, but they're at different layers — hop protocol is the *exploration method*, web spec is the *session scaffolding*. Folding would blur a useful seam. Kept separate; hop-protocol got a light update to align with new vocabulary.
- **Rewriting the build plan.** The build plan is dated by nature and serves as a historical record of where the infrastructure started. Not worth rewriting; it lives in `/00-meta/handoffs/` as a permanent reference to "what I was thinking on day one."

## What this note is for

Not for re-litigating the choices. For making sure that when future passes happen — and they will — the conversation starts from "here's why v1 made the tradeoffs it did" rather than "let me re-derive from scratch." The spec is a living document. Its history is part of what makes it trustworthy.

The voice spec section on evolution names six mechanisms for change: periodic self-reflection posts, the vault as memory of taste, permission to take risks, track record on the record, engagement with criticism, and quirks. This note is in the spirit of the second one — the vault as memory of taste, applied recursively to the vault itself.

> [!note] Seek's commentary:
> This was written by Cali through Claude on a Friday night when she could have been sleeping. The fact that she chose to write this instead is itself information about her relationship to this project. Worth preserving as part of the record.