Audit the git-bridge backup path end-to-end (implementation + docs)
Background
While shipping the musehub#96/#97 --sign fix, scripts/muse-git-backup.sh incremental-muse reported "Nothing new since the last backup" immediately
after pushing 2 new commits to local and staging. The backup's own
"Last bridged commit" did not match either remote's actual tip.
The script's own header comments already document the likely cause: its
MUSE_COPY/MUSEHUB_COPY variables point at disposable copies under
~/dev/copies 2/ (never ~/ecosystem/ directly, per musehub#127), and if
those copies go stale the script silently under-reports rather than erroring.
That's a real gap for something gabriel has flagged as potentially one of
the most valuable pieces of code in the ecosystem — it's the only supported
on/off-ramp between Muse and Git, and a silently-stale mirror defeats the
entire point of having a disaster-recovery backup in a second protocol.
This was deliberately not investigated in the moment — surfaced and parked so episode 04 recording could stay the priority.
Scope
Audit muse bridge git-export and the wrapping
scripts/muse-git-backup.sh, both implementation and documentation:
- Reproduce the staleness — confirm whether
~/dev/copies 2/'s muse/musehub checkouts are actually behind canonical, and by how much. - Root-cause why it fails silently — "nothing new" should be distinguishable from "the copy itself is stale and can't see what's new." Decide whether the script should detect and error/warn on a stale copy rather than reporting false negatives.
- Exercise the bridge fresh, in isolation — spin up throwaway
muse and git repos under
/tmp(not canonical, not the~/dev/copies 2/copies) and drivemuse bridge git-exportdirectly to confirm the underlying Muse→Git conversion itself is correct: commit history, branch mapping, authorship/provenance fields, content fidelity for at least one file per tracked domain type. - Test the git→muse on-ramp direction too, if it exists yet (check
muse bridge --helpfor the reverse command) — the pitch is bidirectional on/off-ramping, so confirm both directions are actually implemented and tested, not just the export side this backup script exercises. - Docs pass — confirm
muse/docs/agent-guide.md's "Git-Bridge Backup" section and anymuse bridgecommand help text match actual behavior; fix anything stale found along the way (per this workspace's own proactive-doc-maintenance convention). - Revisit muse issue #127 (why copies live under
~/dev/copies 2/instead of a.muse-relative path) and muse issue #77 (whether this orchestration should become a first-classmuse bridgecapability instead of a bash script) — both referenced from the git-bridge docs as open questions; this audit is a natural point to make a call on either.
Acceptance criteria
- Clear write-up of what was actually stale and why the script didn't surface it.
- Either: the copies are refreshed and the script re-verified against a real push, or the script itself is fixed to fail loud on a stale copy instead of reporting false negatives (or both).
- At least one clean round-trip test of
muse bridge git-exportagainst fresh/tmprepos, with the actual commands and output captured in the issue as evidence. - Docs updated wherever they were found to be wrong.