---
title: Vault Atom Schema + Lifecycle Reference
type: reference
tags: [vault, atoms, schema, v1.6, ATOM-01]
status: locked
locked_at: 2026-05-29
edges:
  refines:
    - "[[vault-edges]]"
  derived-from:
    - "[[v1.6-graph-primitives]]"
  see-also:
    - "[[vault-mochs]]"
---

# Vault Atoms (Atomic Knowledge Notes)

`Knowledge/Atoms/` is the intermediate one-claim layer between raw clipped
sources and synthesized Knowledge wiki pages. It is the ATOM family's core
shape per SPEC §3.3 (ATOM-01). The canonical pattern comes from
**llm-atomic-wiki** — a production reference of 584 posts → 630 atoms →
83 wiki pages with 87% reply-filter (DEEP-03 SUMMARY.md §Atoms Lens C).

The atomicity invariant is load-bearing across the whole vault:

> **An atom carries exactly ONE canonical claim or definition.**
> If a passage contains two views, and removing one leaves the other
> intact, split into two atoms.

This doc captures the atom schema, lifecycle, topic-branch convention,
and the atom→wiki edge mechanism. It is the authoritative reference for
authoring atoms by hand and for the `gmd-vault-ingest` agent that will
ship the automated extraction loop in Phase 75 (v1.6-F CURATOR-01).

## Schema

Atom frontmatter shape — copied verbatim from
`.planning/research/v1.6-deep-dive/SUMMARY.md` §Atoms `## Shipped shape`
(lines 188-246) as the authoritative source. Phases 71-75 grep `^## Atoms`
on the DEEP-03 SUMMARY and treat the codeblock below as binding contract:

```yaml
# Canonical v1.6 atom layer — invariant + frontmatter schema + lifecycle
# Phases 71-75 grep ^## Atoms and copy this codeblock as authoritative.
atoms:
  invariant:
    rule: "An atom carries exactly ONE canonical claim or definition."
    split_test: |
      If a passage contains two views, and removing one leaves the other intact —
      split into two atoms. The gmd-vault-ingest agent MUST reject candidate atoms
      containing two independent claims and emit them as two atoms instead.
    source: llm-atomic-wiki METHODOLOGY.md + CLAUDE.md (verbatim per A.1)

  placement:
    directory: Knowledge/Atoms/
    organization: topic-branch folders (e.g., Knowledge/Atoms/auth/, Knowledge/Atoms/curator/)
    branch_gate:  # all four required to add a new branch (llm-atomic-wiki CLAUDE.md)
      - Independence       # branch covers a topic that isn't a sub-topic of an existing branch
      - Scale_ge_5         # branch will accumulate >= 5 atoms within reasonable time
      - Clear_boundary     # branch's scope can be stated in one sentence
      - Teaching_independence  # branch teaches itself; doesn't require reading another branch first
    filename_convention: YYYY-MM-DD-<descriptive-slug>.md  # date prefix gives chronological order in `ls`

  frontmatter_schema:
    required:
      id: <branch>/<descriptive-slug>
      claim: <string, <=240 chars, one canonical claim>
      source: <URL | file-path | sha256:hash>  # array shape for multi-source provenance
      created: YYYY-MM-DD
    recommended:
      type: explanation | opinion | tutorial | myth-busting | case-study | comparison
      depth: beginner | intermediate | advanced
      tags: []
    optional:
      confidence: high | medium | low
      superseded_by: <atom-id>     # supersession pointer (see lifecycle below)
      derived_from: [<atom-id>]    # provenance edges to other atoms
      reuse_score: high | medium | low

  lifecycle:
    immutability: |
      Atoms are IMMUTABLE after creation. Knowledge evolution is handled via supersession:
        1. Create a new atom with the updated claim (new id, new created date)
        2. Add `superseded_by: <new-atom-id>` to the old atom's frontmatter
           (this is the ONLY sanctioned mutation of an existing atom)
        3. Move the old atom to Knowledge/Atoms/<branch>/_archive/
        4. Trigger re-derivation of any artifact referencing the old atom
    no_delete: |
      Never `rm` an atom. Use _archive/. Final deletion is a separate, conscious decision
      that must be logged in Knowledge/_log.md.

  composition:
    method: wikilink-only  # NOT embedding; forbids inline expansion to prevent drift
    edge_type: derived-from   # atom → wiki edge type per typed_edges shipped shape
    target_density: 3-8 atoms per wiki page  # llm-atomic-wiki empirical reference

  retrieval:
    default: NOT surfaced by vault-query (atoms feed curator ingest-agent consumption, not primary retrieval)
    opt_in: --include-atoms flag (per SPEC §3.3 + Open Q4 LOCKED-provisional)
```

