chore(ga): repo + version hygiene for public GA cut (#705)

remyluslosius · web-flow · commit 965e146d43a7 · 2026-06-27T21:31:37.000-04:00
Addresses the public-repo hygiene findings from the GA readiness review.
None are functional/security blockers; this is the public-cut polish pass.

F1 — version surfaces now agree (all -&gt; 0.2.0-rc.17): README, the workflows
  README, the root VERSION build-fallback (was 0.1.0-alpha.1), api/openapi.yaml
  (title "OpenWatch (Stage 0)" -&gt; "OpenWatch", version, and the stale "three
  endpoints" description; it actually serves 123 paths), and the API_GUIDE /
  MONITORING_SETUP / PRODUCTION_DEPLOYMENT / QUICKSTART guides (were rc.14).
F2 — untrack the runtime SQLite sidecars .kensa/remediation.db-{shm,wal}
  (already gitignored; they were the recurring dirty-tree noise).
F3 — prettier --write the 8 unformatted frontend files (formatting only;
  tsc + eslint still clean).
F5 — `make migrate` now runs `openwatch migrate` (was "not yet implemented").
F7 — RELEASING.md + workflows README now state the real signing behavior:
  GPG is REQUIRED on a tag-push (release.yml fails closed); only a
  workflow_dispatch trial can publish unsigned.

Judgment calls:
F4 — `make lint` now hard-fails on a golangci-lint version mismatch (was a
  warning then ran the wrong binary), so local lint matches the pinned CI v1.
F6 — removed the zero-secret-value cruft ignore patterns that hid source/docs
  (*test*.ts/.tsx/.mjs are TS source; *_MIGRATION*.md hid migration docs); kept
  the *secret*/*password*/*credential* guards (they have negations + real value).

Also: add docs/guides/README.md (a version-agnostic operator-guide index for
hanalyx.com/docs).
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
@@ -74,7 +74,7 @@ The workflow then:
 Distribution is via GitHub Releases. Operators install with
 `sudo dnf install ./openwatch-*.rpm` or `sudo apt install ./openwatch_*.deb`. A tag
 with a pre-release suffix (for example `-rc.5`) is marked as a pre-release; a bare
-`vX.Y.Z` is GA. The current version (`0.2.0-rc.5`) is a pre-release. See
+`vX.Y.Z` is GA. The current version (`0.2.0-rc.17`) is a pre-release. See
 `specs/system/supply-chain.spec.yaml`, `specs/release/package-build.spec.yaml`, and
 `docs/runbooks/RELEASING.md`.
 
@@ -117,8 +117,10 @@ remain a manual RC step (see `docs/runbooks/RELEASING.md`).
 | `GPG_PRIVATE_KEY`, `GPG_PASSPHRASE` | `release.yml` | Sign RPMs and the checksum manifest |
 | `COSIGN_PRIVATE_KEY`, `COSIGN_PASSWORD` | `release.yml` | Cosign signature over the checksum manifest |
 
-Signing steps in `release.yml` are gated on key presence; without them, packages and
-checksums publish unsigned.
+On a tag-push release, GPG signing is required: `release.yml` fails closed and refuses
+to publish unsigned if `GPG_PRIVATE_KEY` is absent. The cosign layer is optional and
+skips if its key is absent. An unsigned build is only possible via a `workflow_dispatch`
+trial run (never a tag push).
 
 ## Reproducing CI locally
 
diff --git a/.gitignore b/.gitignore
@@ -341,9 +341,9 @@ frontend_test.log
 # Exception: committed test harness scripts under packaging/tests/ (e.g. the
 # container upgrade test) are real tracked files, not transient scratch.
 !packaging/tests/*test*.sh
-*test*.mjs
-*test*.ts
-*test*.tsx
+# NOTE: do NOT blanket-ignore *test*.ts / *test*.tsx / *test*.mjs — in the Go
+# rebuild those are first-class TypeScript source (frontend *.test.ts(x) suites),
+# not build artifacts. Ignoring them silently hides new tests from git.
 
 # Go-rebuild layout: the active frontend (promoted from app/frontend) keeps its
 # tests under frontend/tests/ and co-located *.test.ts(x). Re-include them — the
@@ -702,12 +702,15 @@ scripts/cleanup-documentation.sh
 *-migration-output
 
 # Working Documents and Analysis Reports (DO NOT COMMIT)
+# These guard against committing AI/working scratch notes. They match an
+# UPPER_SUFFIX.md convention legit docs mostly avoid. NOTE: *_MIGRATION*.md was
+# removed — it wrongly hid legitimate DB-migration documentation; name scratch
+# migration notes differently if needed.
 *_ASSESSMENT.md
 *_ANALYSIS.md
 *_COMPLETE.md
 *_FIX*.md
 *_IMPLEMENTATION*.md
-*_MIGRATION*.md
 *_PHASE*.md
 *_REPORT.md
 *_STATUS.md
diff --git a/.kensa/remediation.db-shm b/.kensa/remediation.db-shm
diff --git a/.kensa/remediation.db-wal b/.kensa/remediation.db-wal
diff --git a/Makefile b/Makefile
@@ -140,14 +140,17 @@ 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 "ERROR: golangci-lint $$have installed, but this repo pins $(GOLANGCI_VERSION)."; \
+	    echo "       Local lint must match CI (the config is v1 format; a v2 binary cannot"; \
+	    echo "       load it). Install the pinned version, then re-run:"; \
 	    echo "         go install github.com/golangci/golangci-lint/cmd/golangci-lint@v$(GOLANGCI_VERSION)"; \
+	    exit 1; \
 	  fi; \
 	  golangci-lint run; \
 	else \
-	  echo "golangci-lint not installed; skipping (CI pins v$(GOLANGCI_VERSION)):"; \
+	  echo "ERROR: golangci-lint not installed (this repo pins v$(GOLANGCI_VERSION)):"; \
 	  echo "  go install github.com/golangci/golangci-lint/cmd/golangci-lint@v$(GOLANGCI_VERSION)"; \
+	  exit 1; \
 	fi
 
 # vuln: known-CVE scan against deps + stdlib (call-graph aware).
@@ -267,7 +270,7 @@ spa:
 
 .PHONY: migrate
 migrate:
-	@echo "migrate: not yet implemented (lands in Day 3: goose)"
+	go run ./cmd/openwatch migrate
 
 # -----------------------------------------------------------------------------
 # Packaging (Day 11: RPM + DEB)
@@ -335,7 +338,7 @@ help:
 	@echo ""
 	@echo "Codegen + DB:"
 	@echo "  generate    Run codegen (oapi-codegen, sqlc, registries)              [Day 5]"
-	@echo "  migrate     Run goose database migrations                             [Day 3]"
+	@echo "  migrate     Run goose database migrations (openwatch migrate)"
 	@echo ""
 	@echo "Packaging:"
 	@echo "  rpm         Build RPM package                                         [Day 11]"
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ OpenWatch is the compliance operating system for teams managing Linux infrastruc
 > Python/FastAPI implementation was archived out of the repo on 2026-06-05). The
 > Go tree lives at the **repo root**: Go 1.26 backend (`cmd/`, `internal/`),
 > React 19 + TanStack frontend (`frontend/`), PostgreSQL-only. The current
-> version is `0.2.0-rc.13`, a pre-release, not a GA build.
+> version is `0.2.0-rc.17`, a pre-release, not a GA build.
 
 ![OpenWatch Host Management: a fleet of RHEL and Ubuntu hosts with per-host compliance scores against 538 Kensa rules](docs/images/host-management.png)
 
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.1.0-alpha.1
+0.2.0-rc.17
diff --git a/api/openapi.yaml b/api/openapi.yaml
@@ -17,11 +17,13 @@
 openapi: 3.0.3
 
 info:
-  title: OpenWatch (Stage 0)
-  version: 0.1.0-alpha.1
+  title: OpenWatch
+  version: 0.2.0-rc.17
   description: |
-    Stage 0 walking-skeleton surface — three endpoints that exercise the
-    foundation stack (correlation, idempotency, audit, error envelope).
+    The OpenWatch REST API: authentication, hosts, scans, compliance posture,
+    remediation, reports, notifications, and administration. All responses carry
+    a correlation ID and a structured error envelope; mutating calls are
+    idempotency-keyed and audited.
 
 servers:
   - url: https://localhost:8443
diff --git a/docs/guides/API_GUIDE.md b/docs/guides/API_GUIDE.md
@@ -12,7 +12,7 @@ React UI over HTTPS on port `8443`. All API paths live under `/api/v1`. The
 running binary serves its own OpenAPI document as the contract source of truth,
 and `GET /api/v1/version` reports the build it came from.
 
-This guide reflects OpenWatch `v0.2.0-rc.14`, a pre-release. The compliance
+This guide reflects OpenWatch `v0.2.0-rc.17`, a pre-release. The compliance
 surface (scan execution + results, remediation, exceptions, posture/drift, audit
 export, the rule browser) IS exposed over `/api/v1`. See [the compliance API surface
 (now live)](#compliance-api-surface-now-live). The genuinely-absent pieces (a
@@ -279,7 +279,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.14"}
+{"status": "healthy", "db_connected": true, "version": "0.2.0-rc.17"}
 ```
 
 `status` is `healthy` or `degraded`; the endpoint returns `503` when the service
@@ -356,7 +356,7 @@ configuration steps, see
 
 ## Compliance API surface (now live)
 
-As of `v0.2.0-rc.14`, the compliance workflow IS exposed over `api/v1` (it is no
+As of `v0.2.0-rc.17`, the compliance workflow IS exposed over `api/v1` (it is no
 longer worker-internal only):
 
 - **Scans**: trigger with `POST /api/v1/hosts/{id}/scans`; browse durable
diff --git a/docs/guides/MONITORING_SETUP.md b/docs/guides/MONITORING_SETUP.md
@@ -52,7 +52,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.14"}
+{"status": "healthy", "db_connected": true, "version": "0.2.0-rc.17"}
 ```
 
 When the database ping fails, the endpoint returns `503 Service Unavailable`
@@ -74,7 +74,7 @@ curl -k https://localhost:8443/api/v1/version
 
 ```json
 {
-  "openwatch": "0.2.0-rc.14",
+  "openwatch": "0.2.0-rc.17",
   "kensa": "<embedded engine version>",
   "go": "<go toolchain>",
   "commit": "<abbrev commit>",
diff --git a/docs/guides/PRODUCTION_DEPLOYMENT.md b/docs/guides/PRODUCTION_DEPLOYMENT.md
@@ -14,7 +14,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
-> (`v0.2.0-rc.14`), not a GA build. Treat it
+> (`v0.2.0-rc.17`), not a GA build. Treat it
 > accordingly until a GA tag ships.
 
 ---
diff --git a/docs/guides/QUICKSTART.md b/docs/guides/QUICKSTART.md
@@ -51,7 +51,7 @@ A healthy response looks like this:
 {
   "status": "healthy",
   "db_connected": true,
-  "version": "0.2.0-rc.14"
+  "version": "0.2.0-rc.17"
 }
 ```
 
diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -0,0 +1,42 @@
+# OpenWatch operator guides
+
+Operator and administrator documentation for OpenWatch. For the version you are
+running, check `GET /api/v1/health` or `openwatch --version`; the current line is
+a pre-release on the `0.2.0` series until a bare `v0.2.0` tag is published.
+
+## Getting started
+
+- [Quickstart](QUICKSTART.md) — install and reach a working server fast.
+- [Install guide](INSTALLATION.md) — native RPM and DEB packages, step by step.
+- [Linux distribution support](LINUX_DISTRIBUTION_SUPPORT.md) — tested targets.
+
+## Deploy and operate
+
+- [Production deployment](PRODUCTION_DEPLOYMENT.md) — hardened production setup.
+- [Configuration and environment reference](ENVIRONMENT_REFERENCE.md) — every setting.
+- [Monitoring and operations](MONITORING_SETUP.md) — health, metrics, day-2 ops.
+- [Backup and recovery](BACKUP_RECOVERY.md) — back up and restore data.
+- [Upgrade procedure](UPGRADE_PROCEDURE.md) — move between releases safely.
+- [Database migrations](DATABASE_MIGRATIONS.md) — how schema changes are applied.
+- [Scaling guide](SCALING_GUIDE.md) — grow with fleet size.
+
+## Security
+
+- [Security hardening](SECURITY_HARDENING.md) — lock down a deployment.
+- [Secret rotation](SECRET_ROTATION.md) — rotate keys and credentials.
+- [User roles and permissions](USER_ROLES.md) — the RBAC model.
+
+## Compliance and scanning
+
+- [Scanning and compliance](SCANNING_AND_COMPLIANCE.md) — run scans, read results.
+- [Compliance control mapping](COMPLIANCE_CONTROLS.md) — frameworks and controls.
+- [Host management and remediation](HOSTS_AND_REMEDIATION.md) — manage hosts, apply fixes.
+
+## API
+
+- [API guide](API_GUIDE.md) — the REST API surface and usage.
+
+## Runbooks
+
+Incident response procedures live in [runbooks/](runbooks/): service down, database
+issues, disk full, high CPU, and security incident response.
diff --git a/docs/runbooks/RELEASING.md b/docs/runbooks/RELEASING.md
@@ -109,9 +109,12 @@ Then bump `packaging/version.env` to the next `-dev`/`-rc` and announce.
 
 ## Signing model
 
-When the signing keys are configured, `release.yml` signs at these layers (and
-skips each layer gracefully if its key is absent — releases still publish,
-unsigned):
+On a **tag-push release, GPG signing is required**: `release.yml` fails closed and
+refuses to publish if `GPG_PRIVATE_KEY` is absent, so operators never receive
+unverifiable packages. The cosign layer is optional and skips gracefully if its key
+is absent. An unsigned build is only possible via a manual `workflow_dispatch` trial
+run (never a tag push). When the keys are configured, `release.yml` signs at these
+layers:
 
 | Layer | How | Operator verifies |
 |---|---|---|
diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts
@@ -58,7 +58,11 @@ function readCookie(name: string): string | null {
 // opposed to an authz (permission) denial, which is a 403 and must NOT log
 // the user out. Mirrors auth-error-redirect.ts so the interceptor and the
 // QueryCache onError handler agree on what counts as a session failure.
-const AUTH_FAILURE_CODES = new Set(['auth.session_invalid', 'auth.session_expired', 'auth.required']);
+const AUTH_FAILURE_CODES = new Set([
+  'auth.session_invalid',
+  'auth.session_expired',
+  'auth.required',
+]);
 
 // isAuthFailureResponse reports whether a response is a 401 carrying an
 // authentication-failure code. Reads a CLONE so the caller's body stays
diff --git a/frontend/src/components/shell/TopBar.tsx b/frontend/src/components/shell/TopBar.tsx
@@ -399,7 +399,9 @@ function NotificationBell() {
                 />
                 <span style={{ fontSize: 12, color: 'var(--ow-fg-0)' }}>{n.title}</span>
                 {n.body ? (
-                  <div style={{ fontSize: 11, color: 'var(--ow-fg-3)', marginTop: 2 }}>{n.body}</div>
+                  <div style={{ fontSize: 11, color: 'var(--ow-fg-3)', marginTop: 2 }}>
+                    {n.body}
+                  </div>
                 ) : null}
               </button>
             ))
diff --git a/frontend/src/pages/HostDetailPage.tsx b/frontend/src/pages/HostDetailPage.tsx
@@ -1332,8 +1332,8 @@ function RemediationExplainer() {
       <div style={{ color: 'var(--ow-fg-2)', fontSize: 12, lineHeight: 1.5 }}>
         Each approved fix captures the current host state, applies the change, validates the result,
         then commits. A failed validation rolls back to the captured state, so a host is never left
-        half-fixed. Applying a single approved fix on the host (and rolling it back) is part of core.
-        Bulk and automated remediation are OpenWatch+ features.
+        half-fixed. Applying a single approved fix on the host (and rolling it back) is part of
+        core. Bulk and automated remediation are OpenWatch+ features.
       </div>
     </div>
   );
@@ -1420,9 +1420,7 @@ function RemediationRowAction({
       });
       if (error || !response.ok) {
         if (response.status === 409) {
-          throw new Error(
-            apiErrorMessage(error, 'This request is not in an approvable state.'),
-          );
+          throw new Error(apiErrorMessage(error, 'This request is not in an approvable state.'));
         }
         throw new Error(apiErrorMessage(error, `Action failed (${response.status})`));
       }
@@ -1525,7 +1523,13 @@ function RemediationRowAction({
     return (
       <span
         role="status"
-        style={{ display: 'inline-flex', alignItems: 'center', gap: 6, fontSize: 11, color: 'var(--ow-warn)' }}
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 6,
+          fontSize: 11,
+          color: 'var(--ow-warn)',
+        }}
       >
         <span
           aria-hidden
@@ -1545,8 +1549,20 @@ function RemediationRowAction({
   if (request.status === 'executed') {
     return (
       <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
-        <span style={{ display: 'inline-flex', alignItems: 'center', gap: 6, fontSize: 11, fontWeight: 600, color: 'var(--ow-ok)' }}>
-          <span aria-hidden style={{ width: 6, height: 6, borderRadius: '50%', background: 'var(--ow-ok)' }} />
+        <span
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 6,
+            fontSize: 11,
+            fontWeight: 600,
+            color: 'var(--ow-ok)',
+          }}
+        >
+          <span
+            aria-hidden
+            style={{ width: 6, height: 6, borderRadius: '50%', background: 'var(--ow-ok)' }}
+          />
           Fixed
         </span>
         {canRollback && (
@@ -1581,7 +1597,15 @@ function RemediationRowAction({
 
   if (request.status === 'failed') {
     return (
-      <span style={{ display: 'inline-flex', alignItems: 'center', gap: 6, fontSize: 11, color: 'var(--ow-crit)' }}>
+      <span
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 6,
+          fontSize: 11,
+          color: 'var(--ow-crit)',
+        }}
+      >
         Failed
         {request.review_note ? (
           <span style={{ color: 'var(--ow-fg-3)' }}>({request.review_note})</span>
@@ -1619,9 +1643,9 @@ function RemediationUpsell() {
           Bulk and automated remediation (OpenWatch+)
         </div>
         <div style={{ color: 'var(--ow-fg-2)', fontSize: 12, lineHeight: 1.5 }}>
-          Applying a single approved fix (and rolling it back) is part of core. Applying many rules at
-          once across the fleet, and scheduling auto-remediation so approved fixes apply without a
-          per-rule click, are OpenWatch+ features.
+          Applying a single approved fix (and rolling it back) is part of core. Applying many rules
+          at once across the fleet, and scheduling auto-remediation so approved fixes apply without
+          a per-rule click, are OpenWatch+ features.
         </div>
       </div>
       <button
@@ -2855,7 +2879,6 @@ function activityIconFor(item: ActivityItem): { Icon: LucideIcon; color: string
   }
 }
 
-
 // ─────────────────────────────────────────────────────────────────────────
 // Reusable bits (cards, kv rows, empty states, etc.)
 // ─────────────────────────────────────────────────────────────────────────
diff --git a/frontend/src/pages/HostsListPage.tsx b/frontend/src/pages/HostsListPage.tsx
@@ -163,7 +163,8 @@ export function HostsListPage() {
   const setHostsViewDefault = usePreferencesStore((s) => s.setHostsViewDefault);
   const view: 'table' | 'cards' =
     search.view === 'table' || search.view === 'cards' ? search.view : hostsViewDefault;
-  const group: GroupKey = search.group === 'status' || search.group === 'os' ? search.group : 'none';
+  const group: GroupKey =
+    search.group === 'status' || search.group === 'os' ? search.group : 'none';
   const query = (search.q ?? '').trim().toLowerCase();
   const filters: HostFilters = useMemo(
     () => parseHostFilters({ status: search.status, os: search.os, tier: search.tier }),
@@ -488,11 +489,7 @@ export function HostsListPage() {
             {groups.map((g) => (
               <section key={g.key}>
                 <GroupHeader label={g.label} count={g.hosts.length} />
-                {view === 'cards' ? (
-                  <HostsCards hosts={g.hosts} />
-                ) : (
-                  <HostsTable hosts={g.hosts} />
-                )}
+                {view === 'cards' ? <HostsCards hosts={g.hosts} /> : <HostsTable hosts={g.hosts} />}
               </section>
             ))}
           </div>
diff --git a/frontend/src/pages/dashboard/widgets.tsx b/frontend/src/pages/dashboard/widgets.tsx
@@ -19,7 +19,6 @@ function scoreTone(pct: number): 'crit' | 'warn' | 'ok' {
   return 'ok';
 }
 
-
 // ── KPI: Hosts online ──────────────────────────────────────────────
 export function KpiHostsOnline() {
   const q = useQuery({
diff --git a/frontend/src/pages/scans/RulesTab.tsx b/frontend/src/pages/scans/RulesTab.tsx
diff --git a/frontend/src/pages/scans/ScanDetailPage.tsx b/frontend/src/pages/scans/ScanDetailPage.tsx
diff --git a/frontend/src/pages/scans/ScansPage.tsx b/frontend/src/pages/scans/ScansPage.tsx
