Add PR batch merge ledger

Author: justin808

.agents/skills/pr-batch/SKILL.md

@@ -161,6 +161,14 @@ next paragraph; an empty full check list is `UNKNOWN` / not ready. Treat untriag
 regression, compatibility, and missing-changelog findings as merge blockers
 unless a maintainer explicitly waives them.
 
+At merge readiness and batch closeout, run the machine-checkable per-PR merge
+ledger with `script/pr-merge-ledger <PR> --strict`, supplying explicit changelog
+classification and any P0/P1/P2/Must-Fix disposition evidence. Do not report a
+target `complete` while the ledger has any `UNKNOWN` field, unresolved
+current-head review thread, `CHANGES_REQUESTED` review object, or
+`complete_allowed: false`. Include the ledger JSON artifact path or table in the
+final handoff.
+
 If `gh pr checks <PR> --required` reports no required checks, do NOT treat that
 as CI-ready. Instead treat the full `gh pr checks <PR>` list as the readiness
 gate and require each current-head check to pass or be skipped with CI selector
@@ -216,7 +224,9 @@ Use the canonical Batch Handoff Format in
 `.agents/workflows/pr-processing.md`. In short, split final batch handoffs into
 **Immediate maintainer attention** for true blockers and questions only, and
 **FYI / decisions made** for decisions, validations, review state, full-CI
-requests already handled, and no-PR rationales.
+requests already handled, no-PR rationales, and per-PR merge-ledger summaries.
+Do not call a target `complete` while its ledger has `UNKNOWN` fields or
+`complete_allowed: false`.
 
 ## Coordination State
 
@@ -243,7 +253,7 @@ reporting, full-CI decisions, and merge sequencing.
 For the complete numbered sequence, follow the canonical closeout lane in
 `.agents/workflows/pr-processing.md` instead of stopping at PR creation. The
 coordinator owns the live re-fetch, current-head checks and review-thread triage,
-stale release-mode classification updates and the finalized PR-body
+per-PR merge-ledger run, stale release-mode classification updates and the finalized PR-body
 `Agent Merge Confidence` block refresh required for accelerated-RC readiness (kept
 distinct), full-CI request and waitback when uncertainty remains, and any
 authorized ready/merge action, and the late post-merge bot-finding sweep before

.agents/workflows/pr-processing.md

@@ -92,6 +92,22 @@ gh api graphql --paginate -f owner="${OWNER}" -f name="${NAME}" -F pr="${PR_NUMB
 
 Use `-F pr=...` intentionally here: `gh api graphql` needs a JSON integer for `$pr:Int!`, and raw `-f pr=...` sends a string.
 
+At merge readiness or batch closeout, build the machine-checkable per-PR merge
+ledger. The command uses GitHub GraphQL/API reviewThreads, reviews, and PR
+comments, then emits JSON against `script/pr-merge-ledger.schema.json`:
+
+```bash
+script/pr-merge-ledger <PR> --repo "${REPO}" \
+  --changelog-classification <changelog_present|changelog_missing|deferred_to_update_changelog|not_user_visible> \
+  --finding-dispositions <optional-dispositions.json> \
+  --strict --pretty > "/tmp/pr-<PR>-merge-ledger.json"
+script/pr-merge-ledger --schema
+```
+
+If changelog classification or P0/P1/P2/Must-Fix dispositions are not supplied,
+the ledger records those fields as `UNKNOWN`. `--strict` exits non-zero when any
+ledger violation exists or any field is `UNKNOWN`.
+
 For an issue, gather enough context to avoid duplicate work:
 
 ```bash
@@ -387,11 +403,11 @@ it as an immediate maintainer question. Also apply the merge-endgame debounce
 and waiver-soak rule under **Merge Endgame Debounce And Waiver Soak** before
 the final merge/readiness decision.
 
-After workers finish, the coordinator must keep working through the Coordinator Closeout Lane instead of stopping at PR creation: re-fetch live PR status, wait for current-head checks and reviews, triage/resolve or explicitly waive current unresolved review threads, update stale release-mode classification, refresh the finalized PR-body `Agent Merge Confidence` block when accelerated-RC readiness requires it, request full CI when uncertainty remains, re-fetch and wait for the newly requested current-head checks, and merge eligible ready PRs when authorized under the current release mode.
+After workers finish, the coordinator must keep working through the Coordinator Closeout Lane instead of stopping at PR creation: re-fetch live PR status, wait for current-head checks and reviews, triage/resolve or explicitly waive current unresolved review threads, run `script/pr-merge-ledger <PR> --strict` with explicit changelog classification and P0/P1/P2/Must-Fix dispositions, update stale release-mode classification, refresh the finalized PR-body `Agent Merge Confidence` block when accelerated-RC readiness requires it, request full CI when uncertainty remains, re-fetch and wait for the newly requested current-head checks, and merge eligible ready PRs when authorized under the current release mode.
 
 For blocking questions, stop work on that target, surface a structured question to the coordinator or maintainer, and mark the issue/PR with the agreed pending-question state. Report the question/comment URL as `blocked needing user input`; do not open a speculative PR. For non-blocking questions where you make a decision and continue, record the decision in the PR description before review or merge.
 
-Before final handoff, kill or confirm no stray GitHub polling processes are still running. Final state for every target must be one of: merged PR; open PR waiting on checks/review; blocked needing user input with the surfaced question/comment URL; or no-PR with an evidence-backed issue/PR comment URL. Split the handoff into `Immediate maintainer attention` and `FYI / decisions made`. Put only true blockers or questions in Immediate. Put non-blocking decisions, no-PR rationales, and full-CI uncertainty that was already handled by requesting full CI in FYI. Final handoff must list branches, PR URLs, issue outcomes, validations, last-known CI state, blockers, no-PR comments, and next actions.
+Before final handoff, kill or confirm no stray GitHub polling processes are still running. Final state for every target must be one of: merged PR; open PR waiting on checks/review; blocked needing user input with the surfaced question/comment URL; or no-PR with an evidence-backed issue/PR comment URL. Do not report a target `complete` while its merge ledger has any `UNKNOWN` field or `complete_allowed: false`. Split the handoff into `Immediate maintainer attention` and `FYI / decisions made`. Put only true blockers or questions in Immediate. Put non-blocking decisions, no-PR rationales, full-CI uncertainty that was already handled by requesting full CI, and the per-PR merge-ledger summary in FYI. Final handoff must list branches, PR URLs, issue outcomes, validations, last-known CI state, merge-ledger path or JSON artifact, blockers, no-PR comments, and next actions.
 ```
 
 ### Question And Decision Handling
