Point CLAUDE.md at ai/ repo's consolidated conventions

[jnasbyupgrade]

Removes content now covered by Postgres-Extensions/ai's CLAUDE.md, PR.md, and CODE_STYLE.md: CI-monitoring, the make-vs-ci.yml test-dimension bias, bug-fix comment rules, the CI: title-prefix rule, the PR/issue full-URL convention, general version-specific-SQL-file tracking rules, the general PG-version-support policy, the whole Code Style section (block comments, closing non-indentable blocks, upgrade-vs-update terminology), and the whole Pull request descriptions section (the maintainer-copies-opening-into-squash-commit mechanic isn't cat_tools-specific — filed as ai#4 to add the missing pieces there generally).

Also drops "Always open PRs against the main repo, not a fork" — stale guidance superseded by PR.md's fork-default convention — and "Never delete a branch without approval", now generalized into PR.md's merge authority section instead.

Keeps everything genuinely cat_tools-specific: the docs_only CI mechanism, the pgxntool behavior gotchas (arguably belong in pgxntool/CLAUDE.md instead, but that's out of scope this round), the .sql.in preprocessing convention (a custom sql.mk layer, not a general pgxntool rule), cat_tools' own version history and gitignore rationale, and the TEST_LOAD_SOURCE/CI job matrix documentation.

[github-actions]

Claude finished @jnasbyupgrade's task in 3m 5s —— View job

---

Code Review

• Gather context (PR diff, CLAUDE.md before/after)
• Review removed content vs. what remains in cat_tools' CLAUDE.md
• Check for anything removed that is actually still cat_tools-specific (not truly covered elsewhere)
• Cross-check other files in the repo for references into the sections being removed
• Post review feedback

Overall this is a clean consolidation — the sections removed (GitHub CI monitoring, test-matrix-dimension bias, Bug Fixes, Git safety/CI-prefix, PR/issue reference format, general SQL-file-tracking rules, general PG-version-support policy, Code Style) read as genuinely cross-repo conventions, and what's kept (the docs_only CI mechanism, pgxntool gotchas, PR-description squash-commit mechanics, cat_tools' own version history/gitignore rationale, TEST_LOAD_SOURCE/CI job matrix) is legitimately cat_tools-specific. I can't fetch Postgres-Extensions/ai from this sandbox to verify its CLAUDE.md/PR.md/CODE_STYLE.md actually cover everything claimed, so I focused on internal consistency instead.

Found one real issue: dangling rule-number references.

The deleted "SQL file conventions" list (rules 0–6) is referenced by rule number from three other files, and this PR leaves those references pointing at a rule that no longer exists in CLAUDE.md:

• Makefile:100 — # frozen once released (SQL file conventions rule 5 in CLAUDE.md — never hand-edited again)
• bin/test_existing:267 — # tagged (CLAUDE.md's SQL file conventions rule 5), so a divergence at that
• bin/test_existing:301 — # drift -- see CLAUDE.md's SQL file conventions rule 5), so ANY path

Rule 5 was "Version-specific files MUST NEVER be edited manually — always edit sql/cat_tools.sql.in and regenerate." Even if ai/CLAUDE.md has an equivalent general rule, it won't share cat_tools' local numbering (0–6), so these three comments now cite a rule number that doesn't resolve to anything in this repo. Worth a follow-up pass over those three comments (either rephrase them to not depend on a rule number, or point at wherever the equivalent rule lands in ai/CLAUDE.md).

Fix this →

Smaller, non-blocking observation:

The "Build/test system (pgxntool)" section's intro sentence changed meaning, not just wording — it went from "pgxntool's docs are not auto-loaded, read README.asc/CLAUDE.md first for non-trivial build/test work; here are gotchas those docs explain" to "here are gotchas those docs don't (yet) explain." That's a sensible reframing given this PR's own aside that these gotchas arguably belong upstream in pgxntool/CLAUDE.md, but it also quietly drops the actionable instruction to read pgxntool's (sizeable — ~290 + ~740 lines) own docs before non-trivial build/test work. Not covered by the new top-of-file pointer to ai/. Probably fine to leave for a future pass, just flagging it wasn't called out in the PR description.

