Merge TASK-076: replace tautological-pass blocks in TLS test lanes

Replaces ~25 LT_CHECK_EQ(1,1) tautologies in ws_start_stop.cpp with
LT_SKIP / LT_SKIP_IF (new littletest macros, Automake exit-77 semantics)
or typed std::exception catches that distinguish "config unsupported"
from "config broken". Adds tls-no-cli CI matrix lane and a regression
gate (lint-no-tautological-asserts) wired into make check-local.

Includes iter-1 review-cleanup fixes (test-quality-reviewer majors) and
28 persisted unworked findings.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: etr

.github/workflows/verify-build.yml

@@ -304,6 +304,24 @@ jobs:
             coverage: nocoverage
             linking: dynamic
             shell: bash
+          # TASK-076: TLS-no-CLI lane. Installs libgnutls28-dev (so the
+          # library compiles WITH HAVE_GNUTLS) but deliberately omits
+          # `gnutls-bin`, so the gnutls-cli binary is NOT on $PATH. The
+          # five `psk_connection_*` tests in test/integ/ws_start_stop.cpp
+          # must report `[SKIP]` (via LT_SKIP_IF(!has_gnutls_cli(), ...))
+          # rather than tautological PASS. Post-test verification step
+          # below greps the test log for the [SKIP] markers.
+          - test-group: extra
+            os: ubuntu-latest
+            os-type: ubuntu
+            build-type: tls-no-cli
+            compiler-family: gcc
+            c-compiler: gcc-14
+            cc-compiler: g++-14
+            debug: nodebug
+            coverage: nocoverage
+            linking: dynamic
+            shell: bash
           - test-group: basic
             os: windows-latest
             os-type: windows
@@ -565,7 +583,23 @@ jobs:
       # TASK-037: skip gnutls install on the flag-invariance-off lane so
       # HAVE_GNUTLS auto-detects to off (the configure script just
       # AC_CHECK_HEADER's gnutls/gnutls.h, no header == HAVE_GNUTLS=0).
-      if: ${{ matrix.os-type == 'ubuntu' && matrix.build-type != 'flag-invariance-off' }}
+      # TASK-076: also skip on the tls-no-cli lane — it does its own
+      # install of libgnutls28-dev WITHOUT gnutls-bin in the next step
+      # so the per-test LT_SKIP_IF(!has_gnutls_cli(), ...) gate fires.
+      if: ${{ matrix.os-type == 'ubuntu' && matrix.build-type != 'flag-invariance-off' && matrix.build-type != 'tls-no-cli' }}
+
+    - name: Setup gnutls dependency WITHOUT gnutls-cli (TASK-076 tls-no-cli lane)
+      run: |
+        sudo apt-get install libgnutls28-dev ;
+        # Deliberate: NO gnutls-bin here. The lane asserts that
+        # has_gnutls_cli() returns false at runtime, which makes the
+        # five `psk_connection_*` tests in ws_start_stop.cpp emit
+        # `[SKIP]` rather than tautological PASS.
+        if which gnutls-cli >/dev/null 2>&1; then
+          echo "ERROR: gnutls-cli is on PATH but the tls-no-cli lane requires it absent" >&2
+          exit 1
+        fi
+      if: ${{ matrix.build-type == 'tls-no-cli' }}
 
     - name: Fetch libmicrohttpd from cache
       id: cache-libmicrohttpd
@@ -923,6 +957,56 @@ jobs:
         make check-hygiene
       if: ${{ matrix.build-type == 'header-hygiene' }}
 
