Add post-merge audit scope resolver (#4029)

Fixes #4014

## Summary
- Add `.agents/skills/post-merge-audit/bin/post-merge-audit-scope`, a
read-only resolver for the post-merge audit base/head range,
squash-aware merged PR list, prior finding fingerprints, carry-over PRs,
and `to_audit` list.
- Wire the resolver into `$post-merge-audit` as the initial scope gate.
- Cover parser behavior, first-parent mainline scope, and closed-finding
carry-over rules with shell tests.

## Validation
- `bash -n .agents/skills/post-merge-audit/bin/post-merge-audit-scope
.agents/skills/post-merge-audit/bin/post-merge-audit-scope-test.bash` ->
passed
- `bash
.agents/skills/post-merge-audit/bin/post-merge-audit-scope-test.bash` ->
5 tests passed
- `shellcheck .agents/skills/post-merge-audit/bin/post-merge-audit-scope
.agents/skills/post-merge-audit/bin/post-merge-audit-scope-test.bash` ->
passed
- `.agents/skills/post-merge-audit/bin/post-merge-audit-scope
--self-check` -> passed with live open/closed `gh search` smoke
- `.agents/skills/post-merge-audit/bin/post-merge-audit-scope --json
--limit 50` -> `range=v17.0.0.rc.3..origin/main merged=24 to_audit=10
fingerprints=12`
- `git diff origin/main --check` -> passed
- `script/ci-changes-detector origin/main` -> documentation-only;
recommended CI jobs: none
- `codex review --base origin/main` -> accepted two P2 findings
(first-parent history and closed-marker suppression), fixed both, rerun
clean

## CI / Labels
Labels: none. This is agent process tooling under `.agents/`; detector
recommends no CI expansion.

Confidence note:
- Validated: command list above, pre-commit trailing-newlines hook, and
clean branch review after accepted P2 fixes.
- Evidence: local command output and clean review output.
- UNKNOWN: none.
- Residual risk: low-medium; the resolver is read-only but will shape
future audit scope, so PR reviewers should look closely at scope
semantics.

Decision points: 0

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Read-only agent tooling, but incorrect scope semantics (first-parent
range, open vs closed markers) could mis-route which merged PRs get
audited before release.
> 
> **Overview**
> Adds a **read-only scope gate** for `$post-merge-audit`: new
`post-merge-audit-scope` resolves base/head (default nearest `*.rc.*` on
first-parent mainline), squash-aware merged PRs, existing
`post-merge-audit-finding` fingerprints via `gh search`, **carry-over**
PRs from **open** markers, and **`to_audit`** (merged minus carry-over).
Closed finding issues stay dedupe context only.
> 
> The post-merge-audit skill now tells agents to run
`post-merge-audit-scope --json` first and treat that output as the
initial scope table. A Bash test harness covers log/marker parsing,
first-parent boundaries, RC default-base rules, and sourced-vs-executed
CLI behavior.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
f6b1234. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a “Scope Gate” for post-merge audits by introducing a new scope
generator that computes merged PRs, carry-over PRs, existing
fingerprints, and the remaining PRs to audit (outputs JSON or readable
summaries).
* Included a `--self-check` mode to verify scope generation assumptions.
* **Documentation**
* Updated the post-merge audit instructions to start with the scope gate
output and then confirm assumptions.
* **Tests**
* Added a Bash test harness for scope computation, marker
parsing/deduping, and CLI/error-path validation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

## Agent Merge Confidence

Mode: accelerated-rc
Current head SHA: f6b1234
Score: 8/10
Auto-merge recommendation: yes
Affected areas: agent post-merge-audit workflow/tooling; read-only shell
resolver
CI detector: `script/ci-changes-detector origin/main` ->
documentation-only changes; recommended CI jobs: none
Checks: `gh pr checks 4029` -> 39 pass, 6 skipped, 0 pending, 0 failing.
Benchmark confirmation/report skips and docs-format skip are explained
by CI selector output for this non-benchmark process-tooling change.
Validation run:
- `bash -n .agents/skills/post-merge-audit/bin/post-merge-audit-scope
.agents/skills/post-merge-audit/bin/post-merge-audit-scope-test.bash` ->
passed
- `bash
.agents/skills/post-merge-audit/bin/post-merge-audit-scope-test.bash` ->
16 tests passed
- `.agents/skills/post-merge-audit/bin/post-merge-audit-scope
--self-check` -> passed
- `shellcheck .agents/skills/post-merge-audit/bin/post-merge-audit-scope
.agents/skills/post-merge-audit/bin/post-merge-audit-scope-test.bash` ->
passed
- `git diff --check && git diff --check origin/main...HEAD` -> passed
- `script/ci-changes-detector origin/main` -> documentation-only;
recommended CI jobs: none
Review/check gate:
- GitHub checks: complete for
`f6b1234c32dce08f3d2f0a8d0d3f39f802694c2b`; no failed or pending checks
- Review threads: live GraphQL unresolved count is 0
- Feedback triage: CodeRabbit/Claude/Codex/Cursor findings were fixed,
resolved, or stale/advisory; no current unresolved non-trivial concern
remains
- Current-head reviewer verdicts:
- `claude-review` check: success for
`f6b1234c32dce08f3d2f0a8d0d3f39f802694c2b`
([run](https://github.com/shakacode/react_on_rails/actions/runs/27517272510),
[job](https://github.com/shakacode/react_on_rails/actions/runs/27517272510/job/81328130359))
  - Cursor Bugbot: pass for current head
  - CodeRabbit: pass for current head
- Stale reviewer verdicts, advisory only:
- CodeRabbit requested changes on older heads
`92ac5b8840f5f82ce9a905a5fe11a24b5b7d1f50` and
`d6220edd65760e3a07c06fdf553bbbeb2c632a93`, then approved an
intermediate head; not cited as a merge gate
Labels: none. Agent tooling/process change; CI detector recommends no CI
expansion.
Known residual risk: low-medium; resolver is read-only but shapes future
audit scope, so mistakes would affect audit routing rather than runtime
behavior.
Merge recommendation: merge now by squash.
Finalized by: `claude-review` GitHub check, Claude Code Review run
`27517272510` / job `81328130359`, completed successfully for current
head `f6b1234c32dce08f3d2f0a8d0d3f39f802694c2b`.

Author: justin808

.agents/skills/post-merge-audit/SKILL.md

@@ -21,6 +21,14 @@ Use `.agents/workflows/post-merge-audit.md` for reusable copy-paste prompts, inc
 
 Start by resolving the exact audit range:
 
+When this repository includes `.agents/skills/post-merge-audit/bin/post-merge-audit-scope`, run it first:
+
+```bash
+.agents/skills/post-merge-audit/bin/post-merge-audit-scope --json
+```
+
+The resolver is read-only. It resolves the default release-candidate base, the head SHA, squash-aware merged PRs, prior `post-merge-audit-finding` fingerprints, PRs with open finding markers, and the `to_audit` list. Open finding markers create carry-over PRs that are subtracted from `to_audit`; closed markers remain fingerprint context only. Use the output as the initial scope table, then verify assumptions before deep audit.
+
 1. Base: the user-supplied tag/commit, or the most recent release candidate tag when the user says "since the last RC".
 2. Head: usually `origin/main` or the current release branch.
 3. Merged PR list: every PR merged between base and head.