### Two `derived` semantics — disambiguated

The schema mentions `derived_from:` (underscore) AND the closed-vocab
typed-edge verb `derived-from:` (hyphen). These are **separate axes**;
do NOT conflate them:

- **`derived-from:` (hyphen, inside `edges:` block)** — atom→wiki edge
  per EDGE-01 closed vocab (Phase 71). Inverse-pair-written by Phase 71
  `closeInversePairs` (in `bin/lib/vault-sync.js`): the target wiki page
  gets `derives: [[Atom]]` on the next `vault-sync` pass. Cite
  `references/vault-edges.md` ## Inverse Pairs row 8 (`derived-from`
  ↔ `derives`) as the locked upstream contract.

- **`derived_from:` (underscore, top-level frontmatter list)** —
  atom→atom provenance per DEEP-03 shipped shape. Separate axis; does
  NOT ride the `edges:` block. Phase 72 does NOT auto-write the inverse
  (`derives_into:` or similar) — the field is a one-direction pointer
  in v1.6. Inverse traversal at expected atom counts (~thousands, not
  millions) is acceptable via direct field scan.

### 240-char `claim:` structural enforcement

The `claim: <string, <=240 chars>` cap on line 213 of the codeblock
above is **structurally enforced at the frontmatter parser layer**:
`bin/lib/vault-frontmatter.js::parseFrontmatter` exports
`CLAIM_MAX_CHARS = 240` and emits a `claim_exceeds_240_chars` lint
event on `frontmatter.__lint[]` when an atom-typed note (DEEP-03
required-field triad: `id` + `claim` + `source`) ships an overlength
claim. Fail-open per SPEC §4: parsing succeeds and `fm.claim` is
preserved verbatim; the lint event is the Phase 75 `gmd-vault-lint`
consumer surface. Truncation is the consumer's responsibility, not
the parser's.