+    - name: Verify [SKIP] markers fire on tls-no-cli lane (TASK-076)
+      # The five `psk_connection_*` tests in ws_start_stop.cpp gate on
+      # has_gnutls_cli(); since this lane installs libgnutls28-dev WITHOUT
+      # gnutls-bin, the gate must fire. The runner's stdout must contain
+      # at least 5 [SKIP] markers AND zero [CHECK FAILURE] / [ASSERT
+      # FAILURE] markers attributable to a psk_connection_* test. The
+      # ws_start_stop binary log is at build/test/ws_start_stop.log
+      # (Automake's per-test capture).
+      run: |
+        set -euo pipefail
+        cd build
+        LOG=test/ws_start_stop.log
+        if [ ! -f "$LOG" ]; then
+            echo "ERROR: $LOG missing — ws_start_stop did not run" >&2
+            exit 1
+        fi
+        SKIP_COUNT=$(grep -c '^\[SKIP\].*gnutls-cli' "$LOG" || true)
+        echo "Found $SKIP_COUNT [SKIP] markers attributable to gnutls-cli"
+        if [ "$SKIP_COUNT" -lt 5 ]; then
+            echo "ERROR: expected >=5 [SKIP] markers in $LOG; got $SKIP_COUNT" >&2
+            cat "$LOG"
+            exit 1
+        fi
+        if grep -E '\[(CHECK|ASSERT) FAILURE\].*psk_connection' "$LOG"; then
+            echo "ERROR: a psk_connection_* test reported FAILURE in tls-no-cli lane" >&2
+            exit 1
+        fi
+      if: ${{ matrix.build-type == 'tls-no-cli' }}
+
+    - name: Verify TLS blocks exercised when gnutls-cli is present (TASK-076)
+      # Canary invariant on a representative healthy gnutls-bin-installed
+      # lane: the psk_connection_* tests must NOT report [SKIP]. If they
+      # do, gnutls-cli detection regressed. Runs on the classic
+      # ubuntu/gcc/nodebug/dynamic baseline only.
+      run: |
+        set -euo pipefail
+        cd build
+        LOG=test/ws_start_stop.log
+        if [ ! -f "$LOG" ]; then
+            echo "ERROR: $LOG missing — ws_start_stop did not run" >&2
+            exit 1
+        fi
+        if grep -E '^\[SKIP\].*psk_connection' "$LOG"; then
+            echo "ERROR: psk_connection_* skipped on a lane that has gnutls-bin" >&2
+            cat "$LOG"
+            exit 1
+        fi
+        echo "PASS — no psk_connection_* SKIPs on the with-gnutls baseline lane"
+      if: ${{ matrix.os-type == 'ubuntu' && matrix.test-group == 'basic' && matrix.compiler-family == 'gcc' && matrix.debug == 'nodebug' && matrix.linking == 'dynamic' && matrix.build-type == 'classic' }}
+
     - name: Print tests results
       shell: bash
       run: |

Makefile.am

@@ -47,6 +47,8 @@ EXTRA_DIST = libhttpserver.pc.in $(DX_CONFIG) scripts/extract-release-notes.sh s
 	scripts/check-file-size.sh \
 	scripts/check-warning-suppressions.sh \
 	scripts/check-server-ready-helper.sh \
+	scripts/check-no-tautological-asserts.sh \
+	scripts/test_check_littletest_skip_exit_code.sh \
 	scripts/verify-installed-examples.sh \
 	test/headers/consumer_direct.cpp test/headers/consumer_detail.cpp test/headers/consumer_detail_modded.cpp \
 	test/headers/consumer_umbrella.cpp \
@@ -369,7 +371,7 @@ check-hygiene:
 # staged the install; sub-check skips the install step to avoid double cost.
 # This knob is set only by check-local; do not set it when invoking sub-checks
 # standalone.
