docs(merge): recommend pm merge reconcile (2026.7.22) over raw history-repair

.agents/pm/history/pm-github-wpit.jsonl

@@ -0,0 +1,3 @@
+{"ts":"2026-07-22T19:41:57.764Z","author":"claude-opus-20260722","op":"create","patch":[{"op":"add","path":"/metadata/id","value":"pm-github-wpit"},{"op":"add","path":"/metadata/title","value":"Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs"},{"op":"add","path":"/metadata/description","value":"pm-cli 2026.7.22 shipped GH-623 pm merge reconcile, a purpose-built audited post-merge reconciliation that previews affected streams (dry-run), applies field-aware repair, and leaves pm history --verify plus pm validate green in one command. Verified end-to-end on a 2-branch concurrent edit: the field-aware driver unions notes and scalar fields with zero conflicts, then reconcile re-greens the hash chain with zero data loss (both authors content and attribution preserved). The Multi-agent merge safety README section (added in the 5cx1 rollout) previously recommended the blunt history-repair all-items primitive; this updates it to the dry-run then apply then verify reconcile workflow and links the authoritative upstream MERGE_SAFETY guide. Fleet fan-out from canary pm-beads#42."},{"op":"add","path":"/metadata/type","value":"Issue"},{"op":"add","path":"/metadata/status","value":"open"},{"op":"add","path":"/metadata/priority","value":2},{"op":"add","path":"/metadata/tags","value":["agent-ux","docs","multi-agent"]},{"op":"add","path":"/metadata/created_at","value":"2026-07-22T19:41:57.764Z"},{"op":"add","path":"/metadata/updated_at","value":"2026-07-22T19:41:57.764Z"},{"op":"add","path":"/metadata/author","value":"claude-opus-20260722"},{"op":"add","path":"/metadata/acceptance_criteria","value":"README Multi-agent merge safety section recommends pm merge reconcile with a dry-run preview, apply, and pm history --verify plus pm validate confirmation; links upstream MERGE_SAFETY.md; CI green; PR reviewed by bots."}],"before_hash":"3cc22dff72be7b14824654a7a64ea62b04799939b2fee54c1b5f52ca60bf6df0","after_hash":"4f249d945d884ea2a8a3b6fd5419d4c46f31a7515eac2dcf77d4c453068f27bb","message":""}
+{"ts":"2026-07-22T19:41:58.171Z","author":"claude-opus-20260722","op":"note_add","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-22T19:41:58.171Z"},{"op":"add","path":"/metadata/notes","value":[{"created_at":"2026-07-22T19:41:58.170Z","author":"claude-opus-20260722","text":"Fan-out from canary unbraind/pm-beads#42. README Multi-agent merge safety section closing recommendation migrated to the pm merge reconcile dry-run->apply->verify workflow; links upstream docs/MERGE_SAFETY.md; keeps history-repair --all as a lower-level primitive."}]}],"before_hash":"4f249d945d884ea2a8a3b6fd5419d4c46f31a7515eac2dcf77d4c453068f27bb","after_hash":"66c333619a46d6911cfd49ee70558932273ac169164ff747da4b9fbf8848ead5"}
+{"ts":"2026-07-22T19:41:58.592Z","author":"claude-opus-20260722","op":"close","patch":[{"op":"replace","path":"/metadata/updated_at","value":"2026-07-22T19:41:58.592Z"},{"op":"replace","path":"/metadata/status","value":"closed"},{"op":"add","path":"/metadata/closed_at","value":"2026-07-22T19:41:58.591Z"},{"op":"add","path":"/metadata/close_reason","value":"Docs updated to recommend the 2026.7.22 pm merge reconcile workflow (fleet fan-out from pm-beads#42)."}],"before_hash":"66c333619a46d6911cfd49ee70558932273ac169164ff747da4b9fbf8848ead5","after_hash":"89f3c7f2ed193a9125ce8dfa12f55a1cb6810090451dc827840df1cc6d0a2cde"}

.agents/pm/issues/pm-github-wpit.toon

