Merge TASK-007 2nd-pass review cleanup (HYGIENE_STAMP + minors)

Pulls in two commits authored on the orphan fix/task-007-review-cleanup
worktree at /private/tmp/task-007-review-cleanup that the Pass 1 review
sweeper flagged as missing from feature/v2.0:

- 477a06f TASK-007 review cleanup: address cosmetic and minor behavioral
  findings (Makefile.am hygiene comments + sed-vs-awk + .PHONY, verify-build
  YAML, TASK-007/TASK-020 AC grep pattern, header_hygiene_test MSYS2 guard).
- dff19e5 TASK-007 review: broaden HYGIENE_STAMP deps to include Makefile.am
  and consumer TU.

Both commits were authored 2026-05-27 by Sebastiano Merlino with Claude
Sonnet 4.6 — the user's own work, just stranded on the fix branch.

# Conflicts:
#	Makefile.am

Author: etr

.github/workflows/verify-build.yml

@@ -263,9 +263,9 @@ jobs:
           # (preprocesses <httpserver.hpp> against the staged install and greps
           # for forbidden backend headers). Surfaces this gate as its own named
           # GitHub Actions check so reviewers see header-hygiene status
-          # independently of the broader `make check` log. Until M5 lands the
-          # check is informational (HEADER_HYGIENE_STRICT defaults to "no");
-          # TASK-020 flips it to strict.
+          # independently of the broader `make check` log. HEADER_HYGIENE_STRICT
+          # defaults to "yes" (flipped from "no" at TASK-020 close); any leak
+          # of forbidden backend headers through the umbrella fails CI loudly.
           - test-group: extra
             os: ubuntu-latest
             os-type: ubuntu
@@ -870,8 +870,8 @@ jobs:
       # TASK-007: dedicated public-header hygiene gate. Runs the
       # preprocessor-grep target (Layer 2) against a staged install and
       # reports any forbidden backend headers reaching <httpserver.hpp>.
-      # Currently informational (HEADER_HYGIENE_STRICT=no) -- TASK-020
-      # flips this to strict when M5 closes the umbrella.
+      # HEADER_HYGIENE_STRICT defaults to "yes" (set at TASK-020 close);
+      # any leak of forbidden backend headers through the umbrella fails CI.
       run: |
         cd build
         make check-hygiene
@@ -882,7 +882,7 @@ jobs:
       run: |
         cd build ;
         cat test/test-suite.log ;
-      if: ${{ failure() && matrix.build-type != 'iwyu' && matrix.compiler-family != 'arm-cross' }}
+      if: ${{ failure() && matrix.build-type != 'iwyu' && matrix.compiler-family != 'arm-cross' && matrix.build-type != 'header-hygiene' }}
 
     - name: Run Valgrind checks
       run: |

Makefile.am

@@ -264,10 +264,15 @@ check-install-layout:
 # it still fires on STLs that do not route std::thread through pthread.
 # ---------------------------------------------------------------------------
 
+# NOTE: each entry matches a basename; the grep in check-hygiene anchors with a
+# leading '/' so e.g. mypthread.h is not a false positive.  Keep this list in
+# sync with the #ifdef ladder in test/unit/header_hygiene_test.cpp.
 HEADER_HYGIENE_FORBIDDEN = microhttpd\.h|gnutls/gnutls\.h|sys/socket\.h|sys/uio\.h
-CHECK_HYGIENE_STAGE      = $(abs_top_builddir)/.hygiene-stage
-CHECK_HYGIENE_CXX        = $(CXX) -std=c++20 -E -I$(CHECK_HYGIENE_STAGE)$(includedir) $(CPPFLAGS)
-HEADER_HYGIENE_STRICT   ?= yes
+CHECK_HYGIENE_STAGE = $(abs_top_builddir)/.hygiene-stage
+CHECK_HYGIENE_CXX = $(CXX) -std=c++20 -E -I$(CHECK_HYGIENE_STAGE)$(includedir) $(CPPFLAGS)
+# Override on the command line to run against an in-flight umbrella:
+#   make check-hygiene HEADER_HYGIENE_STRICT=no
+HEADER_HYGIENE_STRICT ?= yes
 
 # Sentinel file: only re-run the staged install when headers have changed.
 # This is an mtime gate used exclusively for standalone `make check-hygiene`
@@ -277,7 +282,14 @@ HEADER_HYGIENE_STRICT   ?= yes
 # own pre-built shared stage, so this stamp target is bypassed entirely.
 HYGIENE_STAMP = $(CHECK_HYGIENE_STAGE)/.hygiene-stamp
 
