From e79508ca996b2989539ad86b1df0236cd7e1d818 Mon Sep 17 00:00:00 2001 From: SteveBot <1153461+unbraind@users.noreply.github.com> Date: Wed, 22 Jul 2026 21:41:59 +0200 Subject: [PATCH 1/2] docs(merge): recommend `pm merge reconcile` (2026.7.22) over raw history-repair Fleet fan-out from canary unbraind/pm-beads#42. Update the Multi-agent merge safety section's closing recommendation from `pm history-repair --all` to the purpose-built, audited `pm merge reconcile` workflow (GH-623): preview with `--dry-run`, apply with `--message`, confirm with `pm history --verify` + `pm validate`. Links the authoritative upstream docs/MERGE_SAFETY.md; keeps `pm history-repair --all` noted as a lower-level primitive. Tracker: pm-github-wpit. CHANGELOG regenerated (changelog:check green). Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/pm/history/pm-github-wpit.jsonl | 3 +++ .agents/pm/issues/pm-github-wpit.toon | 16 ++++++++++++++++ CHANGELOG.md | 6 ++++++ README.md | 11 +++++++++-- 4 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 .agents/pm/history/pm-github-wpit.jsonl create mode 100644 .agents/pm/issues/pm-github-wpit.toon diff --git a/.agents/pm/history/pm-github-wpit.jsonl b/.agents/pm/history/pm-github-wpit.jsonl new file mode 100644 index 0000000..b0dbfc9 --- /dev/null +++ b/.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"} diff --git a/.agents/pm/issues/pm-github-wpit.toon b/.agents/pm/issues/pm-github-wpit.toon new file mode 100644 index 0000000..2ed7b73 --- /dev/null +++ b/.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: "" diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a04c7a..d363d37 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 8221079..eb58771 100644 --- a/README.md +++ b/README.md @@ -207,5 +207,12 @@ 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 the chain is green with +`pm history --verify ` and `pm validate`. 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. From 838ff804ae268e8bd71c208a22adcb6375641c82 Mon Sep 17 00:00:00 2001 From: SteveBot <1153461+unbraind@users.noreply.github.com> Date: Wed, 22 Jul 2026 21:56:23 +0200 Subject: [PATCH 2/2] =?UTF-8?q?docs(merge):=20address=20Greptile=20review?= =?UTF-8?q?=20=E2=80=94=20clarify=20verify=20scope=20+=20bump=20pm-cli=20t?= =?UTF-8?q?o=202026.7.22?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Greptile P2: pm history --verify checks one stream but a merge can affect several — lead the post-reconcile check with whole-tracker pm validate and note that pm merge reconcile lists each affected stream; pm history --verify is a per-item spot check. Greptile P1: the pinned @unbrained/pm-cli devDep resolved to 2026.7.21 (lacks pm merge reconcile) — bump floor to ^2026.7.22 and refresh the lockfile so the documented command exists in the repo's own toolchain. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 5 +++-- package-lock.json | 8 ++++---- package.json | 2 +- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index eb58771..9d774b3 100644 --- a/README.md +++ b/README.md @@ -211,8 +211,9 @@ 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 the chain is green with -`pm history --verify ` and `pm validate`. The field-aware driver already unions every author's +`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 ` 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. diff --git a/package-lock.json b/package-lock.json index 6e51b51..5668385 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,7 @@ "license": "MIT", "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" }, @@ -717,9 +717,9 @@ } }, "node_modules/@unbrained/pm-cli": { - "version": "2026.7.21", - "resolved": "https://registry.npmjs.org/@unbrained/pm-cli/-/pm-cli-2026.7.21.tgz", - "integrity": "sha512-U31SEZtw58QlR3DU/nqU5Cab6sz6DVjxqbg8JLt7lmfstdQWW3n+SW6K3xIQXDanvbQQSPOF26UjvnDzrOTaTw==", + "version": "2026.7.22", + "resolved": "https://registry.npmjs.org/@unbrained/pm-cli/-/pm-cli-2026.7.22.tgz", + "integrity": "sha512-quvTKd4T0LniFd5r52XDwmNQKxEK0eYWYB3lHWM/MeseL3+FKDm+0Vi3u5zA4cvW4PQ2eGFQW846NqW5i6eZPw==", "dev": true, "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index 57dac79..4b02b85 100644 --- a/package.json +++ b/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" },