@@ -433,10 +449,14 @@ Split batch handoffs into two sections:
   unresolved `DISCUSS` feedback, or a merge/release-mode conflict.
 - **FYI / decisions made**: no-PR rationales, non-blocking decisions, full CI
   requested because the coordinator was unsure at readiness time, validation
-  evidence, review churn notes, and already-answered questions.
+  evidence, review churn notes, already-answered questions, and a per-PR
+  merge-ledger table or JSON artifact path.
 
 Do not put full-CI uncertainty in Immediate at final readiness after local
 validation and the final push. Request full CI and log it in FYI.
+Do not report a PR/target as `complete` while `script/pr-merge-ledger <PR>
+--strict` reports `UNKNOWN` fields, review-thread/review-object violations, or
+`complete_allowed: false`.
 
 ### Coordination State
 
@@ -542,19 +562,25 @@ The closeout lane is:
    polling.
 4. Fetch current unresolved review threads and triage them as fixed, waived, or
    still blocking.
-5. Refresh stale release-mode classification from the release tracker when
+5. Run `script/pr-merge-ledger <PR> --strict` for every worker PR, supplying
+   explicit changelog classification and any P0/P1/P2/Must-Fix disposition
+   evidence. Store the JSON artifact or table for the final handoff. Do not
+   mark a target complete while the ledger has `UNKNOWN` fields, unresolved
+   current-head review threads, `CHANGES_REQUESTED` review objects, or
+   `complete_allowed: false`.
+6. Refresh stale release-mode classification from the release tracker when
    needed. For accelerated-RC merge readiness, refresh the latest finalized
    PR-body `Agent Merge Confidence` block required by `AGENTS.md`; keep this
    distinct from tracker mode/classification updates.
-6. After the final push, if local validation passed and the only uncertainty is
+7. After the final push, if local validation passed and the only uncertainty is
    whether full CI is needed, request full CI with `+ci-run-full` and record the
    reason as FYI, then loop back to re-fetch and wait for the newly requested
    current-head checks before readiness or merge.
-7. Under the current release mode, mark ready or merge PRs that satisfy the
+8. Under the current release mode, mark ready or merge PRs that satisfy the
    merge qualification rules, including the merge-endgame debounce and
    waiver-soak rules before merge; report only remaining blockers, questions,
    or `UNKNOWN` live state.
-8. After any closeout-lane merge action, run a lightweight sweep for late
+9. After any closeout-lane merge action, run a lightweight sweep for late
    post-merge bot findings before the final batch handoff: confirm the PR landed,
    check `main` status, and inspect late review/check comments that arrived
    around or after merge. Route release-relevant findings into the next
@@ -841,6 +867,9 @@ Before saying a PR is ready to merge:
 gh pr view <PR> --json headRefOid,mergeStateStatus,reviewDecision,isDraft,labels,latestReviews,reviews,comments,mergedAt
 gh pr checks <PR> --required
 gh pr checks <PR>
