golid / rules

---
description: Deep codebase audit checklist — use when asked to audit, review for release, or grade the codebase
alwaysApply: false
---

# Codebase Audit Checklist

> **Thesis:** Score the codebase across 7 categories with exact file citations. Check ADRs before flagging documented design decisions.

Run this checklist for release readiness audits. Cite exact file paths and line numbers for every finding. Check docs/adr/ for ADRs before flagging documented design decisions.

Core patterns (`apperror`, parameterized SQL, `batch()`, Switch/Match, `createResource`, alive guard) — see `codebase-standards`. Frontend fetch — `solidjs-data-fetching`. Route UI — `solidjs-pages`.

## Backend

- [ ] All SQL uses $N parameterized placeholders (no fmt.Sprintf with values or identifiers)
- [ ] No `_ = fn()` discarded errors in production code
- [ ] No `echo.NewHTTPError` in production code (use apperror)
- [ ] Token refresh is transactional and TOCTOU-safe (atomic UPDATE...RETURNING)
- [ ] Password reset uses SELECT...FOR UPDATE inside transaction
- [ ] Verification tokens hashed with selector/verifier pattern
- [ ] All `rows.Next()` loops check `rows.Err()` after iteration
- [ ] JWT_SECRET rejects CHANGE_ME placeholder at startup
- [ ] Production entrypoint exits on migration failure
- [ ] Timeout middleware uses Echo's built-in (no custom goroutine race)
- [ ] All operational constants in Config struct with env var overrides
- [ ] ForgotPassword/ResendVerification log errors server-side (anti-enumeration: always return 200)

## Frontend

- [ ] Zero `createResource` — use onMount + signals (see `solidjs-data-fetching`)
- [ ] Zero nested `<Show>` for content states — use `Switch/Match` (see `solidjs-pages`)
- [ ] Zero `window.confirm()` — use `DestructiveModal` (see `solidjs-pages`)
- [ ] Zero onMount/createEffect cleanup returns — use `onCleanup` (see `solidjs-data-fetching`)
- [ ] Zero `any` in production — use `unknown` (e.g. `Record<string, unknown>`)
- [ ] Auth store reacts to `auth:session-expired` when token cleared
- [ ] Auth cookie `Secure` on HTTPS set and clear paths
- [ ] Skip link present with correct target and `tabindex`
- [ ] Auth guard effects use `on()` without defer (see `solidjs-pages`)
- [ ] `batch()` wraps signal updates after every `await` (see `solidjs-data-fetching`)

## Security

- [ ] No endpoints leak DB errors or stack traces to clients
- [ ] Rate limiting covers auth (strict) and general API
- [ ] SSE excluded from gzip and timeout middleware
- [ ] SSE payloads validated with Zod schemas in `sse.ts` (`validators` map has entry for each event type)
- [ ] CSP configurable via `CSP_POLICY` env var
- [ ] CORS rejects all origins when `ALLOWED_ORIGINS` unset (deny-by-default)
- [ ] Password hashing uses bcrypt with 72-byte max enforcement (`len([]byte(password))`, not `len(password)`)
- [ ] Refresh token rotation is atomic (revoke + issue in one transaction)

## Tooling — Rename Tool

- [ ] Handles hyphenated names (`my-app` → `MyApp` for PascalCase identifiers)
- [ ] ALL-CAPS form handles hyphens (`my-app` → `MY_APP`, not `MY-APP`)
- [ ] Covers all file types: Go, TSX/TS, CSS, docs, Cursor rules, CI, infra, env files, entrypoints, .gcloudignore, benchmarks, openapi.yaml, scaffold, testutil, teardown.sh
- [ ] ALL-CAPS replacement applied to env files, entrypoints, and config files
- [ ] Validates project name format (lowercase alphanumeric + hyphens)
- [ ] Protects domain (original framework domain) from corruption via `replaceInFileSafe`
- [ ] `frontend/.env.example` gets lowercase + titled + ALL-CAPS passes

## Tooling — Scaffold Tool

- [ ] `singularize()` handles -us/-is/-as suffixes (prevents `status` → `statu`)
- [ ] Template includes `rows.Err()` after `rows.Next()` loops
- [ ] Template uses `toast` (not `snackbar`) for success/error notifications
- [ ] Generated Pagination component props match the actual `PaginationProps` interface
- [ ] Generated code compiles without modification (`go build`, `tsc --noEmit`)

