docs: sha256:09d4b6592647086ae8fe7356c0369b867aba50c718c3ae0b9622088c0490db3a · gabriel/muse

docs: add local source-of-truth for muse#104 -- empty-dir-sentinel comprehensive fix roadmap

Parent/roadmap ticket linking #101, #102, #103 (and the already-shipped 0.2.1rc8 clobber fix) as four symptoms of one root design flaw: the 0.2.1 refactor that replaced the old non-colliding 'dir:' sentinel string with EMPTY_DIR_OID = blob_id(b'') reintroduced ambiguity between 'this is a tracked empty directory' and 'this is a genuinely empty file' -- both hash identically, and object_id equality is the only discriminator used anywhere in the codebase.

Documents the full blast radius (19 call sites across 6 files trusting object_id == EMPTY_DIR_OID, plus 8 files independently constructing directories= values), presents two design options (revert to a non-colliding sentinel vs. an explicit kind discriminator field) with a recommendation, and lays out a 6-phase TDD roadmap with an explicit multi-part acceptance gate -- not closeable until all four child symptoms are fixed, verified with regression tests, and confirmed resolved in all three real-world repos that surfaced this session (~/thoughts, ~/ecosystem/presentations/build-with-muse, ~/ecosystem/musehub).

Co-Authored-By: Claude Sonnet 5 <[email protected]>

symbols added

file changed

1206

files in snapshot

dead code introduced

Semantic Changes 9 symbols

~ docs/issues/issue-104-empty-dir-sentinel-roadmap.md .md 9 symbols added

+ Empty-directory sentinel: one root design flaw, four discovered symptoms — comprehensive fix roadmap section Empty-directory sentinel: one root design flaw, four discovered symptoms — comprehensive fix roadmap L1–216

+ Definition of done — the actual acceptance gate section Definition of done — the actual acceptance gate L201–216

+ Design decision required (Phase 2) — not yet made, needs a call section Design decision required (Phase 2) — not yet made, needs a call L111–139

+ Linked tickets section Linked tickets L8–16

+ Multi-phase TDD roadmap section Multi-phase TDD roadmap L140–200

+ Problem statement — the one root flaw behind all four section Problem statement — the one root flaw behind all four L17–110

+ Blast radius — every place trusting the ambiguous discriminator section Blast radius — every place trusting the ambiguous discriminator L80–110

+ This is a regression, not an original design flaw section This is a regression, not an original design flaw L34–57

+ Why patching each symptom individually doesn't work section Why patching each symptom individually doesn't work L58–79

Files Changed

1206 in snapshot

+ docs/issues/issue-104-empty-dir-sentinel-roadmap.md .md

← Older Oldest on task/muse-104-issue-doc

All commits

Newer → Latest on task/muse-104-issue-doc

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:09d4b6592647086ae8fe7356c0369b867aba50c718c3ae0b9622088c0490db3a --body "your comment"