docs: empty-repo hardening notes + verification item

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> (cherry picked from commit d771dbf03575bb60e692ede44110ff17c3043f39)
2026-08-28 20:34:24 +02:00
parent e0748ba351
commit cf093e3178
2 changed files with 12 additions and 0 deletions
@@ -80,10 +80,15 @@ dir(s) via an optional `AttachmentStore` ctor param (defaults to the production
 - Merge: ff-only, no-ff, abort, mid-merge detection (`MERGE_HEAD`), conflicted files
 - Revert: `RevertMergeCommitAsync` (`git revert --no-edit -m 1 <sha>`), `RevertAbortAsync`, `IsMidRevertAsync` (`REVERT_HEAD`, mirrors `IsMidMergeAsync`)
 - `PreviewMergeAsync` (non-destructive check via `git merge-tree --write-tree`), `CountChangedFilesAsync`, rev-parse, is-git-repo
+- Empty repos: `HasHeadCommitAsync` (HEAD resolves to a real commit) and `EnsureHeadCommitAsync` — a fresh `git init` repo (unborn HEAD) gets an empty bootstrap commit via plumbing only (mktree/commit-tree/update-ref), so the user's index and working tree stay untouched; identity is passed inline, so it also works with no git config, and a broken HEAD throws instead of guessing
+- Identity fallback: `CommitAsync` retries once as the ClaudeDo identity when the machine has none configured

 ⚠️ **Revert never resets or rewrites** — it always produces a new commit, because the working
 directory it operates on is shared with other concurrent sessions.

+⚠️ **Git stdin is BOM-less UTF-8** — `Encoding.UTF8` writes a BOM preamble, which git rejects
+as input (`mktree` fails with "input format error", and commit messages would carry it).
+
 ## Schema

 Tables (one per line so parallel migrations don't collide on the same line):