Fix parallel-build SQL corruption, remote hardcoding, and add safety checks

CLAUDE.md

@@ -101,7 +101,7 @@ include pgxntool/base.mk
   - `PGXNVERSION` - version number
   - `EXTENSIONS` - list of extensions provided
   - `EXTENSION_*_VERSION` - per-extension versions
-  - `EXTENSION__CURRENT_VERSION__FILES` - auto-generated versioned SQL files
+  - `EXTENSION__CURRENT_VERSION__FILES` - the current/most-recent auto-generated versioned SQL file for each extension (not all version files)
 - `base.mk` includes `meta.mk` via `-include`
 
 ### The Magic of base.mk

HISTORY.asc

@@ -18,6 +18,30 @@ with a digit, so extensions using a persistent `stable` pseudo-version
 filename". Widened to accept any non-empty, `--`-free version string,
 matching how pg_tle itself treats extension versions.
 
+== Fix versioned SQL file corruption under overlapping make invocations
+The rule generating `sql/<ext>--<version>.sql` used a `>` truncate followed
+by a separate `>>` append, so a rule that fired more than once (e.g.
+overlapping `make` processes) doubled the file's content. Now uses a single
+atomic redirect.
+
+== Add `check-stale-expected` to catch orphaned test/expected files
+`make test` now fails if `test/expected/*.out` (or `test/build/expected/*.out`)
+has no corresponding `test/sql/*.sql` (or `test/build/*.sql`). If your project
+has genuinely stale expected-output files sitting around, `make test` will
+newly fail until they're removed. pg_regress's alternate expected-output
+files (`test_0.out` .. `test_9.out`) are recognized and not flagged as stale.
+
+== Add `PGXN_REMOTE` to override the remote used by tag/rmtag/forcetag/dist
+These targets hardcoded the `origin` remote, silently re-tagging the wrong
+repository for maintainers whose `origin` is a personal fork. Defaults to
+`origin`, so existing behavior is unchanged unless you set it.
+
+== Add include guard to base.mk
+`base.mk` could end up included twice in one `make` run (for example, an
+extension's own `.mk` module includes it in addition to the Makefile's own
+include), which redefined every target and printed overriding-recipe
+warnings. A second inclusion is now a harmless no-op.
+
 2.1.0
 -----
 == Fix setup.sh / pgxntool-sync.sh / update-setup-files.sh inside a git worktree

README.asc