-check-local: check-headers check-examples check-readme check-release-notes check-doxygen check-hooks-doc-spotcheck lint-warning-suppressions lint-server-ready-helper
+check-local: check-headers check-examples check-readme check-release-notes check-doxygen check-hooks-doc-spotcheck lint-warning-suppressions lint-server-ready-helper lint-no-tautological-asserts lint-littletest-skip-exit-code
 	@echo "=== Shared staged install for check-install-layout and check-hygiene ==="
 	@rm -rf "$(abs_top_builddir)/.shared-check-stage"
 	@$(MAKE) $(AM_MAKEFLAGS) install DESTDIR="$(abs_top_builddir)/.shared-check-stage" >check-shared-install.log 2>&1 || { \
@@ -485,7 +487,30 @@ lint-server-ready-helper:
 	@echo "=== lint-server-ready-helper: forbid bare server-ready sleeps in hooks_* integ tests ==="
 	@$(top_srcdir)/scripts/check-server-ready-helper.sh
 
-.PHONY: check-headers check-install-layout check-hygiene check-local check-examples check-readme check-release-notes check-doxygen check-hooks-doc-spotcheck check-soversion check-parallel-install lint-complexity lint-duplication lint-file-size lint-warning-suppressions lint-server-ready-helper
+# TASK-076: forbid `LT_CHECK_EQ(1, 1)` in test/integ/ws_start_stop.cpp.
+# Pre-TASK-076 ~33 catches in the TLS test suite used the tautological
+# assertion as a fake "skip" — a build that silently lost TLS support
+# would still report PASS. The replacement uses LT_SKIP_IF (added to
+# test/littletest.hpp by TASK-076) which reports SKIP. This gate
+# prevents regressing back to the broken pattern in ws_start_stop.cpp.
+# Wired into `make check` via check-local; pure bash/grep, runs in
+# every CI lane.
+lint-no-tautological-asserts:
+	@echo "=== lint-no-tautological-asserts: forbid tautological pseudo-skip in ws_start_stop.cpp ==="
+	@$(top_srcdir)/scripts/check-no-tautological-asserts.sh
+
+# TASK-076: pin the LT_SKIP exit-code semantics in test/littletest.hpp.
+# Asserts (a) an all-skip binary exits 77 (Automake SKIP), (b) a mixed
+# pass+skip binary exits 0 and emits both `[SKIP]` and `-> N skipped`
+# stdout markers. The textual markers are what CI greps for in the
+# tls-no-cli lane to assert per-test SKIPs fired. Wired into `make
+# check` via check-local; needs only a C++ compiler on $PATH so it
+# runs in every lane.
+lint-littletest-skip-exit-code:
+	@echo "=== lint-littletest-skip-exit-code: pin LT_SKIP exit-code semantics ==="
+	@$(top_srcdir)/scripts/test_check_littletest_skip_exit_code.sh
+
+.PHONY: check-headers check-install-layout check-hygiene check-local check-examples check-readme check-release-notes check-doxygen check-hooks-doc-spotcheck check-soversion check-parallel-install lint-complexity lint-duplication lint-file-size lint-warning-suppressions lint-server-ready-helper lint-no-tautological-asserts lint-littletest-skip-exit-code
 
 # TASK-039: top-level convenience rule that descends into test/ to
 # build and run the bench binaries (see test/Makefile.am and

RELEASE_NOTES.md

@@ -344,6 +344,23 @@ v2 is a clean rename, not an ABI overlay over v1. v1.x is end-of-life
 on the day v2.0 ships — there is no v1 maintenance branch (PRD §1,
 DR-011 ([specs/architecture/11-decisions/DR-011.md](specs/architecture/11-decisions/DR-011.md))).
 
+## Test infrastructure
+
+- **`LT_SKIP` / `LT_SKIP_IF` macros (TASK-076).** The internal
+  `test/littletest.hpp` framework now distinguishes SKIP from PASS.
+  Test bodies that depend on a runtime resource (for example
+  `gnutls-cli` for the PSK connection tests in
+  `test/integ/ws_start_stop.cpp`) now call
+  `LT_SKIP_IF(cond, reason)` instead of recording a tautological
+  `LT_CHECK_EQ(1, 1)`. A binary whose only outcomes are skips exits
+  77 (Automake's SKIP code from `test-driver`); a binary with mixed
+  skips and successes exits 0 and the runner summary reports
+  `-> N skipped`. The TLS lanes in `ws_start_stop.cpp` now skip — not
+  silently pass — when GnuTLS or `gnutls-cli` is absent, so a build
+  that silently lost TLS support is no longer hidden behind a green
+  CI signal. Two new CI lanes (`tls-no-cli`, plus a baseline canary)
+  assert the SKIP wiring fires (or does not) as configured.
+
 ## See also
 
 - [README.md](README.md) — full v2.0 introduction and worked examples.

scripts/check-no-tautological-asserts.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# TASK-076 regression gate: forbid `LT_CHECK_EQ(1, 1)` in
+# test/integ/ws_start_stop.cpp.
+#
+# The pattern was used as a fake "skip" before LT_SKIP / LT_SKIP_IF
+# existed in test/littletest.hpp. A build that silently lost TLS support
+# would still report green because every catch block in the TLS suite
+# swallowed the exception with a tautological `LT_CHECK_EQ(1, 1)`.
+# TASK-076 replaced all 33 occurrences with either:
+#   (a) `LT_SKIP_IF(cond, reason)` for environment-conditional skips
+#       (e.g. gnutls-cli absent from PATH); or
+#   (b) a real postcondition assertion / typed catch + re-throw for
+#       cases where the implementation should be exercised; or
+#   (c) deletion of redundant tail-position liveness pseudo-asserts.
+#
+# This gate keeps the regression visible by failing if any future patch
+# reintroduces the pattern in ws_start_stop.cpp. The scope is
+# intentionally narrow — `test/integ/basic.cpp:1877` and
+# `test/unit/no_v1_compat_shim_test.cpp:96` both use the same textual
+# pattern as intentional liveness/compile-sentinel assertions and are
+# NOT covered by this gate (the task wording scopes only to
+# ws_start_stop.cpp).
+#
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+FILE="$REPO_ROOT/test/integ/ws_start_stop.cpp"
+
+if [ ! -f "$FILE" ]; then
+    echo "ERROR: $FILE missing" >&2
+    exit 1
+fi
+
+if grep -nE 'LT_CHECK_EQ\(1, *1\)' "$FILE"; then
+    echo "ERROR: LT_CHECK_EQ(1, 1) found in $FILE." >&2
+    echo "       Use LT_SKIP_IF(...) for environment-conditional skips" >&2
+    echo "       (see TASK-076). The tautological assertion masks broken" >&2
+    echo "       TLS builds as PASS instead of SKIP." >&2
+    exit 1
+fi
+
+echo "PASS — no tautological LT_CHECK_EQ(1, 1) in $(realpath --relative-to="$REPO_ROOT" "$FILE" 2>/dev/null || echo "$FILE")"

scripts/test_check_littletest_skip_exit_code.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+#
+# TASK-076 Cycle 1 / sentinel for `LT_SKIP` exit-code plumbing.
+#
+# Asserts that the littletest binary semantics for SKIP are:
+#
+#   (a) A binary whose only outcomes are SKIPs exits 77 (Automake's SKIP
+#       code from `test-driver` line 131: `77:*) col=$blu res=SKIP …`).
+#       This is what makes "all dependencies missing" reportable to
+#       Automake as SKIP rather than PASS — the regression the rest of
+#       TASK-076 patches at every TLS test site.
+#
+#   (b) A binary that mixes passes and skips exits 0 (the existing
+#       behaviour; SKIPs do not "infect" a successful run).
+#
+# The script compiles two tiny throwaway TUs against the in-tree
+# `test/littletest.hpp` and runs them. It is wired into Makefile.am as a
+# `lint-`-style script (no library link required); it does NOT depend on
+# anything libhttpserver-specific so it can run on any host with a C++
+# compiler.
+#
+# Exit codes:
+#   0 — both assertions held.
+#   1 — at least one assertion failed.
+#
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+LITTLETEST_HDR="$REPO_ROOT/test/littletest.hpp"
+if [ ! -f "$LITTLETEST_HDR" ]; then
+    echo "ERROR: $LITTLETEST_HDR missing" >&2
+    exit 1
+fi
+
+CXX="${CXX:-c++}"
+
+TMPDIR_=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_"' EXIT
+
+# ---- (a) all-skip → exit 77 -------------------------------------------------
+cat > "$TMPDIR_/only_skips.cpp" <<'EOF'
+#include "littletest.hpp"
+
+LT_BEGIN_SUITE(only_skips_suite)
+    void set_up() {}
+    void tear_down() {}
+LT_END_SUITE(only_skips_suite)
+
+LT_BEGIN_AUTO_TEST(only_skips_suite, this_test_only_skips)
+    LT_SKIP("dependency missing");
+LT_END_AUTO_TEST(this_test_only_skips)
+
+LT_BEGIN_AUTO_TEST_ENV()
+    AUTORUN_TESTS()
+LT_END_AUTO_TEST_ENV()
+EOF
+
+"$CXX" -std=c++20 -I"$REPO_ROOT/test" \
+    "$TMPDIR_/only_skips.cpp" -o "$TMPDIR_/only_skips"
+
+set +e
+"$TMPDIR_/only_skips" > "$TMPDIR_/only_skips.log" 2>&1
+ec_a=$?
+set -e
+
+if [ "$ec_a" -ne 77 ]; then
+    echo "FAIL (a): all-skip binary exited $ec_a, expected 77" >&2
+    cat "$TMPDIR_/only_skips.log" >&2
+    exit 1
+fi
+
+# ---- (b) pass + skip → exit 0 ----------------------------------------------
+cat > "$TMPDIR_/mixed.cpp" <<'EOF'
+#include "littletest.hpp"
+
+LT_BEGIN_SUITE(mixed_suite)
+    void set_up() {}
+    void tear_down() {}
+LT_END_SUITE(mixed_suite)
+
+LT_BEGIN_AUTO_TEST(mixed_suite, this_passes)
+    LT_CHECK_EQ(1 + 1, 2);
+LT_END_AUTO_TEST(this_passes)
+
+LT_BEGIN_AUTO_TEST(mixed_suite, this_skips)
+    LT_SKIP("dependency missing");
+LT_END_AUTO_TEST(this_skips)
+
+LT_BEGIN_AUTO_TEST_ENV()
+    AUTORUN_TESTS()
+LT_END_AUTO_TEST_ENV()
+EOF
+
+"$CXX" -std=c++20 -I"$REPO_ROOT/test" \
+    "$TMPDIR_/mixed.cpp" -o "$TMPDIR_/mixed"
+
+set +e
+"$TMPDIR_/mixed" > "$TMPDIR_/mixed.log" 2>&1
+ec_b=$?
+set -e
+
+if [ "$ec_b" -ne 0 ]; then
+    echo "FAIL (b): mixed pass+skip binary exited $ec_b, expected 0" >&2
+    cat "$TMPDIR_/mixed.log" >&2
+    exit 1
+fi
+
+# Confirm the binary emitted the `[SKIP]` marker and the `-> N skipped`
+# runner summary line — these are the textual contracts the CI lane
+# greps for to assert per-test SKIPs in ws_start_stop fired.
+if ! grep -q '^\[SKIP\] ' "$TMPDIR_/mixed.log"; then
+    echo "FAIL (b): mixed binary stdout missing '[SKIP] ' marker" >&2
+    cat "$TMPDIR_/mixed.log" >&2
+    exit 1
+fi
+if ! grep -qE '^-> [0-9]+ skipped' "$TMPDIR_/mixed.log"; then
+    echo "FAIL (b): runner summary missing '-> N skipped' line" >&2
+    cat "$TMPDIR_/mixed.log" >&2
+    exit 1
+fi
+
+echo "PASS — littletest SKIP exit-code semantics held (77 for all-skip, 0 for mixed)"

specs/tasks/M7-v2-cleanup/TASK-076.md

@@ -8,12 +8,12 @@
 `ws_start_stop.cpp` carries ~20 `try { ws.start() } catch { LT_CHECK_EQ(1,1); return; }` blocks across SSL/mTLS/PSK/SNI sections, plus 5 more `if (!has_gnutls_cli()) { LT_CHECK_EQ(1,1); return; }` env-gates. On hosts without GnuTLS or `gnutls-cli`, the entire TLS suite reduces to `LT_CHECK_EQ(1,1)` passes — a build that silently lost TLS support would still report green. Replace these with a real fail-fast or skip mechanism that distinguishes "configuration not supported" from "configuration broken".
 
 **Action Items:**
-- [ ] Audit each `LT_CHECK_EQ(1,1)` at the lines listed in the audit (759, 789, 914, 949, 1016, 1051, 1091, 1129, 1171, 1212, 1266, 1367, 1486, 1512, 1537, 1552, 1599, 1642, 1685, 1728, plus env-gates at 1550, 1597, 1640, 1683, 1726).
-- [ ] For each, classify:
-  - (a) Environment lacks TLS dependencies → use the littletest `LT_SKIP_IF(!has_gnutls(), "gnutls not available")` (or equivalent) macro that the runner reports as `SKIP`, not `PASS`. Add such a macro if littletest does not have one.
-  - (b) Environment supports TLS but a specific cipher/PSK config is rejected → assert specifically on that rejection rather than swallowing all exceptions; the test must distinguish "expected reject" from "implementation broken".
-- [ ] Add a CI matrix lane that runs `ws_start_stop.cpp` on a host *with* GnuTLS + `gnutls-cli` and a separate lane that asserts the suite reports `SKIP` (not `PASS`) when they are absent.
-- [ ] RELEASE_NOTES.md "Test infrastructure" note (if applicable) on the new skip semantics.
+- [x] Audit each `LT_CHECK_EQ(1,1)` at the lines listed in the audit (759, 789, 914, 949, 1016, 1051, 1091, 1129, 1171, 1212, 1266, 1367, 1486, 1512, 1537, 1552, 1599, 1642, 1685, 1728, plus env-gates at 1550, 1597, 1640, 1683, 1726). The implementation grepped the full set at start-of-cycle and replaced all 33 matches (the plan audit covered 8 lines the original task enumeration omitted).
+- [x] For each, classify:
+  - (a) Environment lacks TLS dependencies → emitted `LT_SKIP_IF(...)` via the new littletest macro (added to `test/littletest.hpp`). Runner reports `[SKIP]`, not `PASS`; a binary whose only outcomes are SKIPs exits 77 (Automake SKIP).
+  - (b) Environment supports TLS but a specific cipher/PSK config is rejected → typed catch on `std::exception` + substring-match on `is_psk_unsupported_error(e)` for SKIP, otherwise `throw;` so implementation-broken cases fail loudly.
+- [x] Added a CI matrix lane (`build-type: tls-no-cli`) that runs `ws_start_stop.cpp` with `libgnutls28-dev` installed but `gnutls-bin` deliberately absent; the post-test verification step greps `test/ws_start_stop.log` for ≥5 `[SKIP]` markers (the five `psk_connection_*` tests) and zero `[CHECK/ASSERT FAILURE]` lines. A separate canary step on the baseline `classic` lane asserts those tests do NOT report SKIP when `gnutls-bin` is present.
+- [x] Added RELEASE_NOTES.md "Test infrastructure" section documenting `LT_SKIP` / `LT_SKIP_IF` and the new exit-77 semantics.
 
 **Dependencies:**
 - Blocked by: None
@@ -30,4 +30,4 @@
 **Related Requirements:** PRD §2 test reliability NFR
 **Related Decisions:** None new
 
-**Status:** Backlog
+**Status:** Done

specs/tasks/M7-v2-cleanup/_index.md

@@ -40,7 +40,7 @@ TASK-093).
 | TASK-073 | Revisit libmicrohttpd v0.99 unescape workaround | LOW | S | Done |
 | TASK-074 | Gate DEBUG raw-body printing behind explicit opt-in | LOW (sec) | S | Done |
 | TASK-075 | Propagate `wait_for_server_ready` to sibling hooks integ tests | HIGH | M | Done |
-| TASK-076 | Replace tautological-pass blocks in TLS test lanes | HIGH | M | Backlog |
+| TASK-076 | Replace tautological-pass blocks in TLS test lanes | HIGH | M | Done |
 | TASK-077 | Restore Windows / Darwin coverage in skipped test suites | HIGH | L | Backlog |
 | TASK-078 | Resolve commented-out CONNECT-method test bodies | HIGH | S | Backlog |
 | TASK-079 | Drive nonce/opaque state machine in v2 digest-auth integ tests | MED | M | Backlog |