ci: helper to move a branch onto the split claim, command and inventory files

[abrichr]

Why

After #1342, #1344 and #1345 land, every open branch that touched claims.yaml, the CAPABILITIES.md command list or public-artifacts.json will conflict with main once. This helper resolves that conflict in one command, so each such PR needs one push instead of a manual rework.

Usage

git fetch origin
git merge origin/main
python scripts/migrate_branch_to_split_files.py
git status
git commit

What it does

It runs while the merge is still in progress and compares your branch with the merge base, so it moves only what your branch changed.

• Claims. Each claim your branch added, changed or removed in claims.yaml goes to packages/flow/claims/<id>.yaml, keeping its wording and comments. It then removes claims.yaml and regenerates docs/VERIFICATION.md and docs/verification.json.
• Commands. Each command your branch added, moved or removed in the old one-line list goes to packages/flow/docs/commands/<group>/<verb>.md. A parenthetical in the old list becomes the file's note, and a capability title it doesn't know gets a new group. For conflict hunks inside "Every command, by capability" only, it takes main's side, then runs scripts/build_command_map.py. Conflicts in map rows or anywhere else are left for you.
• Inventory. It rewrites public-artifacts.json as the path-only list.
• Safety.
  • It never overwrites a claim or command that main also changed; it lists those under "BY HAND".
  • It stages what it resolved, does not commit, and exits 1 if anything is left for you.
  • Each step runs only once main has that format, so the script works whichever of the three PRs have landed.

Verified

I ran a dry run in a scratch worktree, pushing nothing. "Future main" was #1344 (which includes #1342), #1345 and this PR, all on today's main. I merged it into seven open PR branches and ran the helper.

Branch	Conflicts before	Result
flow/deferred-check (#1297)	CAPABILITIES.md, claims.yaml (modify/delete), VERIFICATION.md, verification.json, inventory	all resolved; claims/deferred-report-check.yaml and 03-run-and-answer/deferred.md added
flow/save-response-evidence (#1298)	claims.yaml, both reports, inventory	all resolved; claims/server-response-evidence.yaml added
feat/narration-rules (#1291)	CAPABILITIES.md, inventory	all resolved; narration.md added
claude/crystallize-from-prompt-89950e (#1277)	CAPABILITIES.md, inventory	all resolved; compile-agent.md added
claude/scoreboard-arm7 (#1307)	CAPABILITIES.md, inventory	all resolved; compile-agent.md added
claude/pixel-identity-measure (#1340)	inventory	resolved; its map rows kept
claude/often-missed-oct19 (#1341)	none	nothing to do

Checks on each of the four branches with claim or command changes (#1297, #1298, #1291, #1277):

• No unmerged paths and no conflict markers.
• check_release_consistency.py passes.
• tests/test_validate_claims.py and tests/test_capabilities_map.py pass (31 passed).

On #1307, #1340 and #1341, every line the branch added to CAPABILITIES.md is still present after the migration. The only exception is #1307's old one-line command group, which was converted to a command file as intended. The other three branches added no lines beyond their command group lines.

tests/test_migrate_split_files.py covers the claim split, the old-list parser and the conflict-hunk rule (3 passed).

Savings

One push per affected PR, instead of a manual conflict fix that is often followed by a second push when the first attempt misses a generated file. Each avoided push saves one full PR pipeline run (about 40 jobs). About 13 open PRs touch these files today.

No changes to packages.yml, desktop-release.yml or main.yml.

🤖 Generated with Claude Code