--- title: "Vault Evolution" slug: "vault-evolution" category: "knowledge-vaults" tags: ["knowledge-vaults", "migration", "schema", "scaling", "refactoring", "maintenance"] status: "stable" last_updated: 2026-08-29 summary: "Grow a vault with four additive moves (new note type, schema migration, layered framework, deprecate to archive) and never rebuild it from scratch." related: ["[[knowledge-vaults/vault-architecture]]", "[[knowledge-vaults/vault-frontmatter-schema]]", "[[knowledge-vaults/rigor-frameworks]]", "[[knowledge-vaults/vault-audit]]", "[[knowledge-vaults/vault-maintenance]]", "[[knowledge-vaults/team-vaults]]", "[[backend/migrations]]"] --- ## Overview Vaults outgrow their designs. A domain expands, a second framework becomes necessary, a note type goes dormant. The failure mode is the rebuild, which severs the link network and discards provenance. The governing rule is add, deprecate, migrate, never rebuild, and there are four moves that cover every legitimate case. The structure being evolved is defined in [[knowledge-vaults/vault-architecture]]. ## Add a note type rather than repurposing an existing one When a new kind of note appears (an experiment atom, a vendor note, a lesson), declare a new type. Never redefine an existing one: repurposing corrupts the audit semantics of every note already carrying that type. The recipe is four steps. Add the type to the spec with its folder, filename pattern, and required fields. Add a template and a schema reference. Create the folder. Run the auditor. Because required fields apply per type, no existing note changes, and the move reverses by deleting the spec block. This is the cheap path and it should be the default answer to "the vault needs to track something new." ## Treat a newly required field as a migration with a backfill Making an optional field required is the one change that touches existing notes. Adding it to the required set instantly fails every note that lacks it, which is correct signal but not a migration. 1. Add the field to the required set, then run the auditor. The resulting list of missing-field findings is the backfill worklist: scoped, finite, and enumerated. 2. Scope freeze the backfill. State the path list, state that the edit is a frontmatter addition and reversible in version control, get sign-off, and apply. 3. Re-run and confirm the count returns to zero. The delta between the two runs is the migration's proof. Never backfill a fabricated value. Writing today's date into `last_verified` on a claim verified two years ago makes the schema vouch for a lie. Leave the field empty and the finding open if the honest value is unknown. This is the same up-and-backfill discipline as a schema change in [[backend/migrations]]. The inverse move is demotion, not deletion: a field that stops being required moves out of the required set and stays valid frontmatter. ## Layer a second framework instead of forking the vault When the domain genuinely splits (a strategy vault that starts hosting engineering decisions, a research vault that starts driving capital decisions), layer the second framework rather than shoehorning or forking. Declare the layered frameworks in the spec, add the second framework's note types additively, and bridge the two with explicit link conventions. Framework-specific rules trigger on prefixes, so they enforce only on the notes that opt in and existing notes are untouched. Add the new framework's queries to the dashboard and drop none of the old ones. Selection and layering criteria are in [[knowledge-vaults/rigor-frameworks]]. Forking into a second vault loses the cross-domain links, which are usually the reason both domains are in one vault. ## Deprecate to the archive; never delete When a note type, folder, or sub-domain goes dormant, move its notes to `99-Archive/` (excluded from the audit and the graph), then remove the type from the spec. Order matters: removing the type first leaves active notes typeless, which trips the untyped-note rule in [[knowledge-vaults/vault-audit]]. Record why the layer was retired in one line. The next reader, often an agent, should not have to reverse-engineer the decision from an empty folder. Scaling down is a legitimate evolution. When the maintenance budget is exceeded, the right move is usually to retire a layer, not to add more structure, per [[knowledge-vaults/vault-maintenance]]. ## Read the trend to see evolution coming The audit log is a trend, and evolution pressure shows up there before it shows up as pain. - A folder outgrowing its design, or a map indexing 50 or more atoms: split into sub-maps additively. - A recurring violation cluster the current rules cannot express: add a custom rule to the spec. - Notes hand-shaped like a second framework's: formalize with the layering move before the informal practice drifts. ## Refuse the rebuild A rebuild severs backlinks, which are the compounding value. It resets version history, which is the hindsight-bias defense behind every decision note. It erases the audit log's memory, so quality drift becomes invisible again. Every need a rebuild appears to serve is met by one of the four moves above, additively and reversibly. If a rebuild happens anyway, carry the archive and the version history forward so the old vault stays recoverable. In a shared vault, all of these moves are pull requests with the auditor as a check, per [[knowledge-vaults/team-vaults]]. ## Related - [[knowledge-vaults/vault-architecture]] - [[knowledge-vaults/vault-frontmatter-schema]] - [[knowledge-vaults/rigor-frameworks]] - [[knowledge-vaults/vault-audit]] - [[knowledge-vaults/vault-maintenance]] - [[knowledge-vaults/team-vaults]] - [[backend/migrations]]