gabriel / muse public
docs docs/track-snapshot-content-id-migration-plan #1 / 1
AI Agent gabriel · 9 days ago · Jul 7, 2026 · Diff

docs: architectural plan for unified-store snapshot-content-ID migration

Load-bearing, TDD, multi-phase implementation plan for the tool needed to fix the 2 commits found during musehub#134's investigation whose declared snapshot_id never matched their manifest since creation (2026-05-27).

Records why muse code migrate was investigated and ruled out (its snapshot/commit ID recomputation only touches the legacy pre-unified-store layout; the current migrate() orchestrator passes snapshot_id through unchanged), and specs the three-phase replacement: detect-and-correct at the snapshot layer, cascade-and-resign at the commit layer, then reuse the existing generic ref/reflog rewrite passes unchanged.

No implementation yet -- this is the architectural record, written before any code, per explicit instruction.

sha256:24d9cb81ac1dd071e5d98862c740ad101180588361b4f96a790af79a99aed901 sha
+16 symbols
1130 changed · 1130 in snapshot files
sha256:5212b28fe97a797213b6af86fbc997dc469307c23fa3420e0406d6195c37d92b snapshot
+16
symbols added
1130
files changed
1130
files in snapshot
0
dead code introduced
Semantic Changes 16 symbols
+ Unified-store snapshot-content-ID migration: recompute-and-cascade repair for commits whose declared snapshot_id never m section Unified-store snapshot-content-ID migration: recompute-and-cascade repair for commits whose declared snapshot_id never m L1–288
+ Acceptance criteria section Acceptance criteria L258–277
+ Architecture section Architecture L118–239
+ Phase 1 — migrate_snapshot_content_ids() (detection + correction, snapshot layer) section Phase 1 — migrate_snapshot_content_ids() (detection + correction, snapshot layer) L122–158
+ code variable variable code L127–133
+ Phase 2 — cascading commit rewrite + re-sign (commit layer) section Phase 2 — cascading commit rewrite + re-sign (commit layer) L158–191
+ Phase 3 — ref / reflog integration section Phase 3 — ref / reflog integration L191–206
+ Phase 4 — full dry-run against scratch copies section Phase 4 — full dry-run against scratch copies L206–221
+ Phase 5 — verify the corrected scratch copy round-trips cleanly section Phase 5 — verify the corrected scratch copy round-trips cleanly L221–231
+ Phase 6 — staging cutover section Phase 6 — staging cutover L231–239
+ Background section Background L11–70
+ Non-negotiable invariants section Non-negotiable invariants L87–118
+ Open questions to resolve before implementation starts section Open questions to resolve before implementation starts L239–258
+ Out of scope section Out of scope L277–288
+ Status: architectural intention, not yet implemented section Status: architectural intention, not yet implemented L3–11
+ Why this must be TDD and why it's load-bearing section Why this must be TDD and why it's load-bearing L70–87
Files Changed
+1130
1130 in snapshot
+ .coverage .coverage
+ .museattributes .museattributes
+ .museignore .museignore
+ CLAUDE.md .md
+ README.md .md
+ dev-setup.sh .sh
+ pyproject.toml .toml
← Older Oldest on docs/track-snapshot-content-id-migration-plan
All commits
Newer → Latest on docs/track-snapshot-content-id-migration-plan

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:24d9cb81ac1dd071e5d98862c740ad101180588361b4f96a790af79a99aed901 --body "your comment"