docs(proposal): managed git vault lifecycle

[alemhnan]

Summary

This PR proposes making a Git repository URL a first-class Hatchdoor vault source.

Today, Hatchdoor expects an existing local vault directory and optionally synchronizes writes when that directory is already a configured Git checkout. The proposal
explores having Hatchdoor clone the repository into persistent managed storage and own its ongoing pull/push lifecycle.

This is a documentation-only proposal—no runtime behaviour is changed.

Motivation

The goal is to simplify Git-backed deployments by allowing operators to provide a repository URL instead of preparing and mounting a checkout themselves.

The design also considers repositories with multiple independent writers, such as Obsidian users, automation, and other services pushing from separate clones.

Proposed direction

• Preserve the existing local-directory workflow.
• Add pull-only and bidirectional managed Git modes.
• Clone and reuse repositories from persistent storage.
• Pull remote changes at startup and periodically.
• Fetch and reconcile immediately before pushing.
• Retry bounded non-fast-forward races when another writer pushes concurrently.
• Reindex after working-tree changes.
• Preserve dirty files and unpushed commits across restarts and outages.
• Expose repository lifecycle, degraded, and conflict status.
• Preserve conflicting work through a recovery branch rather than force-pushing.
• Optionally support a vault located in a repository subdirectory.

Feedback requested

I would especially appreciate feedback on:

• Whether repository lifecycle should live inside Hatchdoor.
• The proposed pull-only versus bidirectional modes.
• Conflict-preservation branch behaviour.
• Polling and non-fast-forward retry policies.
• Empty-repository bootstrap behaviour.
• Whether vault-subdirectory support belongs in the initial implementation.
• Compatibility with the project’s intended deployment model.

Validation

The proposal was based on the current startup, vault watcher, indexing, write-lock, and Git sync implementation.

AI assistance disclosure

This proposal and PR description were drafted with AI assistance.

• Tool: OpenAI Codex
• Model: gpt-5.6-sol high
• Human involvement: The proposal’s intent, requirements, follow-up questions, and final direction were provided and reviewed by the contributor through an iterative discussion.

No implementation code is included in this PR. The document should be treated as a design proposal for maintainer review, not as a claim that every architectural detail has already been validated in production.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5578687e8c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BattermanZ]

Thanks for putting this together — I’ve read through the proposal and I’m happy with the overall direction.

Managing the repository lifecycle inside Hatchdoor makes sense to me. Pulls and checkouts affect the filesystem, SQLite index, watcher, write locking, revision events, and user-visible status, so keeping that coordination in the application is a good fit. I also like that the existing local-directory workflow remains fully supported and that conflicts preserve work rather than force-pushing or silently choosing a winner.

There is one point I’d like corrected in the proposal: empty-repository bootstrap should not be allowed in pull-only mode. That would create a local commit which Hatchdoor is intentionally unable to push, and a later remote initialization could leave the checkout diverged. Please either restrict bootstrap to bidirectional mode or reject that configuration explicitly.

On vault-subdirectory support: I don’t want to artificially limit the scope if you want to include it in the initial implementation. Please go ahead with it if that is the direction you want to take. The important part is to keep the repository root and vault root distinct internally, canonicalize and validate the configured subdirectory, and ensure all vault operations stay contained within it.

With the pull-only bootstrap contradiction clarified, I’d be comfortable merging this as the agreed design direction.

[alemhnan]

Thanks for the review and for confirming the overall direction. I addressed the requested clarification in commit 8401145:

• empty/unborn repository bootstrap is now explicitly restricted to bidirectional mode;
• git-pull-only plus HATCHDOOR_BOOTSTRAP_EMPTY_REPOSITORY=true is a configuration error;
• an empty/unborn pull-only remote creates no local commit and reports an actionable readiness error;
• the unit and end-to-end verification matrix now covers both valid bidirectional bootstrap and rejected pull-only bootstrap.

I also kept vault-subdirectory support in the proposed initial scope, clarified that repository root and vault root remain distinct, and made canonicalized containment the boundary for all vault operations.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8401145590

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc83fac710

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Revalidate the vault root after every checkout

When a managed repository uses HATCHDOOR_VAULT_GIT_SUBDIR, a later remote commit can replace that directory with a symlink after the startup validation. The lifecycle calls for checkout followed directly by reindexing here, but does not require re-canonicalizing the configured vault root and verifying that it is still below repository_root; current write and asset guards canonicalize vault_root itself, so a symlinked root would make paths outside the checkout appear valid. Require this validation after every checkout/merge and before resuming reads or writes, otherwise a remote update can redirect vault access outside the managed repository.

Useful? React with 👍 / 👎.