Installer: pre-install CLAUDE.md conflict analysis (surface user-edited sections before overwrite)

[virtualian]

Summary

Before overwriting ~/.claude/CLAUDE.md with a new release template, the installer should diff the user's current file against the outgoing template and surface any user-edited content that would be lost. Silent overwrites of runtime edits are data loss — and the #111 backport exists because 14KB of runtime drift accumulated silently between PR #101 (Apr 6) and Apr 14. Without this feature, the next time someone makes runtime improvements, the same gap re-appears.

This is the "sophisticated" companion to #126 (preserve @-imports). Where #126 is narrow and mechanical (preserve a specific class of line at the top), this one is a full content-diff and merge workflow.

Proposed behaviour

1. Read current ~/.claude/CLAUDE.md and the release template.
2. Section-diff by ## / ### headings, and by line-hash for prose.
3. Classify each section:
   • Template section the user has modified — they have custom content that would be overwritten
   • Template section the user has removed entirely — user opted out of this feature
   • User-added section not in the template — purely user content, must be preserved
4. Present the diff to the user with options:
   • Merge (three-way merge with manual conflict resolution)
   • Accept template (lose user edits — current default behaviour)
   • Keep current (skip the write — user will upgrade manually later)
5. Block install/upgrade until user resolves, unless one of:
   • --force-template — accept template silently (equivalent to current behaviour)
   • --keep-current — skip CLAUDE.md write silently
   • --merge-auto — attempt a three-way merge and fail loudly on conflicts

Why

Users routinely edit CLAUDE.md as part of normal learning-cycle iteration — this is how #111 came to exist. The runtime had 14KB of divergence from the release template for weeks before anyone noticed. Any future runtime improvement faces the same risk: valuable edits accumulate in ~/.claude/CLAUDE.md, then a reinstall silently destroys them.

Scope

This is design-heavy — probably needs its own plan doc in Plans/ before implementation. The section-diff tooling overlaps with what Tools/lint-*.ts proposed in #111 (cross-doc consistency check). Consider factoring shared primitives.

Out of scope

• Diff for files other than CLAUDE.md (Algorithm, PRDFORMAT, etc.) — those are binary-copy files, not user-editable in the same sense
• Automatic merging — start with surface-and-ask; auto-merge is a later refinement

Related

• Backport runtime Algorithm v3.7.0 + CLAUDE.md improvements to Releases/v4.0.3+/ #111 — backport that exposed the gap
• Installer: preserve user-added @-imports in CLAUDE.md across install/upgrade #126 — sibling preserve-imports issue (narrow, mechanical counterpart to this)
• Automated MEMORY migration shim for v4.0.2 → v4.0.3+ upgraders #107 — MEMORY migration shim, same class of upgrade-path correctness concern

[virtualian]

Status update: the minimal safe-overwrite subset of this issue shipped via #134 (merged). What's now live in Releases/v4.0.3+/.claude/PAI/Tools/preserve-claudemd.ts:

• Timestamped (ISO-ms) backup of ~/.claude/CLAUDE.md to CLAUDE.md.bak.{stamp} whenever BuildCLAUDE.build() is about to write non-identical content
• Backup is skipped on byte-identical rebuilds (common case) and on fresh installs (no pre-existing file)
• stderr drift summary: [preserve-claudemd] drift: +N -M lines
• Backup path logged to stderr so users can recover manually

Still open in this issue (deferred, needs a plan doc first):

• Section-diff classification by ## / ### headings and line-hash for prose
• Three-way merge workflow with manual conflict resolution
• Interactive prompt with Merge / Accept-template / Keep-current options
• --force-template, --keep-current, --merge-auto CLI flags
• Block-install-until-resolved behavior

Keeping this issue open as the tracker for that remaining design work. The minimal subset was confirmed out-of-scope for a straight fix because the issue author flagged it as design-heavy.