Build HistoryStore — opt-in git and mode detection

The pro-m1 foundation card. SwiftGitX 0.4.0 (bundled libgit2, the
pathfinder's pin) joins the one target; new Kanban/Git/ holds
BoardGitMode (pure nearest-.git-wins detection, .git-as-file counts,
NSString ancestor walk), HistoryStore (@MainActor @Observable;
compose() is the tier gate — free tier gets no object, no detection,
no stat), GitRepository (scope-confined SwiftGitX handles: create =
init + HEAD forced to main + whole-tree "Initial board state" commit;
branch reads incl. unborn/detached; path-history ranks), GitIdentity
(derived default as a pure function + repo-local config reader — not
libgit2's merged ladder), and GitPathHistory (Mutex-guarded lazy
ranker). beginSession composes the git state beside the tier and
feeds BoardStore.makeIdentityHistoryRanker; git-mode loads pass the
git-backed IdentityHistoryRanker to BoardLoader. The popover's git
slot resolves a pure five-way matrix: free tier unchanged (absent /
BoardGitNote), Pro mode-aware — Add Git on mode none, honest prose on
repo-nested, read-only branch line on git. Provider binding
unchanged: both tiers still bind native until the undo/redo card.

42 new tests across 8 suites, all repositories built through bundled
libgit2; InertGitTests untouched and green. 2194 tests / 375 suites.

Claude-Session: https://claude.ai/code/session_01SR4XGjmBE16ZUYWpfFHXwY

Kanban/Git/HistoryStore.swift

@@ -0,0 +1,162 @@
+import Foundation
+import os
+
+// MARK: - HistoryStore
+
+/// **A board's git state** (02-architecture.md ▸ Components ▸ HistoryStore): which mode the board
+/// opened in, the repository behind it when there is one, and the two operations that can change
+/// either — the app's own add-git, and nothing else.
+///
+/// ### One per board session, composed under the tier
+///
+/// `compose(boardRoot:tier:)` is the whole gate: **the free tier gets no `HistoryStore` at all**, so
+/// a free-tier session runs no detection, opens no repository, and does not so much as `stat` a
+/// `.git` — "any `.git` is inert … the app never reads history, never commits, never touches `.git`
+/// in any way" (12-editions.md ▸ The free tier and `.git`), which `InertGitTests` pins against real
+/// bytes. Nothing in this type is conditional on a tier, because the tier decided whether the type
+/// exists.
+///
+/// ### What it does not do yet
+///
+/// This is the foundation card of pro-m1: mode, a repository, add-git, and the loader's path-history
+/// ranker. **The provider binding is not part of it** — both tiers still bind
+/// `NativeHistoryProvider` (`AppModel.makeHistoryProvider`), and the consumer of `mode` is the
+/// undo/redo card two cards later, which builds the git `HistoryProviding` implementation over
+/// exactly this object. Auto-commit, commit messages, branch controls, the identity fields, remotes
+/// and `.gitignore` seeding are each their own card and deliberately absent here.
+@MainActor
+@Observable
+public final class HistoryStore {
+
+    /// The board this is the git state of. The board root *is* the repository's working-tree root
+    /// in git mode — that is what mode `git` means.
+    public let boardRoot: URL
+
+    /// **Detected once, at composition, and changed by exactly one thing afterwards.**
+    ///
+    /// "Detection is nearest-`.git`-wins, checked at every board open … never mid-session"
+    /// (06-history-undo.md ▸ Rules). A `git init` run in a terminal under an open board therefore
+    /// takes effect at its *next* open — the watcher does not scan for `.git` appearing, and nothing
+    /// re-runs `BoardGitMode.detect` for the life of this object.
+    ///
+    /// The one deliberate mid-session transition is `addGit()` below: "the rule forbids *discovered*
+    /// flips, never commanded ones."
+    public private(set) var mode: BoardGitMode
+
+    /// The current branch's short name in git mode, `nil` until it has been read (or when there is
+    /// nothing to read).
+    ///
+    /// Filled by `refreshBranch()` rather than at composition, deliberately: composition happens on
+    /// the board-open path, where 02-architecture.md's hang-avoidance doctrine says nothing may
+    /// block, and opening a repository is libgit2 work — small, but work. Detection is a `stat`;
+    /// this is a read, and it waits until the popover actually asks.
+    public private(set) var branch: String?
+
+    /// Whether add-git is in flight — the button's disabled state, and the guard that keeps a double
+    /// click from running `git_repository_init` twice.
+    public private(set) var isAddingGit = false
+
+    /// The last add-git failure, or `nil` if the last attempt succeeded (or there hasn't been one).
+    ///
+    /// Surfaced inline in the popover rather than as a banner: the popover is where the operation
+    /// was asked for and is still open when it answers, and 02-architecture.md's one-shot banner
+    /// vocabulary is for failures of writes the user made *elsewhere*. DESIGN does not settle
+    /// add-git's failure surface either way.
+    public private(set) var lastFailure: GitOperationFailure?
+
+    private static let logger = Logger(subsystem: "dev.rzen.indie.Kanban", category: "git")
+
+    init(boardRoot: URL, mode: BoardGitMode) {
+        self.boardRoot = boardRoot
+        self.mode = mode
+    }
+
+    /// **The tier gate and the open-time detection, in one line** (12-editions.md ▸ The provider
+    /// seam; 06-history-undo.md ▸ Rules ▸ Detection) — called by `AppModel.beginSession` beside the
+    /// entitlement read that supplies `tier`.
+    ///
+    /// `nil` under `.free` means exactly what it says: no git state exists for that session, so no
+    /// caller can accidentally consult one. Under `.pro` the mode is whatever the filesystem says
+    /// right now, and a board that has changed mode since its last open simply opens in the new one
+    /// — "the app just reflects what it finds".
+    ///
+    /// **Adoption needs no step of its own**: a board whose root already carries `.git` lands in
+    /// `.git` here, silently, with no dialog and nothing to confirm — "the repo's presence *is* the
+    /// opt-in" (06 ▸ Rules ▸ Adoption).
+    public static func compose(boardRoot: URL, tier: Tier) -> HistoryStore? {
+        guard tier == .pro else { return nil }
+        let mode = BoardGitMode.detect(boardRoot: boardRoot)
+        logger.debug("board opened in git mode \(mode.rawValue, privacy: .public)")
+        return HistoryStore(boardRoot: boardRoot, mode: mode)
+    }
+
+    // MARK: - Add git
+
+    /// **Opt-in init** (06-history-undo.md ▸ Rules): initializes a repository at the board root and
+    /// immediately commits the whole tree as "Initial board state".
+    ///
+    /// Reachable from one place — the board popover's git section under Pro — and from nowhere else:
+    /// "No silent auto-init, ever", a deliberate pivot from the pathfinder, which initialized a repo
+    /// under every board it opened.
+    ///
+    /// **It flips the open board's mode immediately**, which is the design's one sanctioned
+    /// mid-session transition: "clicking it flips the open board into git mode immediately — the
+    /// popover flows straight into the git controls". The flip is commanded, not discovered, which
+    /// is what distinguishes it from the `git init` a user runs in a terminal under an open board.
+    ///
+    /// Only mode `none` can be added to. Mode `git` has nothing to add, and a repo-nested board is
+    /// one the app "leaves strictly alone" — no nested repo, ever.
+    @discardableResult
+    public func addGit() async -> Bool {
+        guard mode == .none, !isAddingGit else { return false }
+
+        isAddingGit = true
+        lastFailure = nil
+        defer { isAddingGit = false }
+
+        let root = boardRoot
+        // Off the main actor: `git_repository_init` plus a whole-tree stage and commit is real
+        // filesystem work, and the popover it was clicked in stays live while it runs.
+        let outcome = await Task.detached(priority: .userInitiated) {
+            GitRepository.create(at: root)
+        }.value
+
+        switch outcome {
+        case .success(let branchName):
+            mode = .git
+            branch = branchName
+            Self.logger.notice("add-git initialized a repository at \(root.path, privacy: .public)")
+            return true
+        case .failure(let failure):
+            lastFailure = failure
+            Self.logger.error("add-git failed: \(failure.description, privacy: .public)")
+            return false
+        }
+    }
+
+    /// Reads the current branch name into `branch` — the popover's read-only display line, refreshed
+    /// when the popover opens. A no-op outside git mode.
+    public func refreshBranch() async {
+        guard mode == .git else { return }
+        let root = boardRoot
+        branch = await Task.detached(priority: .userInitiated) {
+            GitRepository.branchName(at: root)
+        }.value
+    }
+
+    // MARK: - The loader's history seam
+
+    /// **The git-backed `IdentityHistoryRanker`** (01-storage-format.md ▸ Fractal layout ▸ Rules;
+    /// `BoardLoader.IdentityHistoryRanker`), or `nil` on any board the app manages no git for — the
+    /// free tier and modes `none`/`repoNested` alike, all of which fall through to the ladder's
+    /// remaining rungs (birth date, then traversal order).
+    ///
+    /// **A fresh ranker per ask, deliberately.** Each one computes its map at most once, lazily, and
+    /// only if something actually asks — which is only when a duplicate identity was found, since
+    /// that is the only thing `BoardLoader.dedupeIdentities` consults it for. A ranker cached across
+    /// loads would answer from a history that has since moved; one built per load never can.
+    public var identityHistoryRanker: BoardLoader.IdentityHistoryRanker? {
+        guard mode == .git else { return nil }
+        return GitPathHistory(boardRoot: boardRoot).ranker
+    }
+}