TASK-007 review cleanup: address cosmetic and minor behavioral findings

- Makefile.am: add comment explaining HEADER_HYGIENE_FORBIDDEN anchor
  semantics (item 8); add wildcard parse-time warning comment and broaden
  HYGIENE_STAMP to include top-level src/httpserver.hpp (items 10, 29);
  normalize variable alignment; add inline override comment to
  HEADER_HYGIENE_STRICT (items 22, 19/23); expand check-local comment to
  list all sub-checks and document CHECK_*_SHARED knob (items 14, 21);
  replace awk with sed for robust path extraction (item 24); add check-local
  to .PHONY (item 25); quote abs_top_builddir in shell word positions (item
  37); add staged-install content guard after test -d check (item 46)
- verify-build.yml: exclude header-hygiene from 'Print tests results' step
  (item 42); update stale comments about HEADER_HYGIENE_STRICT default
- TASK-007.md, TASK-020.md: fix gnutls acceptance-criteria pattern from
  gnutls\.h to gnutls/gnutls\.h (items 40, 26)
- header_hygiene_test.cpp: add _WINPTHREADS_H guard for MSYS2/MINGW64
  (item 48); document deliberate multi-assert design (item 18); document
  <cstdio> inclusion rationale vs consumer_umbrella_no_backend.cpp (item 5);
  update guard-macro table with MSYS2 variant

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: etr

.github/workflows/verify-build.yml

@@ -262,9 +262,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
@@ -827,8 +827,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
@@ -839,7 +839,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

@@ -222,10 +222,15 @@ check-install-layout:
 # route std::thread through pthread (e.g. MSVC's Microsoft STL).
 # ---------------------------------------------------------------------------
 
+# 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`
@@ -235,7 +240,10 @@ 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.
+# Also includes the top-level umbrella so a change there invalidates the stamp.
+$(HYGIENE_STAMP): $(wildcard $(top_srcdir)/src/httpserver/*.hpp) $(top_srcdir)/src/httpserver.hpp
 	@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; \
@@ -253,6 +261,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 \
@@ -267,7 +280,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>:"; \
@@ -284,24 +297,30 @@ check-hygiene:
 	rm -f check-hygiene.i check-hygiene.err; \
 	exit $$status
 
-# check-local runs check-install-layout and check-hygiene against a single
-# shared staged install to avoid paying two full `make install` costs on
-# every `make check`. Both sub-checks can still be invoked standalone (they
+# check-local runs check-headers (prerequisite), check-install-layout and
+# check-hygiene (via recursive $(MAKE) with shared-stage variables) against a
+# single shared staged install to avoid paying two full `make install` costs on
+# every `make check`.  Both 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).
@@ -386,7 +405,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
@@ -401,7 +420,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;
 
@@ -107,6 +118,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