feat(store): self-describing HEAD format with typed read/write API (#163)

Muse HEAD file format --------------------- Before: bare path, no type tag refs/heads/main

After: self-describing, explicit type prefix ref: refs/heads/<branch> — symbolic ref (on a branch) commit: <sha256> — detached HEAD (direct commit)

The `ref:` prefix is adopted from Git because a file that can hold two semantically different things should declare which one it holds. The `commit:` prefix for detached HEAD is a Muse extension — Git stores a bare SHA, which is ambiguous (SHA-1? SHA-256?). Muse makes the type explicit and leaves room for future algorithm prefixes without changing the parsing rule.

Changes ------- muse/core/store.py: - HeadState = SymbolicHead | DetachedHead (TypedDict union) - read_head(repo_root) → HeadState (typed parser, raises on malformed) - read_current_branch(repo_root) → str (raises ValueError in detached state) - write_head_branch(repo_root, branch) (writes "ref: refs/heads/<branch>") - write_head_commit(repo_root, commit_id) (writes "commit: <sha256>")

Write sites updated (4): muse/cli/commands/init.py, checkout.py, clone.py, tools/git2muse.py

Read sites updated (80+): Every muse/cli/commands/*.py that had the inline `(root / ".muse" / "HEAD").read_text().strip().removeprefix("refs/heads/")` pattern is replaced with `read_current_branch(root)`.

muse/plugins/bitcoin/_loader.py: dead local `read_current_branch` deleted. btc_*.py commands: import moved from _loader to muse.core.store.

Shell plugin (tools/omzsh-plugin/muse.plugin.zsh): _muse_parse_head updated — now matches "ref: refs/heads/" and "commit: " prefixes instead of heuristic shape checks.

Tests (20 fixture writes + all assertions): Every `write_text("refs/heads/…")` in tests/ updated to the new format.

Verification: mypy 0 errors · typing_audit 0 violations · 2504 tests green

Co-authored-by: Gabriel Cardona <gabriel@tellurstori.com>

G Gabriel Cardona <cgcardona@gmail.com> · 3d ago Mar 21, 2026 · f7645c07 · parent 3ed08abf

122

files changed

342

files in snapshot

Files Changed 342 in snapshot

~122

~ muse/cli/commands/agent_map.py .py

~ muse/cli/commands/annotate.py .py

~ muse/cli/commands/api_surface.py .py

~ muse/cli/commands/archive.py .py

~ muse/cli/commands/bisect.py .py

~ muse/cli/commands/blame.py .py

~ muse/cli/commands/branch.py .py

~ muse/cli/commands/breakage.py .py

~ muse/cli/commands/btc_balance.py .py

~ muse/cli/commands/btc_check.py .py

~ muse/cli/commands/btc_compare.py .py

~ muse/cli/commands/btc_consolidate.py .py

~ muse/cli/commands/btc_dust.py .py

~ muse/cli/commands/btc_fee.py .py

~ muse/cli/commands/btc_halving.py .py

~ muse/cli/commands/btc_hodl.py .py

~ muse/cli/commands/btc_mempool.py .py

~ muse/cli/commands/btc_moon.py .py

~ muse/cli/commands/btc_oracle.py .py

~ muse/cli/commands/btc_pnl.py .py

~ muse/cli/commands/btc_privacy.py .py

~ muse/cli/commands/btc_provenance.py .py

~ muse/cli/commands/btc_stack.py .py

~ muse/cli/commands/btc_strategy.py .py

~ muse/cli/commands/btc_utxos.py .py

~ muse/cli/commands/btc_whale.py .py

~ muse/cli/commands/cadence.py .py

~ muse/cli/commands/check.py .py

~ muse/cli/commands/checkout.py .py

~ muse/cli/commands/checkout_symbol.py .py

~ muse/cli/commands/cherry_pick.py .py

~ muse/cli/commands/clone.py .py

~ muse/cli/commands/clones.py .py

~ muse/cli/commands/code_check.py .py

~ muse/cli/commands/code_query.py .py

~ muse/cli/commands/codemap.py .py

~ muse/cli/commands/commit.py .py

~ muse/cli/commands/compare.py .py

~ muse/cli/commands/contour.py .py

~ muse/cli/commands/core_blame.py .py

~ muse/cli/commands/coupling.py .py

~ muse/cli/commands/coverage.py .py

~ muse/cli/commands/dead.py .py

~ muse/cli/commands/density.py .py

~ muse/cli/commands/deps.py .py

~ muse/cli/commands/detect_refactor.py .py

~ muse/cli/commands/diff.py .py

~ muse/cli/commands/fetch.py .py

~ muse/cli/commands/find_phrase.py .py

~ muse/cli/commands/forecast.py .py

~ muse/cli/commands/grep.py .py

~ muse/cli/commands/harmony.py .py

~ muse/cli/commands/hotspots.py .py

~ muse/cli/commands/impact.py .py

~ muse/cli/commands/index_rebuild.py .py

~ muse/cli/commands/init.py .py

~ muse/cli/commands/instrumentation.py .py

~ muse/cli/commands/intent.py .py

~ muse/cli/commands/invariants.py .py

~ muse/cli/commands/languages.py .py

~ muse/cli/commands/lineage.py .py

~ muse/cli/commands/log.py .py

~ muse/cli/commands/merge.py .py

~ muse/cli/commands/midi_check.py .py

~ muse/cli/commands/midi_compare.py .py

~ muse/cli/commands/midi_query.py .py

~ muse/cli/commands/motif_detect.py .py

~ muse/cli/commands/note_blame.py .py

~ muse/cli/commands/note_hotspots.py .py

~ muse/cli/commands/note_log.py .py

~ muse/cli/commands/notes.py .py

~ muse/cli/commands/piano_roll.py .py

~ muse/cli/commands/plan_merge.py .py

~ muse/cli/commands/plumbing/commit_graph.py .py

~ muse/cli/commands/plumbing/commit_tree.py .py

~ muse/cli/commands/plumbing/ls_files.py .py

~ muse/cli/commands/plumbing/pack_objects.py .py

~ muse/cli/commands/plumbing/rev_parse.py .py

~ muse/cli/commands/pull.py .py

~ muse/cli/commands/push.py .py

~ muse/cli/commands/query.py .py

~ muse/cli/commands/query_history.py .py

~ muse/cli/commands/reserve.py .py

~ muse/cli/commands/reset.py .py

~ muse/cli/commands/revert.py .py

~ muse/cli/commands/rhythm.py .py

~ muse/cli/commands/scale_detect.py .py

~ muse/cli/commands/semantic_cherry_pick.py .py

~ muse/cli/commands/shard.py .py

~ muse/cli/commands/show.py .py

~ muse/cli/commands/stable.py .py

~ muse/cli/commands/stash.py .py

~ muse/cli/commands/status.py .py

~ muse/cli/commands/symbol_log.py .py

~ muse/cli/commands/symbols.py .py

~ muse/cli/commands/tag.py .py

~ muse/cli/commands/tempo.py .py

~ muse/cli/commands/tension.py .py

~ muse/cli/commands/velocity_profile.py .py

~ muse/cli/commands/voice_leading.py .py

~ muse/core/store.py .py

~ muse/core/worktree.py .py

~ muse/plugins/bitcoin/_loader.py .py

~ tests/test_annotate_command.py .py

~ tests/test_cli_auth.py .py

~ tests/test_cli_fetch_push.py .py

~ tests/test_cli_hub.py .py

~ tests/test_cli_new_commands.py .py

~ tests/test_cli_plumbing.py .py

~ tests/test_cli_remote.py .py

~ tests/test_code_invariants.py .py

~ tests/test_core_bisect.py .py

~ tests/test_core_blame.py .py

~ tests/test_core_coverage_gaps.py .py

~ tests/test_core_gc.py .py

~ tests/test_core_pack.py .py

~ tests/test_core_query_engine.py .py

~ tests/test_core_store.py .py

~ tests/test_core_workspace.py .py

~ tests/test_core_worktree.py .py

~ tools/git2muse.py .py

~ tools/omzsh-plugin/muse.plugin.zsh .zsh

← Older Oldest on main

All commits

Newer → Latest on main

feat(store): self-describing HEAD format with typed read/write API (#163)

0 comments