@@ -0,0 +1,16 @@
+id: pm-github-wpit
+title: Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs
+description: "pm-cli 2026.7.22 shipped GH-623 pm merge reconcile, a purpose-built audited post-merge reconciliation that previews affected streams (dry-run), applies field-aware repair, and leaves pm history --verify plus pm validate green in one command. Verified end-to-end on a 2-branch concurrent edit: the field-aware driver unions notes and scalar fields with zero conflicts, then reconcile re-greens the hash chain with zero data loss (both authors content and attribution preserved). The Multi-agent merge safety README section (added in the 5cx1 rollout) previously recommended the blunt history-repair all-items primitive; this updates it to the dry-run then apply then verify reconcile workflow and links the authoritative upstream MERGE_SAFETY guide. Fleet fan-out from canary pm-beads#42."
+type: Issue
+status: closed
+priority: 2
+tags[3]: agent-ux,docs,multi-agent
+created_at: "2026-07-22T19:41:57.764Z"
+updated_at: "2026-07-22T19:41:58.592Z"
+closed_at: "2026-07-22T19:41:58.591Z"
+author: claude-opus-20260722
+acceptance_criteria: "README Multi-agent merge safety section recommends pm merge reconcile with a dry-run preview, apply, and pm history --verify plus pm validate confirmation; links upstream MERGE_SAFETY.md; CI green; PR reviewed by bots."
+notes[1]{created_at,author,text}:
+  "2026-07-22T19:41:58.170Z",claude-opus-20260722,Fan-out from canary unbraind/pm-beads#42. README Multi-agent merge safety section closing recommendation migrated to the pm merge reconcile dry-run->apply->verify workflow; links upstream docs/MERGE_SAFETY.md; keeps history-repair --all as a lower-level primitive.
+close_reason: Docs updated to recommend the 2026.7.22 pm merge reconcile workflow (fleet fan-out from pm-beads#42).
+body: ""

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([pm-github-wpit](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-wpit.toon))
+
 ## 2026.7.21 - 2026-07-21
 
 ### Other

README.md

@@ -207,5 +207,13 @@ This repo tracks its project management in `.agents/pm/` and ships a committed `
 that maps those tracker artifacts to pm-cli's field-aware Git merge drivers, so concurrent-branch
 tracker edits merge cleanly. The driver definitions live in per-clone Git config; `npm install` /
 `npm ci` wires them automatically via the `prepare` script (a portable Node guard, `scripts/prepare-merge-driver.mjs`: it runs `pm merge install` only when the `pm` CLI is on `PATH`, and no-ops cleanly otherwise so production / `--omit=dev` installs are not broken; being Node-based it behaves identically on POSIX shells and Windows `cmd.exe`). To (re)run
-manually: `npm run merge:install`. After merging a branch that touched `.agents/pm/`, run
-`pm history-repair --all` to reconcile history verification.
+manually: `npm run merge:install`.
+
+After merging a branch that touched `.agents/pm/`, reconcile any residual history-hash drift with
+**`pm merge reconcile`** (pm-cli ≥ 2026.7.22): preview with `pm merge reconcile --dry-run`, apply with
+`pm merge reconcile --message "post-merge reconcile"`, then confirm with `pm validate`, which scans the
+whole tracker and flags remaining history drift across **every** affected item (`pm merge reconcile`
+itself lists each affected stream in its output; `pm history --verify <id>` spot-checks one item). The field-aware driver already unions every author's
+content, so `reconcile` only re-greens the hash chain (no data loss) — see the authoritative
+[pm-cli merge-safety guide](https://github.com/unbraind/pm-cli/blob/main/docs/MERGE_SAFETY.md). The
+older blunt `pm history-repair --all` remains available as a lower-level primitive.

package.json

@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
-    "@unbrained/pm-cli": "^2026.7.21",
+    "@unbrained/pm-cli": "^2026.7.22",
     "pm-changelog": "^2026.7.18",
     "typescript": "^7.0.2"
   },