chore: GA-readiness fixes (F1-F6) + Specter 100% coverage gate (#602)

GA-readiness review fixes plus a 100% Specter coverage gate (structural + outcome at all tiers).

- F6 hygiene: remove stray root binary, gitignore /openwatch, strip prototype login creds
- F2 lint: warn when local golangci-lint != CI-pinned 1.64.8
- F1 isolation: self-contained SPA test fixture; gate native package-build tests behind OPENWATCH_PACKAGING_BUILD
- F5 CI: hard-fail the build on frontend vitest failures
- F4 release: fail closed on unsigned tag-push releases
- F3 docs: reconcile guide versions to 0.2.0-rc.10 + CHANGELOG
- Specter: enforce 100% structural AC coverage and raise all outcome tiers to 100, wiring the formerly env-gated tests (Kensa corpus AC-08; runtime-boot AC-14 via pgx + CSRF fix) to run in CI

Author: remyluslosius

.github/workflows/go-ci.yml

@@ -196,6 +196,32 @@ jobs:
             exit 1
           fi
 
+      # 100% structural coverage gate. Every acceptance criterion in every spec
+      # MUST have at least one test annotation — no AC may silently lose its
+      # test. This runs in annotation strictness (structural, no ingest) so it
+      # is independent of which tests run in this lane, and it fails fast and
+      # with a clear message before the heavier ingest-based outcome gate. The
+      # outcome gate (`specter sync` at the manifest's threshold strictness,
+      # tiers all 100, below) separately requires every AC's test to PASS; the
+      # ingest job provisions OPENWATCH_KENSA_RULES_DIR + OPENWATCH_PACKAGING_BUILD
+      # so the formerly env-gated tests run there instead of skipping.
+      #
+      # NOTE: `specter sync --strictness annotation` would only enforce the
+      # per-tier thresholds, so we assert 100% directly: any per-spec row
+      # (a "… Tn …" line) not at 100% fails the build.
+      - name: specter structural coverage must be 100%
+        if: steps.paths.outputs.go == 'true'
+        run: |
+          report=$(specter coverage --strictness annotation 2>&1)
+          echo "$report"
+          below=$(echo "$report" | grep -E '\sT[0-9]+\s' | grep -vE '\s100%' || true)
+          if [ -n "$below" ]; then
+            echo "::error::Specter structural coverage is below 100% — every acceptance criterion must carry a // @ac (Go) or // @ac (frontend) annotation. Specs below 100%:"
+            echo "$below"
+            exit 1
+          fi
+          echo "All specs at 100% structural coverage."
+
       # Single full-suite run that BOTH detects data races and emits the
       # JSON specter ingests — replacing the previous two end-to-end passes
       # (`make test-race` + a separate non-race `go test -json`), which ran
@@ -206,8 +232,18 @@ jobs:
       # to 600s because race instrumentation slows the hot DB packages.
       - name: go test (race + json) for specter ingest
         if: steps.paths.outputs.go == 'true'
+        # OPENWATCH_PACKAGING_BUILD=1 opts the native package-build + runtime-boot
+        # tests into this run so their AC coverage is enforced in CI; a plain
+        # local `go test ./...` skips them (they take minutes and write into
+        # dist/). See packaging/tests/package_test.go:requirePackagingBuild.
+        env:
+          OPENWATCH_PACKAGING_BUILD: "1"
         run: |
           set +e
+          # Point the Kensa variable-catalog tests at the real rule corpus that
+          # ships inside the kensa module, so api-system-scan-config/AC-08 runs
+          # here instead of skipping (100% outcome coverage requires it).
+          export OPENWATCH_KENSA_RULES_DIR="$(go list -m -f '{{.Dir}}' github.com/Hanalyx/kensa)/rules"
           go test -race -json -timeout 600s -p 4 ./... > /tmp/go-test.json
           EXIT=$?
           if [ "$EXIT" -ne 0 ]; then
@@ -242,12 +278,14 @@ jobs:
           set +e
           npx vitest run --reporter=junit --outputFile=/tmp/vitest-junit.xml --reporter=default
           EXIT=$?
-          # Don't block the pipeline on Vitest failure — surface it but
-          # let specter sync report which ACs are uncovered. The Go test
-          # step above already fails the build on test failure; this
-          # mirror keeps the gate's failure source observable.
+          # Record the exit code but DON'T fail here: specter ingest (next
+          # step) still needs to read the JUnit file, and specter sync should
+          # report which ACs the failures left uncovered before we abort.
+          # The "Enforce frontend tests passed" step below turns a non-zero
+          # result into a hard build failure once specter has run.
+          echo "$EXIT" > /tmp/vitest-exit
           if [ "$EXIT" -ne 0 ]; then
-            echo "::warning::Vitest reported test failures — see specter coverage for affected ACs"
+            echo "::warning::Vitest reported test failures — specter coverage below shows affected ACs; the build fails at the enforcement step."
           fi
 
       - name: specter ingest
@@ -264,6 +302,22 @@ jobs:
         # are skipped at parse time.
         run: specter sync --tests '**/*'
 
+      # Hard frontend-test gate. Vitest failures are deferred above so
+      # specter can ingest the JUnit results and report coverage first; this
+      # step makes a real frontend test failure fail the build. A frontend
+      # regression that does not happen to map to a spec AC would otherwise
+      # slip through (specter only gates annotated ACs), so this is the
+      # backstop that keeps `npm test` authoritative in CI.
+      - name: Enforce frontend tests passed
+        if: steps.paths.outputs.go == 'true'
+        run: |
+          EXIT=$(cat /tmp/vitest-exit 2>/dev/null || echo 1)
+          if [ "$EXIT" -ne 0 ]; then
+            echo "::error::Frontend vitest suite failed (exit $EXIT). See the 'frontend vitest' step above."
+            exit "$EXIT"
+          fi
+          echo "frontend vitest suite passed"
+
       - name: upload specter artifacts
         if: always() && steps.paths.outputs.go == 'true'
         uses: actions/upload-artifact@v4

.github/workflows/release.yml

@@ -82,9 +82,16 @@ jobs:
         run: |
           if [ -n "$GPG_PRIVATE_KEY" ]; then
             echo "gpg=true" >> "$GITHUB_OUTPUT"
+          elif [ "$GITHUB_EVENT_NAME" = "push" ]; then
+            # A v* tag push is an intentional release cut — publishing it
+            # unsigned would ship packages operators cannot verify. Fail
+            # closed. Manual workflow_dispatch runs (dry-runs / trials) stay
+            # permissive below so an unsigned trial build is still possible.
+            echo "::error::No GPG_PRIVATE_KEY secret configured, but this is a tag-push release ($GITHUB_REF_NAME). Refusing to publish unsigned packages. Configure the GPG_PRIVATE_KEY secret, or cut an unsigned trial via workflow_dispatch."
+            exit 1
           else
             echo "gpg=false" >> "$GITHUB_OUTPUT"
-            echo "::notice::No GPG_PRIVATE_KEY secret — packages and checksums will be published unsigned."
+            echo "::warning::No GPG_PRIVATE_KEY secret — this workflow_dispatch build will be published UNSIGNED. Tag pushes fail closed instead."
           fi
           if [ -n "$COSIGN_PRIVATE_KEY" ]; then
             echo "cosign=true" >> "$GITHUB_OUTPUT"

.gitignore

@@ -962,6 +962,11 @@ Thumbs.db
 coverage.html
 coverage.txt
 
+# Stray root-level build artifact. `make build` writes to dist/ (ignored
+# above); an ad-hoc `go build -o openwatch` at the repo root must never be
+# committed (a 34MB ELF slipped in this way once).
+/openwatch
+
 # Transient specter run output. CI regenerates these from a real
 # go test -json + vitest JUnit run (specter ingest), so a committed copy is
 # never consumed by the gate — it only goes stale and produces misleading

CHANGELOG.md

@@ -10,6 +10,29 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+
+- CI release safety: the release workflow now fails closed on a `v*` tag push
+  when no GPG signing key is configured, rather than publishing unsigned
+  packages. Manual `workflow_dispatch` trial builds stay permissive (warn +
+  publish unsigned).
+- CI frontend gate: a failing frontend Vitest suite now hard-fails the build.
+  Results are still ingested by specter first (so coverage is reported), then a
+  dedicated enforcement step aborts on a real test failure.
+- `make lint` now warns when the locally installed `golangci-lint` does not
+  match the version pinned in CI, so local runs reproduce CI.
+
+### Fixed
+
+- Documentation version drift: operator guides referenced `0.2.0-rc.5` while
+  `packaging/version.env` was `0.2.0-rc.10`; all guides now match.
+- SPA static-delivery tests are self-contained (in-memory fixture) instead of
+  depending on a magic staged asset filename, so `go test ./internal/server/`
+  passes against a real `vite build`, the Makefile stub, or no staged tree.
+- Repository hygiene: a stray 34 MB root build artifact was removed and the
+  root-level `openwatch` binary path is now gitignored; placeholder credentials
+  were stripped from the prototype login page.
+
 ---
 
 ## [0.2.0-rc.10] Eyrie — 2026-06-17

Makefile

@@ -20,6 +20,12 @@ DIST_DIR  := dist
 CMD_DIR   := ./cmd/openwatch
 SPA_DIR   := internal/server/spa
 
+# golangci-lint version. MUST match the version pinned in
+# .github/workflows/go-ci.yml (`go install ...golangci-lint@vX.Y.Z`) so a
+# local `make lint` reproduces CI exactly — a newer local binary surfaces
+# lints CI won't enforce yet (and vice-versa). Bump both together.
+GOLANGCI_VERSION := 1.64.8
+
 # Version metadata injected at build time. The Go rebuild has its own
 # version track (packaging/version.env) so its milestones decouple from
 # the legacy Python project at ../VERSION. Fallback order: local
@@ -132,9 +138,16 @@ vet: internal/server/openapi_embed.yaml $(SPA_DIR)/index.html
 .PHONY: lint
 lint: internal/server/openapi_embed.yaml $(SPA_DIR)/index.html
 	@if command -v golangci-lint >/dev/null 2>&1; then \
+	  have=$$(golangci-lint version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1); \
+	  if [ "$$have" != "$(GOLANGCI_VERSION)" ]; then \
+	    echo "WARNING: golangci-lint $$have installed, but CI pins $(GOLANGCI_VERSION)."; \
+	    echo "         Results may differ from CI. Install the pinned version:"; \
+	    echo "         go install github.com/golangci/golangci-lint/cmd/golangci-lint@v$(GOLANGCI_VERSION)"; \
+	  fi; \
 	  golangci-lint run; \
 	else \
-	  echo "golangci-lint not installed; skipping (install: https://golangci-lint.run/usage/install/)"; \
+	  echo "golangci-lint not installed; skipping (CI pins v$(GOLANGCI_VERSION)):"; \
+	  echo "  go install github.com/golangci/golangci-lint/cmd/golangci-lint@v$(GOLANGCI_VERSION)"; \
 	fi
 
 # vuln: known-CVE scan against deps + stdlib (call-graph aware).

docs/guides/API_GUIDE.md

@@ -11,7 +11,7 @@ contract source of truth is `api/openapi.yaml` in the repository; the running
 binary serves the same document, and `GET /api/v1/version` reports the build it
 came from.
 
-This guide reflects OpenWatch `0.2.0-rc.5`, a pre-release. The API surface is
+This guide reflects OpenWatch `0.2.0-rc.10`, a pre-release. The API surface is
 still growing — endpoints that the legacy Python API exposed (scan execution,
 remediation, exceptions, posture history, audit exports, the rule-reference
 browser) are not yet part of `api/v1`. See [What is not yet in the
@@ -276,7 +276,7 @@ curl -s --cacert /etc/openwatch/tls/ca.crt https://localhost:8443/api/v1/health
 ```
 
 ```json
-{"status": "healthy", "db_connected": true, "version": "0.2.0-rc.5"}
+{"status": "healthy", "db_connected": true, "version": "0.2.0-rc.10"}
 ```
 
 `status` is `healthy` or `degraded`; the endpoint returns `503` when the service
@@ -354,7 +354,7 @@ configuration steps, see
 ## What is not yet in the API
 
 The compliance scanning workflow runs through Kensa and the background worker,
-not yet through public REST endpoints. As of `0.2.0-rc.5`, `api/v1` does not
+not yet through public REST endpoints. As of `0.2.0-rc.10`, `api/v1` does not
 include:
 
 - Scan execution or scan-result endpoints (`/api/v1/scans/…`).

docs/guides/MONITORING_SETUP.md

@@ -54,7 +54,7 @@ curl -k https://localhost:8443/api/v1/health
 A healthy response returns `200 OK`:
 
 ```json
-{"status": "healthy", "db_connected": true, "version": "0.2.0-rc.5"}
+{"status": "healthy", "db_connected": true, "version": "0.2.0-rc.10"}
 ```
 
 When the database ping fails, the endpoint returns `503 Service Unavailable`
@@ -76,7 +76,7 @@ curl -k https://localhost:8443/api/v1/version
 
 ```json
 {
-  "openwatch": "0.2.0-rc.5",
+  "openwatch": "0.2.0-rc.10",
   "kensa": "<embedded engine version>",
   "go": "<go toolchain>",
   "commit": "<abbrev commit>",

docs/guides/PRODUCTION_DEPLOYMENT.md

@@ -12,7 +12,7 @@ touches lightly: process layout, TLS, the background worker, backups, upgrades,
 and incident runbooks.
 
 > Verify the version you deploy. The current line is a pre-release
-> (`0.2.0-rc.5` per `packaging/version.env`), not a GA build. Treat it
+> (`0.2.0-rc.10` per `packaging/version.env`), not a GA build. Treat it
 > accordingly until a GA tag ships.
 
 ---

docs/guides/QUICKSTART.md

@@ -49,7 +49,7 @@ A healthy response looks like this:
 {
   "status": "healthy",
   "db_connected": true,
-  "version": "0.2.0-rc.5"
+  "version": "0.2.0-rc.10"
 }
 ```
 

docs/guides/UPGRADE_PROCEDURE.md

@@ -13,7 +13,7 @@ database backup and restore commands referenced below, see
 [`BACKUP_RECOVERY.md`](BACKUP_RECOVERY.md). For migration mechanics, see
 [`DATABASE_MIGRATIONS.md`](DATABASE_MIGRATIONS.md).
 
-> Version note: the current release line is a pre-release (`0.2.0-rc.5`). Treat
+> Version note: the current release line is a pre-release (`0.2.0-rc.10`). Treat
 > upgrades between pre-release builds as potentially breaking and always back up
 > first.