0041: In-repo vaults sync on a dedicated branch
- Status: accepted
- Date: 2026-10-19
- Amends: 0019 (hooks do not run on vault-branch commits)
- Amended by: 0046 (the branch-mode push is the compare-and-swap for privilege writes; receive runs the git history check of policy slots)
- Builds on: 0004, 0006, 0010
Context
An in-repo vault was the directory .vaultfold/ committed on whatever
code branch was checked out, and sync pushed HEAD to that branch. On
first real use (2026-10-19) the working branch of a client repository was
protected by a GitHub ruleset (pull request and status checks required,
no bypass), so every sync push would have been rejected, and the
repository's pre-commit path-classification hook refused init's own
commit. Protected code branches are normal in teams.
There was a deeper mismatch too: secrets have one timeline, but a vault on code branches forks and merges with the code, so branches can hold different event sets and a vault write waits for a code review that adds nothing to integrity (events are signed, ADR 0006).
Ben and Hannes worked around it by hand with an orphan branch vaultfold
checked out in an extra worktree. Ben decided on 2026-10-19 (agentboard
ticket 01M5BK83N4X22JKC1BG262EA3V) that in-repo vaults sync on a
dedicated branch by default. The details are in the OpenSpec change
vault-sync-branch.
Decision
- An in-repo vault lives on a dedicated orphan branch,
vaultfoldby default, recorded asbranchinvault.toml. The branch holdsvault.tomland the vault directory (.vaultfold/), the same layout as the manual setups. - vaultfold reads and writes that branch with git plumbing only: fetch
into a private ref,
cat-file,hash-object --no-filters, a private temporary index,commit-tree, a non-forced push. No worktree, no checkout, no commit on a code branch, and repository hooks are disabled for these invocations (an emptycore.hooksPathandpush --no-verify). Commit signing still followscommit.gpgSign. - The local copy is a mirror directory under the data directory; git objects and the private ref live in the code repository's common git directory, so the user's repository configuration applies. Each sync makes one commit on the fetched tip adding the new files: history is linear and the "merge" is a tree union, which ADR 0004's write-once paths make conflict-free.
- Same-branch mode stays, chosen explicitly (
same_branch = true); vaults created before this decision keep it until migrated withvaultfold vault migrate, which also adopts the manual worktree setups unchanged. initanddoctordetect branch rules that would block sync (throughghwhen available, otherwise from the forge's push rejection), andvaultfold vault removeunregisters a vault.- Init never installs a hook for the vault branch and never writes into a
hooks directory the repository tracks (
core.hooksPathinside the work tree); it prints the line to add to the repository's own hook instead. - The recommended forge protection for the vault branch is a push-restriction ruleset (members only, no force push, no deletion, no pull request requirement) plus the CI verify action on pushes to the branch.
Consequences
- In-repo vaults work in repositories with protected code branches and strict commit hooks, and every code branch, worktree and CI checkout sees the same vault.
- The vault is no longer in the work tree, so it is no longer copied
into build contexts with the code; it is still in
.gitonce fetched, and hygiene now checks that.gitis excluded from Docker contexts. vault.tomlon the code branch must be committed through the repository's normal flow for teammates to find the vault; until then a fresh clone discovers it from thevaultfoldbranch.- Older vaultfold versions refuse a
vault.tomlwith the new keys, which forces teammates to upgrade instead of syncing a stale copy. - ADR 0019's rule that hooks run as configured now applies to same-branch and standalone vaults only.
- Forge rules on the vault branch prevent writes by non-members; they remain an extra layer, never the authority (ADR 0006).
Alternatives considered
- Keep same-branch as the default and document protected-branch workarounds. Rejected by the decision: it keeps vault writes behind code review and the vault forked across code branches.
- A dedicated branch checked out in a worktree (the manual setup). Rejected as the product: an extra directory per repository, hooks still run, and Windows users have to manage worktree paths.
- A private bare repository per vault. Rejected: it would not see
includeIf-scoped configuration (per-client SSH keys and identities) or the repository's remote settings, against the purpose of ADR 0019. - Reading the vault straight from git objects with no mirror. Rejected: a git process on every command, and a signed event could be lost between write and ref update.
--force-with-leasepushes. Rejected: a non-forced push of a commit built on the fetched tip is already a compare-and-swap, and a lease would permit a non-fast-forward.