PG compatibility: documentation and final verification (Task 12)

[renecannao]

Context

This issue tracks Task 12 from docs/superpowers/plans/2026-06-11-postgresql-libpg-query-compatibility.md.

Goal

Document how to run and verify the PostgreSQL compatibility harness end to end.

Files

• Modify README.md
• Modify docs/benchmarks/REPRODUCING.md

What the next agent should do

• Document libpg_query as the PostgreSQL syntax oracle.
• Explain DEEP_SUPPORTED versus CLASSIFIED_ONLY.
• Document make test-pg-compat, make pg-compat, and make pg-compat-refresh.
• List the external prerequisites and the PG_COMPAT_CACHE location.
• Run the final verification commands from the plan.

Acceptance

• The documentation is concise and accurate.
• The verification commands from the plan all pass.
• The repository has no unintended whitespace or status changes after the documentation update.

[renecannao]

Implemented Task 12 in commit 901f666 on PR #50.

Documentation added:

• README.md: PostgreSQL compatibility harness overview, libpg_query oracle role, result taxonomy, Makefile targets, and PG_COMPAT_CACHE default.
• docs/benchmarks/REPRODUCING.md: prerequisites, reproducible pg_compat workflow, refresh outputs, and distinction between DEEP_SUPPORTED and CLASSIFIED_ONLY.

Fresh verification run before closing:

• make clean: passed.
• make test with local Homebrew dependency overrides: 1,299 tests run, 1,262 passed, 37 skipped.
• make test-pg-compat PG_COMPAT_CACHE=/tmp/parsersql-pg-compat-task9: 87 tests passed; checked 24,080 committed pg_compat CI cases.
• make pg-compat PG_COMPAT_CACHE=/tmp/parsersql-pg-compat-task9: skipped 13 known invalid/unsplittable PostgreSQL corpus files per oracle role; checked 24,080 committed pg_compat CI cases; committed PostgreSQL compatibility baseline matches.
• git diff --check: passed.
• git status --short: clean after commit.

Review checks:

• No libpg_query references under include/ or src/; production parser targets do not link it.
• No upstream checkout or oracle binary is committed; only harness scripts/report paths reference the oracle.
• Committed PostgreSQL result taxonomy verified against the six allowed values.
• Unmapped PostgreSQL top-level nodes are covered by UNMAPPED_NODE_CASE tests and fail the harness as infrastructure/reporting errors instead of silently passing.