## Documentation

- [ ] Zero broken internal links (check all `*.md` files in docs/)
- [ ] Review `docs/staleness.md` — for each row, check if the verification trigger has occurred since the last verified date
- [ ] Permission matrix (`docs/permissions.md`) matches current endpoint auth logic
- [ ] ADR stubs in `docs/adr/` with unfilled Rationale past due date — fill or remove
- [ ] Flow map primary method citations match current code (check transaction boundaries)
- [ ] README Quick Start works on fresh clone (including JWT_SECRET generation)
- [ ] `docs/quick-start.md` Option B includes JWT_SECRET generation
- [ ] `example-module.md` matches scaffold output: constructor signatures, interface pattern, ParsePagination, 5-arg List with search, rows.Err, Pagination props, toast, reactive page refetch
- [ ] Cursor rules reference correct function names, arities, and store APIs — cross-check against actual source:
  - `go-service.mdc` constructor and `NormalizePagination` signature
  - `write-tests.mdc` constructor and pagination helper
  - `frontend-lib.mdc` store method names
  - `sse-realtime.mdc` `NewSSEHub` signature, notification store, and Zod validation pattern
- [ ] Release-state docs accurate (module spec `Last Verified` dates, plan
  archive `Status` fields, rule counts, coverage thresholds, feature claims)
- [ ] All test counts, coverage numbers, and version badges match actual values
- [ ] Migration numbers in examples don't conflict with existing migrations

## Integration Tests

- [ ] All integration test files compile with current constructor signatures
- [ ] Test assertions match current service behavior (e.g., error codes, return values)
- [ ] Concurrency tests enforce correct outcomes (e.g., exactly 1 success for token refresh race)

## Thesis Alignment

- [ ] Generated service code is framework-agnostic (no Echo imports) — reflects `go-service` thesis
- [ ] Generated handlers are thin (validate → delegate → return, no business logic) — reflects `go-handler` thesis
- [ ] Generated pages use onMount + signals + alive guard + Switch/Match — reflects `solidjs-data-fetching` and `solidjs-pages` theses

## Sequential audit methodology

Running multiple audits in a row (e.g., audit → remediation → re-audit to verify) is the normal cycle. The trap: each successive audit anchors on the previous grade and confirms the predicted jump while missing real findings that only surface with fresh eyes.

The 2026-05-26 sequence is the load-bearing example:

- **Audit #1** (cold): 84/100. Surfaced 6 Important findings. Cleanup batch closed all 6.
- **Audit #2** (contextualized with "predicted to jump from 84 → 89"): 86/100. Confirmed the closures, surfaced 1 new Important.
- **Audit #3** (fresh, NO prior-grade context): 84/100 — same as cold. The fresh pass surfaced **new Important findings** (e.g. transaction boundary mistakes, `testutil.SetupTestDB` dev-DB misuse, broken rename tool) that audits #1 and #2 missed because they were focused on confirming what we'd just done.

**Rule:** For second and third audits in a sequence, dispatch the subagent **without** prior-grade context, prior Important findings, or predicted outcomes. Let the audit re-discover the state fresh. Anchoring biases the grade up and biases the finding search toward closing what was already known.

The trade-off: a fresh audit will redundantly re-confirm closed findings as "still closed", which feels like wasted work. That redundancy is the price of catching new findings.

## Handler unit test coverage

When auditing the Backend section, explicitly check `backend/internal/handler/*_test.go` parity against `backend/internal/handler/*.go`. Every handler file should have a dedicated `_test.go` exercising:

- Each public method's success path
- Each method's validation error path (where applicable)
- Each method's `NoAuth` path (where the method calls `requireUserID` / `requireUserType` / `requireBusinessID`)
- Each method's `NotFound` and `Forbidden` paths (where the service can surface them)

The canonical pattern is `backend/internal/handler/payment_test.go` — mock struct with panic-by-default + per-test func-field overrides.

Service integration tests do NOT substitute for handler unit tests. Integration tests cover the data path; handler tests cover request binding, validation, and role gates at the HTTP boundary.

## Grading

Score out of 100 with subgrades per category. List every finding with severity:
- **Blocker**: security vulnerability, data loss risk, or generated code that won't compile
- **Important**: incorrect behavior, stale references that mislead developers, or missing coverage
- **Minor**: style inconsistency, cosmetic, or documentation clarity