@@ -603,6 +603,75 @@ Each generated SQL file is wrapped in a transaction (`BEGIN;` ... `COMMIT;`) to
 *Solution*: pg_tle only supports trusted languages. You cannot use C extensions with pg_tle. The script will warn you but still generate files (which won't work).
 
 NOTE: there are several untrusted languages (such as plpython), and the only tests for C.
+
+== Configuration Variables
+
+This is the comprehensive list of make variables you can override to customize pgxntool's behavior, either in your Makefile (before `include pgxntool/base.mk`) or on the `make` command line. Several of these are also covered in more detail in the sections above; this section exists so there's one place that lists all of them.
+
+NOTE: Variables marked with `*` must be set to exactly `yes` or `no` (case-insensitive) when given explicitly; any other value is a hard `make` error.
+
+=== PGXN_REMOTE
+
+Default: `origin`. The git remote used by `tag`, `rmtag`, `forcetag`, and `dist` (which depends on `tag`). If your `origin` is a personal fork rather than the canonical repository -- for example, if you develop on a fork and only push release tags to the canonical repo -- set this so tagging and pushing target the right remote:
+
+----
+make dist PGXN_REMOTE=upstream
+----
+
+=== ASCIIDOC
+
+Default: auto-detected, the first of `asciidoctor` or `asciidoc` found on `PATH`. Path to the Asciidoc processor used to build `.html` files from `$(ASCIIDOC_EXTS)` source files. Override if the processor you want isn't first on `PATH`, or isn't on `PATH` at all. See <<_document_handling>>.
+
+=== PG_CONFIG
+
+Default: `pg_config`. Path to the `pg_config` binary used to detect the PostgreSQL version and locate PGXS. Override when the right `pg_config` isn't the one on `PATH`, such as when testing against a specific PostgreSQL install.
+
+=== TESTDIR
+
+Default: `test`. Root directory for test input files: `$(TESTDIR)/sql/`, `$(TESTDIR)/expected/`, `$(TESTDIR)/build/`, `$(TESTDIR)/install/`. Overriding this on its own is unusual; it mainly exists so `TESTOUT` has a sensible default.
+
+=== TESTOUT
+
+Default: `$(TESTDIR)`. Directory `pg_regress` writes actual test output to -- `$(TESTOUT)/results/`, `$(TESTOUT)/regression.diffs`, etc. -- via `--outputdir` in `REGRESS_OPTS`. Kept separate from `TESTDIR` so generated output can be pointed somewhere other than the directory holding your checked-in `sql`/`expected` files, if you want that separation.
+
+=== PGXNTOOL_VERIFY_RESULTS_MODE
+
+Default: `pgtap`. Controls how the <<_verify_results_safeguard,verify-results safeguard>> decides whether tests are failing.
+
+==== pgtap
+
+Scans `test/results/*.out` for pgTap `not ok` lines and plan mismatches, falling back to checking for `regression.diffs` too. Use this mode when your test suite uses pgTap.
+
+==== diffs
+
+Checks only for `regression.diffs`, matching classic pg_regress behavior. Use this mode when your tests use plain SQL expected-output comparison only.
+
+=== PGXNTOOL_ENABLE_TEST_BUILD *
+
+Default: auto-detected -- `yes` if `test/build/*.sql` files exist, `no` otherwise. Enables or disables the <<_test_build,test-build>> pre-flight SQL check. Set explicitly to `yes` if you want an error when `test/build/` unexpectedly has no SQL files (catches accidental deletion of its contents), or to `no` to disable the check even when files are present.
+
+=== PGXNTOOL_ENABLE_TEST_INSTALL *
+
+Default: auto-detected -- `yes` if `test/install/*.sql` files exist, `no` otherwise. Enables or disables the <<_testinstall,test/install>> schedule-based setup feature. Same explicit-override semantics as `PGXNTOOL_ENABLE_TEST_BUILD`.
+
+=== PGXNTOOL_ENABLE_VERIFY_RESULTS *
+
+Default: `yes`. Enables or disables the <<_verify_results_safeguard,verify-results safeguard>> that blocks `make results` when tests are failing. Setting it to empty on the command line (`make PGXNTOOL_ENABLE_VERIFY_RESULTS= results`) also disables it.
+
+=== PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *
+
+Default: `yes`. Enables or disables the check-stale-expected safeguard, which fails `make test` if `test/expected/` (or `test/build/expected/`) contains a `.out` file with no corresponding `.sql` file -- catching a stale file left behind after a test was renamed or removed. Set to `no` to make the check a complete no-op (it's dropped from `TEST_DEPS` entirely).
+
+This is also the supported pattern for disabling one specific optional pgxntool feature: a documented `PGXNTOOL_ENABLE_*` variable, gating both the target's registration into `TEST_DEPS`/etc. and (where applicable) the target's own definition. Cleanly replacing or overriding an arbitrary pgxntool-generated recipe with your own entirely is a separate, larger, and not-yet-decided design question -- see https://github.com/Postgres-Extensions/pgxntool/issues/30[issue #30] (two proposed approaches) -- and is *not* what this mechanism solves.
+
+=== PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *
+
+Default: `yes`. Sub-check of check-stale-expected, independent of `PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED`: fails (with a distinct error message and exit code from the orphaned-`.out` check) if `test/expected/` (or `test/build/expected/`) contains any file that isn't `*.out`. Set to `no` to disable just this sub-check while leaving the orphaned-`.out` check active.
+
+=== PGXNTOOL_NO_PGXS_INCLUDE
+
+Default: unset (PGXS is included normally). Skips including PGXS (`$(PGXS)`) entirely. This is only for advanced scenarios where you need to manage the PGXS include yourself; most projects should never set this.
+
 == Copyright
 Copyright (c) 2026 Jim Nasby <Jim.Nasby@gmail.com>