test: triage 37 skipped-test sites — closure comments pinning rationale (Q-1)

Closes Q-1 (cat-s3-58ce7e9840be) — 37 t.Skip / testing.Short() sites
across 9 test files audited. Per-site verdict matrix:

  - cmd/agent/verify_test.go (1 site): defensive guard against unreachable
    httptest.NewTLSServer code path. Document-skip with closure comment.

  - deploy/test/qa_test.go (11 sites): file already gated by `//go:build qa`
    tag. The 11 t.Skip("Requires X — manual test") markers are runtime
    second-line guards for operators who run -tags qa against a stack
    missing the required external service. File-level header comment
    block added explaining the manual-test convention.

  - deploy/test/healthcheck_test.go (5 sites): 3 docker-availability +
    1 testing.Short + 1 hard-skip for not-yet-wired runtime probe
    (image-spec contract above already covers the audit-flagged
    regression). All correctly gated; file-level header comment block
    added explaining each.

  - deploy/test/integration_test.go (5 sites): in-flight-state guards
    (poll-with-skip after 90s polling for agent-online, inter-test
    Phase04→Phase07 ordering, scheduler-tick race for discovered certs,
    inter-test issuer fallthrough, defensive PEM-empty assertion).
    Each site now has a closure comment explaining why skip is the
    right choice rather than fail (upstream phase already surfaces the
    real failure; skipping prevents masking root cause behind cascading
    noise).

  - internal/repository/postgres/{testutil,seed,repo}_test.go (5 sites):
    testing.Short() gates for testcontainers-backed live PostgreSQL
    integration tests. All correctly gated; closure comments added
    naming the run command.

  - internal/connector/notifier/email/email_test.go (2 sites):
    anti-fixture assertions (test asserts SMTP dial fails; if a captive
    portal black-holes the call to success, skip rather than false-pass).
    Closure comments added explaining the fixture assumption.

  - internal/connector/target/iis/iis_test.go (2 sites): platform-gated
    skip for powershell.exe absence on non-Windows hosts. Mirrors the
    production iis_connector.go LookPath guard. Closure comments added.

Total: 17 closure comments anchor the 37 skip sites (some sites share a
single block-level comment). All skips remain in place; the change is
purely documentation. The audit recommendation was "audit each skip and
decide" — for these 37, the decision is uniformly **document-skip**:
the gating is correct, the t.Skip messages name the missing precondition,
and the closure comments now pin the rationale for future readers.

See coverage-gap-audit-2026-04-24-v5/unified-audit.md
cat-s3-58ce7e9840be for closure rationale.

internal/connector/notifier/email/email_test.go

@@ -413,9 +413,15 @@ func TestEmail_SendAlert_ValidationFailure(t *testing.T) {
 
 	// We expect an error because the SMTP server doesn't exist
 	// The exact error depends on network conditions, but we know it should fail
+	//
+	// Q-1 closure (cat-s3-58ce7e9840be): anti-fixture skip — the test
+	// asserts that sending to a non-existent SMTP server fails. If a
+	// captive portal, SOHO router, or test sandbox happens to resolve
+	// smtp.example.com:587 to a black hole that returns success, the
+	// assertion is invalid and we skip rather than false-pass. The
+	// IANA-reserved example.com domain shouldn't resolve to an active
+	// SMTP server in practice; this skip is the defensive fallback.
 	if err == nil {
-		// In some environments this might succeed if the host/port resolves oddly
-		// but in most cases it will fail
 		t.Skip("test requires no service on smtp.example.com:587")
 	}
 }
