gabriel / muse public
docs fix/78-phase4-stale-agent-md-references #1 / 1
AI Agent gabriel · 5 hours ago · Oct 21, 2026 · Diff

docs: complete muse#78 Phase 4 — regenerate muse's own CLAUDE.md, fix last stale reference

Phases 1-3 (canonical agent-config source moved to .museagent.md, with auto-migration) landed back in v0.2.0-nightly.3. Phase 4 (the final workspace-wide sweep) was left incomplete per the ticket's own closing comment: "the workspace root's own CLAUDE.md still resolves via .muse/agent.md, and Phase 4 ... hasn't been verified complete across every member repo."

Confirmed, ironically, that the muse repo itself -- the one hosting this very ticket -- was the one left behind. muse agent-config status showed `claude` adapter `in_sync: false` here, while the workspace root and musehub were already correctly in sync. Root cause: nothing had re-run `muse agent-config sync --force` in this repo since .museagent.md was introduced, so this repo's own CLAUDE.md still literally read `@../.muse/agent.md` / `@.muse/agent.md` -- stale references into a path that's unconditionally excluded from every snapshot and had long since stopped existing on disk here. This repo also has no .musehooks.toml, so there was no pre-commit gate (`muse agent-config status --fail-if-out-of-sync`, the exact mechanism this ticket's own hooks feature added for this class of drift) to catch it.

Fixed by regenerating: `muse agent-config sync --force` now produces a CLAUDE.md that correctly includes `.museagent.md`. `muse agent-config status` confirms `out_of_sync_count: 0`.

Also fixed the one remaining stale-path reference anywhere in muse/'s docs: docs/issues/derive-semver-tag-from-pep440-version.md (an unrelated, still-open ticket about SemVer tag derivation) referenced `musehub/.muse/agent.md` twice as the target file for an unrelated planned edit. Corrected both to `musehub/.museagent.md` -- a pure path- string fix, no change to that ticket's actual scope or checklist.

Every remaining `.muse/agent.md` reference in muse/ is intentional and expected, not stale: agent_config.py's one-time forward-migration logic (must reference the old path to migrate FROM it), test_cmd_agent_config.py and test_cmd_code_add.py's migration/staging test scenarios (testing behavior at the old path on purpose), and the release notes / agent-guide historical note describing the incident as past fact.

Verified: tests/test_cmd_agent_config.py + tests/test_agent_config_envelope.py (144 tests) pass unchanged -- this is a config-regeneration fix, not a code change, so no new tests were needed; the ticket's own Phase 1-2 tests already cover the underlying mechanism.

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

sha256:3560e411a1bb6dc414bfacc43b7dc7b1bc44897f585f1f36d490096b69556342 sha
sha256:7763f749a1b2845c66db69db1cc9930ad22e4b470c46416280363181780e8ea8 parent
~3 symbols
2 changed · 1216 in snapshot files
sha256:8dff7d5afaa09a159593d7d86d3682158483d42d8abbb6b0c6341b10d2952520 snapshot
~3
symbols modified
2
files changed
1216
files in snapshot
0
dead code introduced
Semantic Changes 3 symbols
~ CLAUDE.md .md
~ docs/issues/derive-semver-tag-from-pep440-version.md .md 3 symbols modified
~ toml automatically
~ Deliverables
~ Suggested approach
Files Changed
~2
1216 in snapshot
~ CLAUDE.md .md
~ docs/issues/derive-semver-tag-from-pep440-version.md .md
← Older Oldest on fix/78-phase4-stale-agent-md-references
All commits
Newer → Latest on fix/78-phase4-stale-agent-md-references

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:3560e411a1bb6dc414bfacc43b7dc7b1bc44897f585f1f36d490096b69556342 --body "your comment"