Overview
A solo vault has one hard problem, thinking. A shared vault adds a second, coordination without corruption. Two people editing one note, racing to name the same idea, or independently splitting the same atom will destroy link density and provenance unless the architecture designs the conflict out. This page covers the multi-author layer on top of the architecture in vault-architecture.
Use Git as the substrate, not a file syncing service
File replicators resolve concurrent edits by last write wins, which for a team is silent data loss: two people edit one note, and one person’s paragraph disappears with no record. Git gives a shared vault three things no replicator can.
- A merge model. Edits to different regions of a file merge; edits to the same region surface a conflict for a human instead of vanishing.
- Immutable history. This is what actually enforces the immutable pre-decision section from decision-journals. A hindsight rewrite shows up as a diff against a section that should never have changed.
- Review gates. A second author can check atomicity, sources, and naming before a note lands.
Commit the vault spec and the tooling. Ignore per-user editor state (workspace.json, caches, local trash) and keep shared plugin configuration tracked so the team runs the same templates and queries. A timed auto-commit plugin covers the authors who do not live in a terminal. Branching conventions carry over from git.
Design the conflicts out with atomicity and append conventions
Atomicity is a concurrency discipline as much as a thinking one. Two people editing two atoms never conflict; one 2,000-word note that three people need to touch is a permanent merge hotspot.
- Append-only regions get an append convention. Decision outcomes, map link lists, and daily notes take one bullet per line, newest at the bottom, and never reflow existing lines. Git merges disjoint appends cleanly; a reflow turns a clean append into a conflict.
- Frontmatter keeps a fixed field order, so a one-field change is a one-line diff. Do not auto-bump
modifiedon every keystroke, which manufactures conflicts on otherwise-untouched notes. - Split high-traffic maps early. A map three people edit weekly wants to be three sub-maps, per linking-and-tags.
When a conflict does happen, the note’s author arbitrates, not whoever pulled last.
Hold one naming authority over the namespace
Filenames are the vault’s primary keys. Two authors independently creating compound-interest-beats-linear.md and compound-interest-outpaces-linear-saving.md for one idea splits the link density across two notes that should be one.
Keep a lightweight naming ledger where an author proposes a title before writing when the idea might already exist. Most atoms are obviously new; the ledger exists for the ambiguous minority. One maintainer owns the taxonomy: the domain tag tree, the note-type prefixes, and the map names. A fork between #domain/finance/macro and #domain/macro-finance is expensive to reconcile later.
Renames are a scope-freeze operation. A rename breaks every inbound link until the links are rewritten, so state the path list and the referring notes, get sign-off, then commit the rename and the link updates together so history stays bisectable.
Keep atoms communal and decisions owned
Anyone may improve any atom; permanent notes are the communal core, with contribution history attributed in an append-only authors field rather than reconstructed from the log.
Decision notes have exactly one owner, the person who made the decision. A reviewer may comment on a pre-decision section and never edit it. Active project workspaces and inbox captures can carry a light owner convention so two people are not racing in the same scratch space.
Gate merges on the auditor
Run the auditor as a pull request check. Criticals block merge; warnings are advisory. Map its severities onto the review vocabulary the team already uses so one language covers code and notes, and lead the review comment with the counts before the detail.
Branch per work session rather than per note: atoms are small, and a session’s worth is the reviewable unit. Squash atom pull requests, but preserve decision-note commits, because the timeline of when each section was written is the hindsight defense. Human review covers what the auditor cannot: whether the title is a real claim, whether the atom is one idea, whether the cited source is the right source. A reviewer who has not read the source says the claim looks unsourced rather than asserting it is. Semantic checks are covered in semantic-audit, and pull request mechanics in github-pr-workflow.
Audit on a schedule as well as on every merge
Run the auditor weekly against the main branch and append each run to the log, so the team sees the trend rather than a snapshot. Surface the delta in the weekly review while drift is still cheap to reverse. Schema and framework changes go through the same pull request path as any other change, using the moves in vault-evolution.