fix(renderer): make root CLAUDE.md mergeable instead of full-overwrite#105
Merged
Conversation
The root CLAUDE.md was written as a static full-overwrite pointer (_CLAUDE_POINTER) and excluded from MERGEABLE_FILES, so every render (deep-scan, finalize, archie init, viewer regen) destroyed any hand-written root CLAUDE.md guidance. - Add CLAUDE.md to MERGEABLE_FILES so it routes through render_mergeable, which owns only the block between archie:generated markers and preserves everything outside it. - Drop the top-level H1 from _CLAUDE_POINTER: it is now appended below the project's existing body, so a second H1 would be wrong. It becomes an "## Archie Architecture Context" section. - Route render_outputs (archie init / serve adapter) through render_mergeable too — it wrote every file with a blind write_text, the same clobber bug. - Refresh stale "full-overwrite / static pointer / never mergeable" comments. - Sync npm-package/assets/renderer.py from canonical. - Add regression test: a hand-authored root CLAUDE.md survives a render, the pointer lands below it inside markers, and re-render is idempotent. finalize.py and the standalone main() both key off renderer.MERGEABLE_FILES + render_mergeable, so all three production write paths are fixed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When
/archie-deep-scan(or any render via.archie/renderer.py,archie init, finalize, or the viewer regen) runs, Archie overwrites the rootCLAUDE.mdwith a short throwaway pointer toAGENTS.md, destroying any hand-written guidance that previously lived there.Root cause
In
renderer.py,AGENTS.mdwas the only mergeable file (MERGEABLE_FILES = frozenset({"AGENTS.md"})). The rootCLAUDE.mdwas written as a static, full-overwrite_CLAUDE_POINTER(a# CLAUDE.mdH1 document), never routed throughrender_mergeable. The marker-merge machinery already existed and was used forAGENTS.mdand per-folderCLAUDE.mdfiles — just not the rootCLAUDE.md.The CLI adapter
render_outputs(archie init/ serve) was a second instance of the same bug: it wrote every file with a blindwrite_text, clobbering bothCLAUDE.mdandAGENTS.md.Fix
MERGEABLE_FILESnow includesCLAUDE.md→ it routes throughrender_mergeable, which owns only the block betweenarchie:generatedmarkers and preserves all hand-authored content outside it._CLAUDE_POINTERdrops its top-level# CLAUDE.mdH1 (it's appended below the project's existing body now — a second H1 would be wrong) and becomes an## Archie Architecture Contextsection.render_outputsroutes mergeable files throughrender_mergeable, matching whatfinalize.pyand the standalonemain()already do.npm-package/assets/renderer.pyfrom canonical (verify_sync.pypasses).finalize.py(deep-scan Step 8) and the standalonemain()(Step 6 / viewer regen) both key offrenderer.MERGEABLE_FILES+render_mergeable, so all three production write paths are fixed by this change.Verification
test_serve_command.pyfails — pre-existing, missing optionalfastapi/starlette; unrelated.)CLAUDE.mdsurvives a render, the pointer lands below it inside markers, and re-render is idempotent.main()(thepython3 .archie/renderer.py <root>path): hand-authored body preserved →CLAUDE.md: appended Archie block (user content preserved); re-render →CLAUDE.md: updated Archie block; exactly one marker pair; byte-identical on the idempotent re-run.🤖 Generated with Claude Code