Agent UX: pm merge leaves history verify red until manual history-repair — add opt-in post-merge hook / reconcile command #623

Summary

pm merge install (2026.7.20) sets up the field-aware git merge drivers beautifully, but leaves the post-merge reconciliation as a manual step. After any driver merge that re-anchors the history chain, the on-disk item is correct but pm history <id> --verify reports current_item_hash_mismatch and --strict-exit fails until pm history-repair --all is run by hand. For an automated multi-agent workflow (the exact use case the merge drivers target), a merge gate that runs pm history --verify --strict-exit right after git merge gets a false failure, even though no data was lost.

Repro (2026.7.20)

pm init test && pm merge install
ID=$(pm create issue "x" --json | jq -r .id)
git add -A && git commit -qm base && git branch b
# agent A
pm update "$ID" --priority high && pm notes "$ID" --add "A"
git commit -aqm A
# agent B
git checkout -q b
pm update "$ID" --assignee alice && pm notes "$ID" --add "B"
git commit -aqm B
git checkout -q master && git merge b     # driver merges cleanly, exit 0
pm history "$ID" --verify                  # -> verify_failed:current_item_hash_mismatch
pm history-repair --all                    # only now does verify pass
pm history "$ID" --verify                  # ok:true

The merge itself is correct — priority=high, assignee=alice, and both notes all survive (field-level TOON merge works great). The only gap is that verify is red between git merge and history-repair.

Why this matters for agents

The merge drivers exist so concurrent agents on different branches merge without manual conflict resolution. But the merge is only half automatic: every merge must be followed by two manual commands (pm history-repair --all, pm validate --check-history-drift) or history verification stays broken. The driver already knows it re-anchored — it prints that guidance in its output. An agent orchestrating merges has to remember to run repair after every single merge, and a CI merge gate can't just verify.

Proposed fix

Make the reconciliation opt-in-automatable, any of:

1. pm merge install --hook installs a git post-merge hook that runs pm history-repair --all (scoped to items touched by the merge) + drift check, so git merge leaves the workspace verify-clean.
2. A pm merge reconcile convenience command (repair + drift check in one) that the docs point agents to run after merges.
3. The history driver itself performs the reconciliation when it re-anchors, so no follow-up is needed.

Option 1 is the most agent-friendly: after pm merge install --hook, a merge is fully hands-off and any post-merge pm history --verify --strict-exit gate is trustworthy.

Discovered while adopting the 2026.7.20 merge drivers fleet-wide across the pm-* package ecosystem.