release skill: own PGXS-target modifications, pin DEBUG exception, auto-sync preflight

[jnasbyupgrade]

Summary

Three related dev-tooling improvements to the /release skill and its
supporting definitions, all found/decided during 2.3.0 release prep. No
changes to pgxntool-test's own test suite or template.

1. Tighten the "Known gap" in CLAUDE.md's User-Facing API Surface
   definition. pgxntool's own modifications to PGXS-named targets (e.g.
   installcheck: install from issue #79, test's prerequisites, clean's
   EXTRA_CLEAN additions) are now explicitly IN SCOPE for API surface
   tracking, rather than being excluded just because the target shares a
   name with a PGXS target. The underlying PGXS behavior pgxntool didn't
   touch stays out of scope; pgxntool's own authored changes to a
   shared-name target no longer do. This has already caused two real misses
   (a stale README claim, and installcheck: install/#79 almost being waved
   through) — this settles the policy instead of leaving it open-ended.

2. Pin down the DEBUG documentation exception. CLAUDE.md's item 5 now
   states explicitly that DEBUG's absence from README.asc/CLAUDE.md
   documentation is intentional and not itself a finding, so future
   API-documentation review agents don't re-flag it. This is framed as the
   first entry in a general pattern (standing exceptions get recorded here
   rather than re-litigated release after release). SKILL.md's review-agent
   launch section now points agents at this list instead of duplicating it.

3. Auto-sync in release-preflight.sh. The sync-status check no longer
   just warns when local master is behind upstream — it self-heals: fetches
   upstream, and if local is a clean fast-forward behind (verified via
   git merge-base --is-ancestor), it fast-forwards with git merge --ff-only (never a plain merge/rebase — master must only ever
   fast-forward, never gain a merge commit) and pushes the result to
   origin (the fork remote). If --ff-only itself refuses, or local has
   commits upstream lacks (true divergence), that's a hard error requiring
   manual resolution — never auto-merged, rebased, or forced. Found during
   2.3.0 prep, where both pgxntool and pgxntool-test local masters and forks
   had drifted behind upstream. SKILL.md's "Run Pre-flight Checks" prose
   updated to match.

Test plan

• bash -n .claude/skills/release/scripts/release-preflight.sh — syntax check passes
• Ran the modified script against the real (in-sync) pgxntool/pgxntool-test checkouts — reports "in sync", no errors, no unwanted pushes
• Extracted the new sync_repo function and exercised it against throwaway local git repos simulating both scenarios:
  • clean fast-forward case: fast-forwards local master and pushes to the fork remote correctly
  • true divergence case (local has a commit upstream lacks): reported as an error, nothing merged/pushed/forced
• Confirmed set -euo pipefail doesn't abort the script on the expected non-zero exit from merge-base --is-ancestor or a refused merge --ff-only

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 48c69eb7-31cb-4f99-af4b-89a99d2b251a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}