@@ -487,6 +493,12 @@ func TestEmail_ValidateConfig_ConnectionRefused(t *testing.T) {
 	conn := New(&Config{}, logger)
 
 	err := conn.ValidateConfig(context.Background(), rawConfig)
+	// Q-1 closure (cat-s3-58ce7e9840be): anti-fixture skip — the test
+	// asserts that ValidateConfig fails to reach an SMTP server on a
+	// random high port (54321) that nothing should be listening on.
+	// If the port happens to be occupied (rare in CI, possible on a
+	// dev machine), we skip rather than false-pass. The dial-error
+	// path below is the actual assertion target.
 	if err == nil {
 		t.Skip("test assumes no service on 127.0.0.1:54321")
 	}

internal/connector/target/iis/iis_test.go

@@ -81,7 +81,13 @@ func TestIISConnector_ValidateConfig_Success(t *testing.T) {
 	// We test the validation logic up to that point by checking the error message.
 	err := connector.ValidateConfig(context.Background(), rawConfig)
 	if err != nil {
-		// If it's just a "powershell not found" error, that's expected on Linux
+		// Q-1 closure (cat-s3-58ce7e9840be): platform-gated skip — IIS
+		// connector dispatches via powershell.exe; the binary only exists
+		// on Windows hosts. This branch lets the test pass on Linux/macOS
+		// CI runners where powershell.exe isn't available; on Windows
+		// runners the assertion below runs normally. The iis_connector.go
+		// production code has the same platform check; this skip mirrors
+		// it at test-fixture level.
 		if strings.Contains(err.Error(), "powershell.exe not found") {
 			t.Skip("Skipping: powershell.exe not available (non-Windows)")
 		}
@@ -212,6 +218,9 @@ func TestIISConnector_ValidateConfig_DefaultValues(t *testing.T) {
 
 	err := connector.ValidateConfig(context.Background(), rawConfig)
 	if err != nil {
+		// Q-1 closure (cat-s3-58ce7e9840be): same platform-gate as
+		// TestIIS_ValidateConfig_Empty above; mirrors the production
+		// LookPath("powershell.exe") guard in iis_connector.go.
 		if strings.Contains(err.Error(), "powershell.exe not found") {
 			t.Skip("Skipping: powershell.exe not available (non-Windows)")
 		}

internal/repository/postgres/repo_test.go

@@ -1937,6 +1937,9 @@ func seedPendingJobs(t *testing.T, ctx context.Context, db *sql.DB, certID strin
 // semantics: a single call transitions Pending rows to Running atomically, and
 // the rows returned to the caller reflect the post-update state.
 func TestJobRepository_ClaimPendingJobs_FlipsToRunning(t *testing.T) {
+	// Q-1 closure (cat-s3-58ce7e9840be): exercises the SKIP-LOCKED claim
+	// SQL against a live PostgreSQL via testcontainers-go. Run with:
+	//   go test -count=1 ./internal/repository/postgres/... (omit -short)
 	if testing.Short() {
 		t.Skip("integration test requires PostgreSQL")
 	}
@@ -1993,6 +1996,9 @@ func TestJobRepository_ClaimPendingJobs_FlipsToRunning(t *testing.T) {
 // an atomic progress counter before exiting, so transient SKIP-LOCKED zeros do
 // not cause premature termination.
 func TestJobRepository_ClaimPendingJobs_ConcurrentDisjoint(t *testing.T) {
+	// Q-1 closure (cat-s3-58ce7e9840be): concurrent claim semantics
+	// require true row-level locking — only PostgreSQL provides this.
+	// Run with: go test -count=1 ./internal/repository/postgres/... (omit -short)
 	if testing.Short() {
 		t.Skip("integration test requires PostgreSQL")
 	}
@@ -2100,6 +2106,10 @@ func TestJobRepository_ClaimPendingJobs_ConcurrentDisjoint(t *testing.T) {
 // Running; AwaitingCSR rows are returned but their state is preserved (the CSR
 // submission path drives their next transition).
 func TestJobRepository_ClaimPendingByAgentID_TransitionsDeployments(t *testing.T) {
+	// Q-1 closure (cat-s3-58ce7e9840be): Pending→Running deployment-job
+	// transition vs CSR-flow preservation requires the live PostgreSQL
+	// transactional semantics. Run with:
+	//   go test -count=1 ./internal/repository/postgres/... (omit -short)
 	if testing.Short() {
 		t.Skip("integration test requires PostgreSQL")
 	}

internal/repository/postgres/seed_test.go

@@ -84,6 +84,9 @@ func TestRunSeed_AppliesIdempotently(t *testing.T) {
 // We point at a directory that exists (empty temp dir) but contains no
 // seed.sql. RunSeed must return nil silently.
 func TestRunSeed_MissingFileIsNoOp(t *testing.T) {
+	// Q-1 closure (cat-s3-58ce7e9840be): RunSeed opens a *sql.DB connection
+	// against the live PostgreSQL testcontainer. Run with:
+	//   go test -count=1 ./internal/repository/postgres/... (omit -short)
 	if testing.Short() {
 		t.Skip("skipping integration test in short mode")
 	}

internal/repository/postgres/testutil_test.go

@@ -30,6 +30,11 @@ type testDB struct {
 func setupTestDB(t *testing.T) *testDB {
 	t.Helper()
 
+	// Q-1 closure (cat-s3-58ce7e9840be): live PostgreSQL needed via
+	// testcontainers-go (postgres:16-alpine). Run with:
+	//   go test -count=1 ./internal/repository/postgres/... (omit -short)
+	// The short-mode gate keeps it off the default `go test ./... -short`
+	// fast loop where docker-in-docker may not be available.
 	if testing.Short() {
 		t.Skip("skipping integration test in short mode")
 	}