No other removed section (test-matrix-dimension bias, Bug Fixes, Git/CI-prefix, PR/issue reference format, Code Style/terminology) has any dangling reference elsewhere in the repo — checked via grep across non-CLAUDE.md files.

[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: 833beed0-7a7a-497c-a4cf-1a414b673127

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.}

[github-actions]

Claude finished @jnasbyupgrade's task in 3m 37s —— View job

---

Code Review

• Gather context (PR diff, CLAUDE.md before/after, prior review comment)
• Re-review current diff vs. prior review (checking if the dangling rule-number issue is still present after the new commit)
• Check accuracy of the new commit's rewritten "SQL file conventions" section against sql.mk
• Post final review feedback

Reviewed the new commit (1831dad, "Fix: .sql.in preprocessing is this repo's own convention, not a general pgxntool rule"), which correctly addresses the conceptual mislabeling from the first commit (the .sql.in step was listed as a pgxntool gotcha; it isn't — it's this repo's own addition). Two issues remain, one carried over from the prior review and one new:

1. Still open: dangling "SQL file conventions rule 5" references (from the previous review, unaddressed by this commit)

Makefile:100, bin/test_existing:267, and bin/test_existing:301 all cite "SQL file conventions rule 5 in CLAUDE.md." This commit restored the numbered list (0–6) in CLAUDE.md:65-124 — so the numbering itself is back — but the previous review already flagged this as pointing at content that, in the merged PR, would live in ai/CLAUDE.md under different (or no) numbering. Since this commit's own restored list keeps rule 5 ("Version-specific files MUST NEVER be edited manually") as a local rule rather than delegating it to ai/CLAUDE.md, this particular instance is self-consistent for now — but only by accident of this commit's structure, not because it was addressed. Worth confirming intentionally rather than leaving it as a coincidence of how the second commit happened to lay things out.

2. New: inaccurate description of how pgxntool interacts with the .sql.in layer (CLAUDE.md:67-69)

"This repo preprocesses a tracked sql/cat_tools.sql.in into pgxntool's base sql/cat_tools.sql ... before pgxntool's own versioned-SQL generation runs on top of that base."

This isn't what sql.mk does. Per sql.mk:212-220's own comment, pgxntool's control.mk (auto-generated from cat_tools.control) defines its own recipe for $(EXTENSION__CURRENT_VERSION__FILES) that copies sql/cat_tools.sql straight to the current version's file — but sql.mk:229 and sql.mk:241 override that pgxntool-generated rule with cat_tools' own .sql.in/version-sed pipeline, specifically because "GNU Make always prefers an explicit rule over a pattern rule for the same target" and the override is "the only way to route that target through the same .sql.in / version-sed pipeline." So pgxntool's native generation for the current-version file doesn't run "on top of" the .sql.in-built base — it's replaced/overridden by cat_tools' own rule. The surrounding point (this preprocessing layer is repo-specific, not general pgxntool behavior) is correct; only the "runs on top of" mechanics are wrong.

Fix this →

Everything else in this commit's rewrite (the bulleted vs. numbered restructuring, the ../ai/CLAUDE.md pointer scoping, the stable pseudo-version explanation) checks out against sql.mk and sql/.gitignore.

[github-actions]

Code Review in progress

• Gather context (PR diff, CLAUDE.md before/after, prior review comments)
• Check whether the two previously-flagged issues (dangling "rule 5" references, .sql.in/pgxntool mechanics description) are still present after the latest push
• Review current full diff for any new issues
• Post final review feedback

View job run

[github-actions]

Claude Code is working…

I'll analyze this and get back to you.

View job run