+script/pr-merge-ledger <PR> \
+  --changelog-classification <changelog_present|changelog_missing|deferred_to_update_changelog|not_user_visible> \
+  --strict
 ```
 
 Before evaluating review feedback at this gate, also fetch inline PR review
@@ -859,6 +888,7 @@ Also verify:
 - No requested adversarial review has unresolved `BLOCKING` or `DISCUSS` findings.
 - Required checks are green, or the user has explicitly accepted an auditable waiver for full CI.
 - The PR body or latest agent comment includes exact local validation commands and results.
+- The merge ledger has no `UNKNOWN` fields and reports `complete_allowed: true`.
 
 Merge qualification follows the canonical rule in `AGENTS.md` -> Review Workflow -> For All PRs: CI is passing, all current review comments and threads are addressed or explicitly triaged by tier, no major question or discussion item needs maintainer attention, and advisory AI systems such as CodeRabbit.ai are not special approval gates.
 

Rakefile

@@ -70,7 +70,7 @@ end
 
 def root_rubocop_paths
   # Root lint covers repo-root tooling only; package-owned rakelib files stay under package RuboCop.
-  %w[Gemfile Rakefile rakelib]
+  %w[Gemfile Rakefile rakelib script/pr-merge-ledger]
 end
 
 def define_package_task(task_name, *arg_names)

react_on_rails/spec/react_on_rails/fixtures/pr_merge_ledger/pr_3613.json

@@ -0,0 +1,88 @@
+{
+  "repository": "shakacode/react_on_rails",
+  "pull_request": {
+    "number": 3613,
+    "title": "ci(rspack): decouple per-bundler build + integration jobs so one bundler's build failure doesn't skip the other (#3593)",
+    "url": "https://github.com/shakacode/react_on_rails/pull/3613",
+    "state": "MERGED",
+    "isDraft": false,
+    "baseRefName": "main",
+    "headRefName": "jg-conductor/3593-fix",
+    "headRefOid": "62ecd5760e3466726a3be1ed77b0071665c5cf2d",
+    "mergedAt": "2026-06-05T01:32:12Z",
+    "reviewDecision": "CHANGES_REQUESTED"
+  },
+  "files": [
+    ".github/workflows/dummy-app-bundler-tests.yml",
+    ".github/workflows/integration-tests.yml"
+  ],
+  "review_threads": [
+    {
+      "id": "PRRT_kwDOAnNnU86HM4iZ",
+      "isResolved": false,
+      "isOutdated": false,
+      "path": ".github/workflows/integration-tests.yml",
+      "line": 131,
+      "comments": [
+        {
+          "id": "PRRC_kwDOAnNnU87INkFj",
+          "databaseId": 3358998883,
+          "body": "**P2** Keep CI rerun helper aligned with new check names.",
+          "author": {
+            "login": "chatgpt-codex-connector"
+          },
+          "url": "https://github.com/shakacode/react_on_rails/pull/3613#discussion_r3358998883",
+          "path": ".github/workflows/integration-tests.yml",
+          "line": 131,
+          "createdAt": "2026-06-04T21:26:41Z",
+          "outdated": false,
+          "commit": {
+            "oid": "62ecd5760e3466726a3be1ed77b0071665c5cf2d"
+          },
+          "originalCommit": {
+            "oid": "d4d94358873321664b1e3a8c2a297f793a8ae3ed"
+          },
+          "pullRequestReview": {
+            "id": "PRR_kwDOAnNnU88AAAABCCSc3Q",
+            "state": "COMMENTED",
+            "submittedAt": "2026-06-04T21:26:41Z",
+            "commit": {
+              "oid": "d4d94358873321664b1e3a8c2a297f793a8ae3ed"
+            },
+            "author": {
+              "login": "chatgpt-codex-connector"
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "reviews": [
+    {
+      "id": "PRR_kwDOAnNnU88AAAABCCTgOg",
+      "state": "CHANGES_REQUESTED",
+      "submittedAt": "2026-06-04T21:29:57Z",
+      "author": {
+        "login": "coderabbitai"
+      },
+      "commit": {
+        "oid": "d4d94358873321664b1e3a8c2a297f793a8ae3ed"
+      },
+      "url": "https://github.com/shakacode/react_on_rails/pull/3613#pullrequestreview-4431601722",
+      "body": "**P2** Run this PR under full-ci before merge."
+    },
+    {
+      "id": "PRR_kwDOAnNnU88AAAABCC6cRg",
+      "state": "COMMENTED",
+      "submittedAt": "2026-06-04T23:36:33Z",
+      "author": {
+        "login": "coderabbitai"
+      },
+      "commit": {
+        "oid": "62ecd5760e3466726a3be1ed77b0071665c5cf2d"
+      },
+      "url": "https://github.com/shakacode/react_on_rails/pull/3613#pullrequestreview-4432239686",
+      "body": "Nitpick comments only."
+    }
+  ]
+}