haft

Teams & git

Haft is local-first. Each project checkout uses a local SQLite database, while readable files under .haft/ can be reviewed with the code in git. This is useful for review and partial exchange. It is not a distributed project database.

What works today

  • Reviewable Haft records and specifications can travel in the same pull request as the code they explain.
  • haft sync can import supported artifact projections into the local SQLite store.
  • haft spec sync handles the separate specification edition path.
  • Structured blocks preserve supported typed data; older files may import as visibly degraded legacy records.
git pull
haft sync
haft spec sync
haft check

Inspect the command output. A partial, malformed, unknown-schema, or conflicting file must remain visible; do not treat a clean subset as proof that every kind of project state replayed.

Review records with the code

Include relevant .haft/ changes in the pull request. Reviewers can inspect the problem, options, decision rationale, scope, invariants, and evidence references beside the implementation. 

git diff main...feature-branch -- .haft/

The record being present does not prove that the code implements it or that its evidence is fresh. Those remain separate review questions.

What v9 does not provide

  • No real-time shared database or background replication.
  • No complete replay of every typed-memory, authority, specification, and lifecycle event through generic haft sync.
  • No automatic semantic winner when branches carry conflicting records.
  • No safe assumption that two worktrees can concurrently share one project ledger.

Current project binding ties one project ID and ledger to one physical checkout root. A second worktree with the same identity can fail exact-root validation. Do not create a new project ID merely to hide that mismatch; it would split the memory instead of solving shared-workspace identity.

A safe team posture

  1. Treat git-tracked Haft files as review and supported exchange surfaces, not as a complete replicated database.
  2. Keep SQLite, WAL/SHM files, indexes, locks, runtime output, and secrets out of git.
  3. Use one canonical local checkout for mutation when the same project identity is involved.
  4. Run the exact sync command for the record family and inspect partial failures.
  5. Recheck current specifications, decisions, and evidence before consequential reliance.

The trade-off

Local-first storage avoids a required server and keeps project data under the user's control. In v9, that simplicity comes at the cost of incomplete multi-worktree and team-runtime collaboration. Git review is useful today; authoritative distributed replay remains future work.

Related pages