-$(HYGIENE_STAMP): $(wildcard $(top_srcdir)/src/httpserver/*.hpp)
+# NOTE: wildcard is evaluated at parse time; run `make clean` if new headers
+# are added to src/httpserver/ in the same invocation that generates them.
+# Makefile.am and consumer_umbrella_no_backend.cpp are also listed so that
+# changes to HEADER_HYGIENE_FORBIDDEN or the consumer TU invalidate the stamp.
+$(HYGIENE_STAMP): $(wildcard $(top_srcdir)/src/httpserver/*.hpp) \
+                  $(top_srcdir)/src/httpserver.hpp \
+                  $(top_srcdir)/Makefile.am \
+                  $(top_srcdir)/test/headers/consumer_umbrella_no_backend.cpp
 	@rm -rf $(CHECK_HYGIENE_STAGE)
 	@$(MAKE) $(AM_MAKEFLAGS) install DESTDIR=$(CHECK_HYGIENE_STAGE) >check-hygiene-install.log 2>&1 || { \
 	    echo "FAIL: staged install failed"; cat check-hygiene-install.log; \
@@ -295,6 +307,11 @@ check-hygiene:
 	        echo "  Always pair CHECK_HYGIENE_SHARED=yes with CHECK_HYGIENE_STAGE=<valid-dir>."; \
 	        exit 1; \
 	    fi; \
+	    if ! test -f "$(CHECK_HYGIENE_STAGE)$(includedir)/httpserver.hpp"; then \
+	        echo "FAIL: CHECK_HYGIENE_STAGE exists but does not contain $(includedir)/httpserver.hpp"; \
+	        echo "  Was the staged install complete before invoking check-hygiene?"; \
+	        exit 1; \
+	    fi; \
 	fi
 	@status=0; \
 	if ! $(CHECK_HYGIENE_CXX) $(top_srcdir)/test/headers/consumer_umbrella_no_backend.cpp >check-hygiene.i 2>check-hygiene.err; then \
@@ -309,7 +326,7 @@ check-hygiene:
 	        sed 's/^/    /' check-hygiene.err | tail -10; \
 	    fi; \
 	else \
-	    leaks=`grep -hE '^# [0-9]+ "[^"]*/($(HEADER_HYGIENE_FORBIDDEN))"' check-hygiene.i | awk '{print $$3}' | sort -u`; \
+	    leaks=`grep -hE '^# [0-9]+ "[^"]*/($(HEADER_HYGIENE_FORBIDDEN))"' check-hygiene.i | sed 's/.*"\(.*\)".*/\1/' | sort -u`; \
 	    if test -n "$$leaks"; then \
 	        if test "$(HEADER_HYGIENE_STRICT)" = "yes"; then \
 	            echo "FAIL: forbidden headers leaked through <httpserver.hpp>:"; \
@@ -333,20 +350,25 @@ check-hygiene:
 # staged install to avoid paying two full `make install` costs on every
 # `make check`. Both install-backed sub-checks can still be invoked standalone
 # (they will do their own install when CHECK_*_SHARED is not set).
+#
+# CHECK_INSTALL_SHARED=yes / CHECK_HYGIENE_SHARED=yes: the caller has already
+# 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
 	@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 || { \
+	@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 || { \
 	    echo "FAIL: shared staged install failed"; cat check-shared-install.log; \
-	    rm -f check-shared-install.log; rm -rf $(abs_top_builddir)/.shared-check-stage; exit 1; }
+	    rm -f check-shared-install.log; rm -rf "$(abs_top_builddir)/.shared-check-stage"; exit 1; }
 	@rm -f check-shared-install.log
 	@$(MAKE) $(AM_MAKEFLAGS) check-install-layout \
-	    CHECK_INSTALL_STAGE=$(abs_top_builddir)/.shared-check-stage \
+	    CHECK_INSTALL_STAGE="$(abs_top_builddir)/.shared-check-stage" \
 	    CHECK_INSTALL_SHARED=yes
 	@$(MAKE) $(AM_MAKEFLAGS) check-hygiene \
-	    CHECK_HYGIENE_STAGE=$(abs_top_builddir)/.shared-check-stage \
+	    CHECK_HYGIENE_STAGE="$(abs_top_builddir)/.shared-check-stage" \
 	    CHECK_HYGIENE_SHARED=yes
-	@rm -rf $(abs_top_builddir)/.shared-check-stage
+	@rm -rf "$(abs_top_builddir)/.shared-check-stage"
 
 # TASK-040: enforce static invariants on the two flagship examples
 # (hello_world.cpp <= 10 LOC, lambda-only; shared_state.cpp class+mutex).
@@ -429,7 +451,7 @@ lint-file-size:
 	@echo "=== lint-file-size: enforce per-file line-count ceiling ==="
 	@$(top_srcdir)/scripts/check-file-size.sh
 
-.PHONY: check-headers check-install-layout check-hygiene 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
+.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
 
 # TASK-039: top-level convenience rule that descends into test/ to
 # build and run the bench binaries (see test/Makefile.am and
@@ -449,7 +471,7 @@ MOSTLYCLEANFILES = $(DX_CLEANFILES) *.gcda *.gcno *.gcov \
 DISTCLEANFILES = DIST_REVISION
 
 clean-local:
-	rm -rf $(CHECK_HYGIENE_STAGE) $(abs_top_builddir)/.shared-check-stage $(CHECK_INSTALL_STAGE)
+	rm -rf "$(CHECK_HYGIENE_STAGE)" "$(abs_top_builddir)/.shared-check-stage" "$(CHECK_INSTALL_STAGE)"
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libhttpserver.pc

specs/tasks/M1-foundation/TASK-007.md

@@ -19,7 +19,7 @@ Lock in the "no backend headers leak through `<httpserver.hpp>`" invariant with
 - Blocks: None (informational gate; will fail until M2-M5 land, that's expected and intended)
 
 **Acceptance Criteria:**
-- `grep -lE 'microhttpd\.h|pthread\.h|gnutls\.h|sys/socket\.h' src/httpserver/*.hpp` returns no results once M2-M5 land (PRD §3.1 acceptance).
+- `grep -lE 'microhttpd\.h|pthread\.h|gnutls/gnutls\.h|sys/socket\.h' src/httpserver/*.hpp` returns no results once M2-M5 land (PRD §3.1 acceptance).
 - The hygiene test is invoked by `make check` and fails loudly when violated.
 - Typecheck passes.
 

specs/tasks/M3-request/TASK-020.md

@@ -20,7 +20,7 @@ Verify and lock the "no backend headers in public surface" invariant after PIMPL
 - Blocks: None (gating outcome that the rest of the project relies on)
 
 **Acceptance Criteria:**
-- `grep -lE 'microhttpd\.h|pthread\.h|gnutls\.h|sys/socket\.h' src/httpserver/*.hpp` returns no results (PRD §3.1 acceptance).
+- `grep -lE 'microhttpd\.h|pthread\.h|gnutls/gnutls\.h|sys/socket\.h' src/httpserver/*.hpp` returns no results (PRD §3.1 acceptance).
 - A test program containing only `#include <httpserver.hpp>` and `int main(){}` compiles without `-I` to libmicrohttpd / pthread / gnutls (PRD §3.1 acceptance).
 - TASK-007's hygiene test (red until now) goes green.
 - Typecheck passes.

test/unit/header_hygiene_test.cpp

@@ -44,11 +44,12 @@
 //      XPASS (a hard error by default) -- which is the explicit signal
 //      for TASK-020 to remove the XFAIL_TESTS marker.
 //
-// Guard-macro mapping (verified on glibc, musl, macOS/BSD):
+// Guard-macro mapping (verified on glibc, musl, macOS/BSD, MSYS2/MINGW64):
 //
 //   <microhttpd.h>     -> MHD_VERSION       (defined unconditionally inside)
 //   <pthread.h>        -> _PTHREAD_H        (glibc/musl, AND macOS/Apple SDK)
 //                         _PTHREAD_H_       (some BSDs)
+//                         _WINPTHREADS_H    (MSYS2/MINGW64 winpthreads)
 //   <gnutls/gnutls.h>  -> GNUTLS_GNUTLS_H   (the library's own include guard)
 //   <sys/socket.h>     -> _SYS_SOCKET_H     (glibc/musl)
 //                         _SYS_SOCKET_H_    (macOS/BSD)
@@ -78,10 +79,20 @@
 // preprocessor-grep target `make check-hygiene` in the top-level
 // Makefile.am. Keep both lists in sync.
 
+// <cstdio> is included before <httpserver.hpp> for fprintf availability.
+// The forbidden-header macro checks in main() are compile-time (#ifdef) guards
+// evaluated after the umbrella include, so <cstdio>'s transitive headers cannot
+// mask any umbrella-leaked macro.  Unlike consumer_umbrella_no_backend.cpp
+// (which avoids all standard-library includes for a strict Layer 2 isolation
+// test), this sentinel requires fprintf for human-readable runtime reporting.
 #include <cstdio>
 
 #include <httpserver.hpp>
 
+// Deliberate multi-assert design: all forbidden-header checks share a single
+// accumulator so CI logs show every leaked header in one run, not just the
+// first.  Each #ifdef block is independent; a single-assert style would stop
+// at the first failure and hide remaining leaks.
 int main() {
     int leaks = 0;
 
@@ -114,6 +125,11 @@ int main() {
     std::fprintf(stderr, "LEAK: <pthread.h> reached the consumer TU (macOS/BSD guard _PTHREAD_H_)\n");
     ++leaks;
 #endif
+
+#ifdef _WINPTHREADS_H
+    std::fprintf(stderr, "LEAK: <pthread.h> reached the consumer TU (MSYS2/MINGW64 guard _WINPTHREADS_H)\n");
+    ++leaks;
+#endif
 #endif  // !_LIBCPP_VERSION && !_GLIBCXX_HAS_GTHREADS
 
 #ifdef GNUTLS_GNUTLS_H