gabriel / muse public
issue-git-bridge-stale-copy-audit.md markdown
63 lines 3.4 KB
Raw
sha256:85fa17e96bc8632c2e155402f5baf389e498a71e441ace4bd50cdd577e9a417c docs: add local source-of-truth for musehub#98 (git-bridge audit) Sonnet 5 1 day ago

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:

  1. Reproduce the staleness — confirm whether ~/dev/copies 2/'s muse/musehub checkouts are actually behind canonical, and by how much.
  2. 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.
  3. Exercise the bridge fresh, in isolation — spin up throwaway muse and git repos under /tmp (not canonical, not the ~/dev/copies 2/ copies) and drive muse bridge git-export directly 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.
  4. Test the git→muse on-ramp direction too, if it exists yet (check muse bridge --help for 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.
  5. Docs pass — confirm muse/docs/agent-guide.md's "Git-Bridge Backup" section and any muse bridge command help text match actual behavior; fix anything stale found along the way (per this workspace's own proactive-doc-maintenance convention).
  6. 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-class muse bridge capability 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-export against fresh /tmp repos, with the actual commands and output captured in the issue as evidence.
  • Docs updated wherever they were found to be wrong.
File History 1 commit
sha256:85fa17e96bc8632c2e155402f5baf389e498a71e441ace4bd50cdd577e9a417c docs: add local source-of-truth for musehub#98 (git-bridge audit) Sonnet 5 1 day ago