next-merge-recovery

name	next-merge-recovery
description	How agents detect and self-heal git merge-conflict markers in the projected NEXT files (`.hero/NEXT.md`, `.hero/next/*.md`) without resorting to hand-resolution.
compatibility	opencode
metadata	{"audience":"any-agent","purpose":"session-handoff","applies_when":"working in a hero repo where `.hero/NEXT.md` or `.hero/next/*.md` may have unresolved merge markers"}

What I do

Stop the agent from hand-resolving merge conflicts in projected NEXT files. These files are graph projections — total-rewrite from local state every Stop hook. Conflict markers in them are noise to be regenerated, not a diff to be merged thoughtfully.

When <<<<<<< markers appear in any of:

• .hero/NEXT.md
• .hero/next/<user>.md
• .hero/next/<user>.local.md

run hero next checkpoint immediately. The command regenerates each file from the local graph, discarding both sides of the conflict cleanly.

Why this matters

hero next migrate-to-projection flips next.projected = true and ships a hero-next git merge driver registered in .git/config by hero install. For clones that have run install, conflicts in these files never produce markers — the driver regenerates the file on merge automatically.

For clones that haven't run install (fresh checkouts, CI runners, teammates picking up the repo for the first time), git falls back to the default merge behavior and writes standard conflict markers. The next Stop-hook firing of hero next checkpoint will catch it and regenerate, but if an agent gets to the file first and tries to hand-resolve, the result is wasted effort plus the very brittleness projection exists to eliminate.

What to do

The instant you see <<<<<<< in one of those paths:

hero next checkpoint

That's it. Don't:

• Open the file and pick a side.
• Run git checkout --ours / --theirs.
• Edit the markers out by hand.
• Try to merge the two halves into a "best of both" version.

The file's content isn't a source of truth — the graph is. Re-deriving from the graph is faster, deterministic, and the correct semantic answer.

Verifying

After hero next checkpoint:

grep -l '<<<<<<<\|=======\|>>>>>>>' .hero/NEXT.md .hero/next/*.md 2>/dev/null

Should print nothing. If markers remain, the projection failed (check the command's stderr) — surface it, don't paper over.

When this doesn't apply

• Conflicts in .hero/specs/*.md or .hero/planning/*.md. These are hand-authored, not projected. Resolve them normally with the usual diff-merge tools.
• Conflicts in .hero/knowledge/*.md. Same — hand-authored.
• Conflicts in .hero/QUEUE.md. Projected, but covered by its own regen path (hero queue write). The same principle applies but the command differs.
• next.projected = false. Pre-migration repos still use the hand-authored NEXT.md flow. Normal merge resolution applies.

See also

• skills/next-handoff-emit/SKILL.md — the companion skill for writing projection state during normal work.
• hero next migrate-to-projection — one-shot to flip a repo into projection mode and capture pre-existing NEXT.md content as graph nodes.
• hero install — registers the hero-next merge driver in .git/config so future merges resolve without markers in the first place.