The 240-char cap is a STRUCTURAL proxy for the atomicity invariant.
The semantic split-test predicate ("if two independent claims share
a paragraph, split into two atoms") is convention until Phase 75's
`gmd-vault-ingest` agent ships the automated extraction loop with
predicate enforcement.

## Lifecycle

### Immutability invariant

Atoms are IMMUTABLE after creation (verbatim from DEEP-03 SUMMARY.md
§Atoms `lifecycle.immutability` block, lines 226-236):

> Knowledge evolution is handled via supersession:
> 1. Create a new atom with the updated claim (new id, new created date)
> 2. Add `superseded_by: <new-atom-id>` to the old atom's frontmatter
>    (this is the ONLY sanctioned mutation of an existing atom)
> 3. Move the old atom to `Knowledge/Atoms/<branch>/_archive/`
> 4. Trigger re-derivation of any artifact referencing the old atom

### Supersession manual checklist

Phase 72 ships MANUAL supersession. The `gmd-vault-ingest` agent
(Phase 75 CURATOR-01) will automate this loop later. Until then,
authors run this checklist by hand:

- [ ] Create new atom with updated claim — new `id:` (typically new slug)
      and new `created: YYYY-MM-DD` date
- [ ] Add `superseded_by: <new-atom-id>` to OLD atom's frontmatter
      (this is the ONLY sanctioned mutation of an existing atom — atoms
      are immutable in every other respect)
- [ ] Move OLD atom file to `Knowledge/Atoms/<branch>/_archive/`
      (NEVER `rm` — see `no_delete:` block in §Schema codeblock above)
- [ ] Log the conscious-deletion decision in `Knowledge/_log.md`
      (file convention; created lazily on first supersession — no
      pre-emptive scaffold in Phase 72)
- [ ] Trigger re-derivation of any wiki page referencing the old atom.
      Phase 72: manual `grep -rn "<old-atom-id>" Knowledge/` plus
      author-editing of the referencing wiki page(s). Phase 75
      `gmd-vault-lint` surfaces these as advisory warnings.

Phase 75 (CURATOR-04) expands `Knowledge/_log.md` scope from atom-only to all Knowledge notes — non-atom supersession events ride the same append-only log alongside atom supersession. See `references/vault-curator-split.md` §Bi-temporal Schema + §Lint Cadence.

### `superseded_by:` vs `invalidated_at:` rationale

DEEP-03 SUMMARY.md §Atoms rationale block 4 proposes amending SPEC §3.3
to replace the pre-DEEP `invalidated_at:` field with `superseded_by:`
for atom-specific lifecycle. The case (verbatim from llm-atomic-wiki
Lens A.1 + A.4):

> `superseded_by:` is graph-preserving (forward-link to replacement)
> vs destructive (timestamp-only — *when* something stopped being
> true, but not *what replaced it*). `superseded_by:` carries strictly
> more information at the same cost.

This is the load-bearing methodology contribution from llm-atomic-wiki.
The forward pointer to the replacement atom is the *graph-traversable*
answer to "what does this atom now say"; a destructive timestamp leaves
the reader to grep for the replacement.

### Phase 75 bi-temporal forward-reference (additive, not replacement)

When Phase 75 ships bi-temporal (`valid_from:` + `invalidated_at:` +
`invalidated_by:`) for non-atom Knowledge notes (CURATOR-04), atom-layer
notes will gain access ADDITIVELY — `superseded_by:` is the
graph-traversable answer, `invalidated_at:/invalidated_by:` is the
temporal answer; both coexist. Phase 75 should not reopen this design.

Concretely: after Phase 75 lands, an atom MAY carry both
`superseded_by: <new-atom-id>` (the forward-link to its replacement)
AND `invalidated_at: YYYY-MM-DDTHH:MM:SSZ` + `invalidated_by:
<actor-id>` (the temporal record of when the supersession was
authored and by whom). Authors who want only one axis are free to
omit the other — the atom-specific `superseded_by:` axis remains the
load-bearing structural answer; bi-temporal is the additional
audit-trail layer that the broader Knowledge-note evolution machinery
will use.

## Topic Branches

`Knowledge/Atoms/` organization is FLAT on day 1 of Phase 72:
`Knowledge/Atoms/YYYY-MM-DD-<descriptive-slug>.md` (empty `branch`
segment in the `id:` field). The flat bootstrap matches llm-atomic-wiki's
lived experience — branches become essential PAST ~50 atoms but are
premature before that scale.

### The 4-criterion branch gate

Promotion to `Knowledge/Atoms/<branch>/...` (e.g.,
`Knowledge/Atoms/auth/`, `Knowledge/Atoms/curator/`) happens when ≥5
atoms accumulate around a topic AND the topic meets ALL FOUR criteria
below (from llm-atomic-wiki CLAUDE.md):

1. **Independence** — branch covers a topic that isn't a sub-topic
   of an existing branch.
2. **Scale ≥ 5** — branch will accumulate ≥5 atoms within reasonable
   time (the empirical floor below which a folder is premature).
3. **Clear boundary** — branch's scope can be stated in one sentence.
4. **Teaching independence** — branch teaches itself; doesn't require
   reading another branch first.

Phase 72 documents the gate as **convention**. Enforcement ships in
Phase 75 with `gmd-vault-lint`. Authors are trusted to apply the gate
manually until then.

### Branch sprawl is the failure mode

llm-atomic-wiki's lived experience at 630 atoms says branch sprawl
is the dominant maintenance cost when the gate is skipped. A folder
with 2 atoms that splits into 2 folders of 1 atom each is worse than
either single folder OR the original flat layout — the navigational
tax is paid up front without the payoff of scale. Apply the gate
strictly; resist the temptation to pre-organize.

## Atom-to-Wiki Edge Mechanism

The atom→wiki edge wiring **reuses Phase 71 EDGE-01 ENTIRELY**: no new
writer, no new schema axis, no new vocabulary surface. The atom emits
a `derived-from:` typed-edge inside its `edges:` block; Phase 71's
`closeInversePairs` writer (in `bin/lib/vault-sync.js`) materializes
the inverse on the target wiki page during the next `vault-sync` pass.

### Authoring shape

An atom's frontmatter declares its source wiki page via the
EDGE-01 `derived-from` verb:

```yaml
---
id: auth/jwt-rotation-window-default
claim: JWT refresh-token rotation defaults to 30-day window in NextAuth.
source: https://next-auth.js.org/configuration/options#jwt
created: 2026-05-29
type: explanation
tags: [auth, jwt, nextauth]
edges:
  derived-from: [[Authentication]]
---
```

After the next `vault-sync` pass, Phase 71's `closeInversePairs` writer
adds the inverse to the `Authentication` wiki page's frontmatter:

```yaml
edges:
  derives: [[auth/jwt-rotation-window-default]]
```

### Inverse-pair lock — `derived-from` ↔ `derives` (NOT `cited-by`)

The atom→wiki edge inverse pair is **`derived-from` ↔ `derives`**,
locked from Phase 71 EDGE-01's stored-inverse-pair table row 8. Cite
`references/vault-edges.md` ## Inverse Pairs section as the upstream
contract — that table is the authoritative source for the locking.

Two atom-target edge verbs exist in EDGE-01's closed 10-verb vocab:
`derived-from` and `cited-by`. Atoms use `derived-from` for the wiki
page they synthesize from. `cited-by` is reserved for citation chains
between Knowledge wiki pages (different semantic; do not conflate).
The audit harness `tests/audit-atom-schema.sh` does NOT police this
particular inverse-pair (that's `tests/audit-edge-inverse-pair.sh`'s
job from Phase 71-02); but authors and downstream callers MUST treat
this locking as binding.

### MC1 harmonization — unchanged

The MC1 harmonization (writer = Phase 71; warning surface = Phase 75)
applies to atom-emitted `derived-from` edges UNCHANGED. Plan 72-02
(`vault-query --include-atoms`) and any future atom-aware retrieval
surface do NOT re-litigate ownership: the inverse-pair writer is
Phase 71's `closeInversePairs`, full stop. Phase 75's `gmd-vault-lint`
surfaces `phantom_inverse` warnings (when an atom's `derived-from:`
target wiki page doesn't exist) and any `unknown_edges` bucket
entries. See `references/vault-edges.md` ## Inverse Pairs for the
MC1 harmonization sentence verbatim.

### DEEP-06 cross-milestone anchor

`Knowledge/Patterns/v1.6-graph-primitives.md` is the curator-promoted
v1.6 graph-primitives synthesis note (Phase 70 Plan 70-04). It is the
authoritative cross-milestone anchor for v1.6 graph primitives —
EDGE-01 vocab, EDGE-02 note-type enum, ATOM-01 schema, EDGE-03 SKOS-lite
aliases. v1.7-A CDEEP phase (code-edge vocabulary binding per SPEC §6
Open Q7 LOCKED) will cite that synthesis note as the v1.6 anchor; this
doc (`references/vault-atoms.md`) is the v1.6 atom-specific contract
that the v1.7-A plan-phase MUST cite when defining code-atom semantics.

The DEEP-06 contract marker at
`.planning/phases/70-v1-6-a-deep-research-substrate/deep-06-contract-marker.md`
is grep-discoverable. v1.7-A's plan-phase agent MUST find that marker
and route to `Knowledge/Patterns/v1.6-graph-primitives.md` as the
synthesis anchor.

## v1.7-A CDEEP forward-reference

When v1.7-A binds code-atom semantics (per SPEC §6 Open Q7 LOCKED
vocabulary-divergence contract — vocabulary-level divergence is
intentional; mechanism-level consistency is preserved), it MUST cite
this doc as the v1.6 vault-atom upstream. The atom-layer mechanism
(IMMUTABILITY + supersession via forward-pointer + 240-char structural
cap + flat-bootstrap-then-4-criterion-gate branch organization) is
reusable as the mechanism baseline; the vocabulary (`explanation`,
`opinion`, `tutorial`, `myth-busting`, `case-study`, `comparison`)
is v1.6-A vault-specific and v1.7-A CDEEP may diverge — but the
divergence must be made explicit and routed through the same
SPEC-amendment path that originated this doc.

---

*Audit: `tests/audit-atom-schema.sh` (Phase 72-01). Implementation:
`bin/lib/vault-frontmatter.js::parseFrontmatter` +
`CLAIM_MAX_CHARS` (Phase 72-01 ATOM-01). Upstream edge contract:
`references/vault-edges.md` ## Inverse Pairs row 8 (`derived-from`
↔ `derives`).*
