# 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.