Separate test debug from script debug; add commit-time level check

.claude/agents/test.md

@@ -35,7 +35,7 @@ make clean-envs && test/bats/bin/bats tests/04-pgtle.bats
 ✅ **DO THIS**:
 ```bash
 test/bats/bin/bats tests/04-pgtle.bats  # Auto-rebuilds if needed
-DEBUG=5 test/bats/bin/bats tests/04-pgtle.bats  # For investigation
+TESTDEBUG=5 test/bats/bin/bats tests/04-pgtle.bats  # For investigation
 ```
 
 **ONLY clean when debugging the cleanup mechanism itself** and you MUST document what cleanup failure you're investigating.
@@ -228,11 +228,11 @@ test/bats/bin/bats tests/test-pgtle-install.bats
 
 ### Debugging
 ```bash
-DEBUG=2 test/bats/bin/bats tests/01-meta.bats  # Debug output
+TESTDEBUG=2 test/bats/bin/bats tests/01-meta.bats  # Debug output
 test/bats/bin/bats --verbose tests/01-meta.bats  # BATS verbose mode
 ```
 
-**Debug levels**: 10 (critical), 20 (significant), 30 (general), 40 (verbose), 50+ (maximum)
+**Debug levels** (set via `TESTDEBUG`): 1 (pollution/critical), 2 (major workflow), 3 (detailed state), 5 (verbose internals)
 
 ---
 
@@ -247,7 +247,8 @@ Tests set these automatically (from `tests/helpers.bash`):
 - `PGXNBRANCH` - Branch to use (defaults to `master`)
 - `TEST_TEMPLATE` - Template directory (defaults to `${TOPDIR}/template`)
 - `PG_LOCATION` - PostgreSQL installation path
-- `DEBUG` - Debug level (0-5)
+- `TESTDEBUG` - Test infrastructure debug level (0-5); controls helpers.bash debug() output
+- `DEBUG` - pgxntool script debug level; controls debug() in pgxntool/lib.sh (independent of TESTDEBUG)
 
 ---
 
@@ -292,7 +293,7 @@ test/bats/bin/bats tests/04-pgtle.bats  # Auto-rebuilds foundation via ensure_fo
 ### Debugging Test Failures
 
 1. Read test output (which assertion failed?)
-2. Use DEBUG mode: `DEBUG=5 test/bats/bin/bats tests/test-name.bats`
+2. Use TESTDEBUG mode: `TESTDEBUG=5 test/bats/bin/bats tests/test-name.bats`
 3. Inspect environment: `cd .envs/sequential/repo && ls -la`
 4. Check state markers: `ls .envs/sequential/.bats-state/`
 5. **Work top-down**: Fix earliest failure first (downstream failures often cascade)
@@ -361,7 +362,7 @@ make test
 test/bats/bin/bats tests/04-pgtle.bats
 
 # Debug
-DEBUG=5 test/bats/bin/bats tests/04-pgtle.bats
+TESTDEBUG=5 test/bats/bin/bats tests/04-pgtle.bats
 
 # Test infrastructure
 make test-recursion

.claude/settings.json

@@ -2,17 +2,17 @@
   "permissions": {
     "allow": [
       "Bash(make:*)",
-      "Bash(DEBUG=1 make:*)",
-      "Bash(DEBUG=2 make:*)",
-      "Bash(DEBUG=3 make:*)",
-      "Bash(DEBUG=4 make:*)",
-      "Bash(DEBUG=5 make:*)",
+      "Bash(TESTDEBUG=1 make:*)",
+      "Bash(TESTDEBUG=2 make:*)",
+      "Bash(TESTDEBUG=3 make:*)",
+      "Bash(TESTDEBUG=4 make:*)",
+      "Bash(TESTDEBUG=5 make:*)",
       "Bash(test/bats/bin/bats:*)",
-      "Bash(DEBUG=1 test/bats/bin/bats:*)",
-      "Bash(DEBUG=2 test/bats/bin/bats:*)",
-      "Bash(DEBUG=3 test/bats/bin/bats:*)",
-      "Bash(DEBUG=4 test/bats/bin/bats:*)",
-      "Bash(DEBUG=5 test/bats/bin/bats:*)",
+      "Bash(TESTDEBUG=1 test/bats/bin/bats:*)",
+      "Bash(TESTDEBUG=2 test/bats/bin/bats:*)",
+      "Bash(TESTDEBUG=3 test/bats/bin/bats:*)",
+      "Bash(TESTDEBUG=4 test/bats/bin/bats:*)",
+      "Bash(TESTDEBUG=5 test/bats/bin/bats:*)",
       "Edit",
       "WebFetch",
 

.claude/skills/commit/SKILL.md

@@ -41,6 +41,18 @@ bash .claude/skills/commit/scripts/gather-repo-info.sh ../pgxntool .
 
 Review output. Identify which repos have changes.
 
+### 2b. Check Debug Level Distribution (pgxntool .sh changes only)
+
+If `../pgxntool/*.sh` files are in the diff, scan each changed file:
+
+1. Collect all `debug N` call levels
+2. Note whether the file contains loops (`for`, `while`)
+3. Flag if: file has loops AND every debug call uses a single-digit level (1-9)
+4. Flag if: file has 5+ debug calls AND they all use the exact same level
+
+This is **advisory only** — present any findings in Step 5 and let the user decide.
+If nothing looks off, say nothing (don't add noise to the common case).
+
 ### 3. Check HISTORY.asc (pgxntool changes only)
 
 Read `../pgxntool/HISTORY.asc`. Determine if changes are significant and user-visible:

.claude/skills/test/scripts/run-tests.sh

@@ -8,6 +8,16 @@
 
 set -euo pipefail
 
+# Set PGPORT from PGCLUSTER if not already set, so pg_regress and other raw
+# PostgreSQL binaries use the correct cluster (Debian pg_wrapper handles
+# PGCLUSTER but raw binaries only respect PGPORT).
+if [ -z "${PGPORT:-}" ] && [ -n "${PGCLUSTER:-}" ]; then
+    _port=$(pg_lsclusters -h 2>/dev/null | awk -v c="$PGCLUSTER" \
+        'BEGIN{split(c,a,"/"); v=a[1]; n=a[2]} $1==v && $2==n {print $3; exit}')
+    [ -n "$_port" ] && export PGPORT=$_port
+    unset _port
+fi
+
 # Determine log directory (per-project, based on working directory)
 LOG_DIR="/tmp/pgxntool-test-logs$(pwd | sed 's/\//_/g')"
 mkdir -p "$LOG_DIR"

test/lib/helpers.bash

@@ -70,13 +70,15 @@ error() {
 
 # Debug output function
 # Usage: debug LEVEL "message"
-# Outputs message if DEBUG >= LEVEL
+# Outputs message if TESTDEBUG >= LEVEL
+# Uses TESTDEBUG (not DEBUG) to avoid conflating test infrastructure verbosity
+# with pgxntool script verbosity — set them independently as needed.
 debug() {
   local level=$1
   shift
   local message="$*"
 
-  if [ "${DEBUG:-0}" -ge "$level" ]; then
+  if [ "${TESTDEBUG:-0}" -ge "$level" ]; then
     out -f "DEBUG[$level]: $message"
   fi
 }