Track verification tooling upgrades for visual, format, complexity, coverage, and secrets

[BASIC-BIT]

Parent epic: #43

Problem

VRDex has a useful baseline verification loop now, but the current gates are still mostly lint/typecheck/build/backend checks. As the product adds real public UI and submission flows, we need a single tracking issue for the next layer of quality gates: visual confidence, formatting consistency, dead-code checks, coverage, complexity reporting, and secret-scanning posture.

Current baseline

Already wired:

• web lint via pnpm lint:web
• web typecheck via pnpm typecheck:web
• web build via pnpm build:web
• backend typecheck via pnpm typecheck:backend
• backend unit tests via pnpm test:backend
• local Convex verification plus generated API diff check via pnpm check:backend:generated
• CI workflow in .github/workflows/baseline-checks.yml
• Husky pre-commit hook running pnpm lint-staged
• lint-staged ESLint autofix for staged web JS/TS files

Not yet wired:

• screenshot tests
• Playwright e2e/smoke tests
• Prettier/Biome formatting
• complexity checks such as scc, lizard, or ESLint complexity rules
• coverage reporting
• dead-code / unused dependency checks such as knip
• repo-local secret-scanning CI workflow
• PR screenshot artifacts or visual review evidence

Scope

Add staged quality and verification tooling without making early UI iteration painful.

Recommended phases:

1. Add Playwright smoke coverage and screenshot artifacts for core public routes.
2. Add formatting policy, choosing either Prettier or Biome.
3. Add dead-code / unused-dependency reporting, likely knip.
4. Add backend helper coverage reporting.
5. Add complexity and size metrics as report-only first.
6. Add repo-local secret-scanning/checks for PRs.
7. Document the verification loop and when each gate should be blocking vs advisory.

Candidate checklist

Playwright and visual confidence

• Add Playwright dependency and config.
• Add smoke tests for /, /submit, /p/<slug>, and /c/<slug>.
• Provide deterministic seed or fixture path for public profile pages.
• Capture screenshots as CI artifacts for public UI routes.
• Keep visual snapshot assertions report-only at first, unless the route is stable enough to gate.
• Document local commands for running Playwright and inspecting screenshots.

Formatting

• Decide between Prettier and Biome for formatting.
• Add format/check scripts.
• Integrate formatting with lint-staged.
• Add CI format check if the tool is stable and low-noise.
• Document the formatting policy.

Dead code and dependency hygiene

• Add knip or equivalent unused-file/export/dependency check.
• Start as report-only or narrowly scoped to avoid false-positive churn.
• Document suppressions/ignores for generated files and framework conventions.

Coverage

• Add coverage reporting for backend unit tests.
• Decide whether coverage should be threshold-gated now or report-only first.
• Include helper modules such as slug, permission, claim-state, public projection, and submission sanitization logic.

Complexity and size metrics

• Add size/LOC reporting, likely scc, as advisory output.
• Evaluate cyclomatic/maintainability checks via ESLint complexity rules, lizard, or another JS/TS-friendly tool.
• Start complexity as report-only before enforcing thresholds.
• Document intended thresholds once enough code exists to calibrate them.

Secret scanning and policy checks

• Add a repo-local PR check for likely committed secrets or credentials.
• Ensure .env*, Convex local state, and generated local files remain ignored/uncommitted.
• Consider AST-grep or equivalent policy checks for dangerous patterns later.

CI and docs

• Update .github/workflows/baseline-checks.yml or add dedicated workflows for new checks.
• Update README.md with new local verification commands.
• Update docs/planning/architecture.md or a dedicated verification doc with blocking vs advisory gate policy.
• Keep early UI visual checks useful without blocking every design iteration.

Non-goals

• full visual regression gating for every route immediately
• exhaustive e2e coverage
• strict coverage thresholds before the backend surface stabilizes
• blocking complexity thresholds before enough code exists to calibrate them
• replacing GitHub platform-level secret scanning if it is already enabled

Acceptance criteria

• the repo has a documented verification roadmap covering visual, format, complexity, coverage, dead-code, and secret-scanning checks
• at least the first slice of Playwright/screenshot confidence is implemented or split into a concrete follow-up PR
• new checks are categorized as blocking or advisory
• local commands and CI behavior are documented clearly enough for agents and humans to use consistently

Related context

This came out of reviewing the verification posture after adding the first public submission/profile-page slice in #70.