muse reflog — Follow-up Items

Background

Issue #47 delivered complete reflog coverage: all ref-moving operations write entries (commit, checkout, branch-create, merge, reset, rebase, cherry-pick, revert, switch, pull, shelf-pop, shelf-apply), lifecycle management (expire/delete/GC), @{N} ref resolution across rev-parse/reset/read/diff/checkout, and a reflog exists subcommand. All 30 test IDs (RL_01–RL_30) are green.

This issue captures the items explicitly deferred from #47 plus extensions that emerged during implementation.

Deferred from #47

1. Relative time syntax (@{1.hour.ago}, @{yesterday})

@{N} resolves by index. Git's reflog additionally supports time-based ref syntax:

HEAD@{1.hour.ago}      → most recent entry older than 1 hour
dev@{yesterday}        → most recent entry before midnight last night
HEAD@{2.days.ago}      → 2 days back

This is particularly ergonomic for agent prompts: "show me what main looked like an hour ago" is more natural than finding the right index. Implementation lives in resolve_reflog_ref() in muse/core/rev_parse.py — add a time-spec branch before the integer-index branch.

2. --format options beyond text/JSON

Currently muse reflog outputs human text or --json. Two additional formats are useful:

• --format oneline — @{N} <short-sha> <operation> per line, machine-parseable without full JSON overhead. Mirrors muse log --oneline.
• --format patch — each entry followed by the diff it introduced, equivalent to muse format-patch output. Useful for generating migration scripts from reflog history.

3. Automatic log compaction

Currently reflog files are append-only, pruned only by age (expire) or manually (delete). For branches with very high churn (e.g. a long-running rebase series with hundreds of fixup commits) the log can grow large before the 90-day window expires.

Compaction would merge consecutive entries with the same operation type into a single summary entry — similar to how muse rebase --squash works at the commit level. This keeps log files bounded by activity density, not just age.

4. Remote reflog sharing

Reflogs are currently local-only. For teams on a shared MuseHub remote, a clone has no reflog — a pull starts history from zero. The correct design mirrors the symlog remote sharing plan:

• muse push optionally bundles .muse/logs/ alongside commits.
• muse pull merges incoming reflog entries (append-only, no conflicts).
• Per-ref entries are namespaced by remote on the receiving side to avoid collisions.

5. Reflog for tags

The current implementation writes entries for branch refs (refs/heads/*) only. muse tag add and muse release add move refs/tags/* without a trace. A muse reflog --tag v1.0.0 command should show the tag creation and any subsequent re-tagging events.

New items from implementation

6. muse reflog stat [--branch <name>] [--json]

Summary statistics for a branch reflog: total entries, operation breakdown (commit/reset/merge/rebase/…), most active author, first and last timestamps, number of resets (indicator of how often the branch was "undone"). Useful context for agents deciding whether a branch is stable enough to merge.

7. muse reflog diff @{N} @{M} [--json]

Currently muse diff @{N} HEAD works. But diffing two arbitrary reflog states requires manual SHA resolution. A dedicated muse reflog diff @{N} @{M} command makes point-in-time comparisons first-class, resolving both specs from the same branch's reflog automatically.

8. muse reflog anchor [--json]

Given a commit ID, return all @{N} indices (across all branches) where that commit appears in the reflog. Answers: "how did I get to this commit, and from how many different paths?" Useful for post-mortem analysis of complex rebase sequences.

9. Reflog entries for muse worktree add / muse worktree remove

Creating or removing a linked worktree moves refs but leaves no reflog trace. These operations should append entries to the worktree's HEAD log so the full ref history is preserved regardless of which worktree triggered the move.

10. muse reflog watch [--branch <name>] [--json]

Stream reflog entries as they are written — a live tail of ref movements. Useful for agents monitoring a long-running operation (e.g. an automated rebase series) without polling muse reflog --json in a loop.