Upgrade mode regroups every existing heading and the diff is hard to review #75

Status: Verified during the Pick Your AI rollout (reproduced, or read directly in the code).

Part of epic: Epic: Make README generation safe for existing repositories.

Summary

Upgrade mode demotes existing H2s under a new ## Notes and adds placeholder sections that stay needs-input. No line is dropped, but heading levels change, so diffs such as +108/-73 appear for a header change.

Evidence

• Observed in the Pick-Your-AI PRs (for example docs: add Pick Your AI showcase banner, card, icon and README header Pick-Your-AI/pick-your-ai-catalog-pipeline#85, docs: add Pick Your AI showcase banner, card, icon and README header Pick-Your-AI/pick-your-ai-papers#168).
• R7 stays incomplete in almost every repository because the placeholder sections have no source facts.

Impact

Reviewers cannot tell a safe header addition from a restructure.

Proposed fix

Add a header-only upgrade option, a heading-change summary in the dry run, and a way to supply the missing section facts.

Acceptance criteria

• --no-regroup keeps authored headings.
• The dry run lists heading moves separately from additions.

Tasks

Each task below is a sub-issue.

Prior work

Prior work: open PR #20 (opt-in --allow-t3 and the Pick Your AI family), open #7 and PR #13 (variant J badges), merged PRs #14 to #19 (icon art-direction path, UTF-8 output, registry-free org health and label planning, Windows test portability, footer URL repair) and closed issues #8 to #12. Nothing here duplicates those; where an item is already handled it is linked, not refiled.

Fresh VM verification: not run. Findings were verified on a Windows host; hosted CI is separate evidence.