Skip to content

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, vaultfold by default, recorded as branch in vault.toml. The branch holds vault.toml and 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 empty core.hooksPath and push --no-verify). Commit signing still follows commit.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 with vaultfold vault migrate, which also adopts the manual worktree setups unchanged.
  • init and doctor detect branch rules that would block sync (through gh when available, otherwise from the forge's push rejection), and vaultfold vault remove unregisters a vault.
  • Init never installs a hook for the vault branch and never writes into a hooks directory the repository tracks (core.hooksPath inside 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 .git once fetched, and hygiene now checks that .git is excluded from Docker contexts.
  • vault.toml on 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 the vaultfold branch.
  • Older vaultfold versions refuse a vault.toml with 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-lease pushes. 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.