From 255cfc87ddc726d2a18ffce5b63bfd7885d83974 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Thu, 2 Jul 2026 20:21:07 -0400 Subject: [PATCH] docs: add post-merge file-presence verification to merge workflow (#112) --- docs/llm-workflow-runbooks.md | 13 ++++++++----- skills/llm-project-workflow/SKILL.md | 4 ++-- skills/llm-project-workflow/templates/merge-pr.md | 9 +++++++-- 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/llm-workflow-runbooks.md b/docs/llm-workflow-runbooks.md index 128426b..f427c16 100644 --- a/docs/llm-workflow-runbooks.md +++ b/docs/llm-workflow-runbooks.md @@ -339,22 +339,25 @@ touching anything. - **Steps:** confirm eligibility; require explicit confirmation (`MERGE PR `); optionally pin head SHA / changed-file set; merge only when Gitea reports the PR mergeable (branch-protection checks satisfied). No force, - no ignore-checks. + no ignore-checks. Verify that remote master contains the merge commit or the expected squashed changes (do not assume a "closed" PR succeeded without verifying the actual landed changes). - **Prompt:** `Use any eligible merger profile to merge PR #N if checks pass and it is mergeable. Confirm with "MERGE PR N". Do not force-merge.` ### Close the issue after merge / Reconciliation - **Profile:** issue-manager or merger. -- **Steps:** verify remote `master` actually contains the merge; close the - issue; release `status:in-progress` (if it cannot be removed, report why). +- **Steps:** Verify remote `master` actually contains the merge (post-merge file-presence verification): + - Run: `git fetch --prune; git checkout master; git pull master --ff-only` + - Verify that expected files added/modified in the PR are present on `master` (or absent if deleted). + - Alternatively, verify with: `git log --oneline -- ` or `git merge-base --is-ancestor master` + - Close the issue; release `status:in-progress` (if it cannot be removed, report why). - **If closed but not merged (`merged=false`):** Stop normal flow. Do not delete worktrees. Compare PR content to remote `master`. - **fully landed:** comment it landed, remove `status:in-progress`, clean up. - **partially landed:** reopen issue, create corrective PR for missing pieces. - **not landed:** reopen issue/PR, do not clean up. - **Direct push to master:** is forbidden except as a documented recovery exception. Final reports must include why, commits, PR metadata, and repaired labels. -- **Final reports:** must include both PR metadata (state, merged flag, merge commit) and Git content (remote master hash, expected content present). -- **Prompt (normal):** `After confirming master contains the merge of PR #N, close issue #M and delete the merged branch.` +- **Final reports:** must include both PR metadata (state, merged flag, merge commit) and Git content (remote master hash, expected content present, verification method used & results). +- **Prompt (normal):** `After verifying master contains the merge of PR #N using post-merge file-presence verification, close issue #M and delete the merged branch. Include verification details in the report.` - **Prompt (reconcile):** `Reconcile closed-not-merged PR #N by verifying if its content landed on master.` ### Stop on blocker diff --git a/skills/llm-project-workflow/SKILL.md b/skills/llm-project-workflow/SKILL.md index 49cdff8..0606699 100644 --- a/skills/llm-project-workflow/SKILL.md +++ b/skills/llm-project-workflow/SKILL.md @@ -182,7 +182,7 @@ results); and merge with a **pinned head SHA** and, where supported, the **expected changed-file set**, so a moved head or widened diff refuses the merge. After a real merge: -1. Confirm remote `master` actually contains the merge commit (A PR is not done just because `master` moved. A PR is done only when: Gitea reports the PR merged or reconciliation documents equivalent content on `master`; remote `master` contains the expected content; linked issues are closed; `status:in-progress` is removed). +1. Confirm remote `master` actually contains the merge commit or expected squashed changes via post-merge file-presence verification (A PR is not done just because `master` moved or is marked "closed". Verify that expected files added/modified in the PR are actually present on `master` using `git pull`, `git log --oneline -- `, or `git merge-base --is-ancestor`; linked issues are closed; `status:in-progress` is removed). 2. Close/release the issue. 3. Whenever an issue is closed, check for `status:in-progress`: remove it, or report why it could not be removed. 4. Do not delete the remote source branch until: PR `merged=true`, or reconciliation confirms content is safely landed, or the issue owner explicitly abandons the work. @@ -190,7 +190,7 @@ merge. After a real merge: 6. Remove the branch worktree folder (`scripts/worktree-clean --delete-branch `). Branches/worktrees are cleaned only after the above is verified. 7. Fetch/prune. 8. Confirm the main checkout is clean and current (`0 0` vs remote). -9. Final merge/reconciliation reports must include both: PR metadata (state, merged flag, merge commit/hash) and Git content (remote master hash, expected content present or not). +9. Final merge/reconciliation reports must include: PR metadata (state, merged flag, merge commit/hash), Git content (remote master hash, expected content present or not), and the exact post-merge verification method used & results. Never run cleanup before the merge is confirmed on remote `master`. diff --git a/skills/llm-project-workflow/templates/merge-pr.md b/skills/llm-project-workflow/templates/merge-pr.md index 6c61bb5..8766ad6 100644 --- a/skills/llm-project-workflow/templates/merge-pr.md +++ b/skills/llm-project-workflow/templates/merge-pr.md @@ -23,12 +23,17 @@ Steps: 4. If any gate fails → STOP and report. 4. Merge with explicit confirmation (e.g. confirmation="MERGE PR "), optionally pinning the reviewed head SHA / changed-file set. -5. Confirm remote master now contains the merge commit. +5. Confirm remote master now contains the merge commit (or the expected changes if squash merged). + *Note: Gitea PR "closed" state is NOT equivalent to "merged". Do not assume a closed PR succeeded without verifying the actual landed changes.* Then run the cleanup template (worktree-cleanup.md): +- Verify expected file/commit presence on master (post-merge file-presence verification): + - Run: git fetch --prune; git checkout master; git pull master --ff-only + - Verify that the expected files added/modified in the PR are present on master (or absent if deleted). + - Alternatively, verify with: git log --oneline -- or git merge-base --is-ancestor master - close/release issue #, remove status:in-progress (if it cannot be removed, report why) - delete remote branch, remove local branch + worktree folder - fetch/prune; confirm main checkout is clean and current (0 0). -Handoff: reviewer identity, merge result + commit, cleanup done, issue closed, PR metadata state/merged flag/hash, remote master hash & Git content check. +Handoff: reviewer identity, merge result + commit, cleanup done, issue closed, PR metadata state/merged flag/hash, remote master hash, post-merge verification method used & verification results. ```