# Boilerplate Readiness This page enumerates the verification gates that protect the boilerplate's "safe to fork and build on" contract. The default CI lane is asserted by `.gitea/workflows/ci.yml`; heavier gates such as coverage, Lighthouse, Storybook, a11y, and deploy verification may live in dedicated workflow files. Failing a required gate blocks the PR or deployment lane that owns it — there is no silent override mode. ## How to read this page Each section names a gate, what it enforces, the canonical command, and the file(s) that contain the contract. Gates marked **anti-regression** keep the current floor; they only allow improvements, never regressions. Gates marked **hard contract** assert structural invariants that must always hold. ## Onboarding & branding | Gate | Contract | Command | | --- | --- | --- | | Brand env layer (hard) | All user-facing brand strings are overridable via `BRAND_*` env vars in `packages/config/src/catalog.ts`. `packages/brand/src/env.ts` is the source-of-truth loader. | `pnpm --filter @hivegrid/brand test` | | Infra-host parametrization (hard) | Gitea runner label, registry host, image prefix, DB user/name read from `scripts/infra-config.mjs` with `HIVEGRID_*` env overrides — forks can sed-replace strings and set vars without rewriting `verify-gitea-*-workflow.mjs`. | `pnpm run verify:gitea-ci-workflow && pnpm run verify:deploy-workflow` | | `.env.example` drift (hard) | Every key in `.env.{example,local.example,production.example,fly.example,test}` exists in the catalog. | `pnpm exec vitest run packages/config/src/env-examples.test.ts` | ## Internationalization | Gate | Contract | Command | | --- | --- | --- | | DE/EN namespace parity (hard) | All registered `i18nNamespaces` stay in lockstep across `de` and `en`, including app, auth, billing, CRM, settings, email marketing, mail, and error namespaces. | `pnpm run verify:i18n` | | Hardcoded user-facing strings (anti-regression) | `brand-literal`, `jsx-text`, `user-facing-prop-literal`, and `user-facing-response-literal` counts may only decrease over the ratcheted baseline; current zero-floor categories must stay at zero. | `node scripts/verify-hardcoded-strings.mjs` | | RTL/direction (hard) | `getDirection(locale)` covers known RTL languages; `isRTL` matches. | `pnpm --filter @hivegrid/i18n test` | | Mail templates (hard) | `renderTransactionalEmail(template, props)` (React-Email) renders subject + body for every supported template. Host-app translator hooks are reserved for a future i18n pass; templates emit English copy directly. | `pnpm --filter @hivegrid/mail test` | ## Security | Gate | Contract | Command | | --- | --- | --- | | Secret scanning (hard) | 10 secret-shaped patterns (GitHub PAT, AWS, Legacy-Provider `sk_live_*`, Slack, PEM, JWT, generic) scanned across `apps/packages/scripts/prisma/docs/`. Allowlist for `.env.example` variants and test fixtures. | `pnpm run verify:secrets` | | CSRF inventory (hard) | Every mutating `POST/PATCH/DELETE` route is classified in `docs/security/csrf-inventory.md`. | `pnpm exec vitest run apps/api/src/csrf-inventory.test.ts apps/web/app/utils/session-csrf-sweep.test.ts` | | Route access inventory (hard) | Every API route has an access class (`tenant-api-key`, `service-token`, `public-health`, …) documented + matching OpenAPI security. | `pnpm run verify:api-inventory && pnpm run verify:openapi-security` | | Tenant isolation (hard) | 1115 lines of runtime tests in `apps/api/src/isolation/` + `apps/web/app/test/isolation/` exercise cross-tenant mutations and assert 403/401. | `pnpm exec vitest run apps/api/src/isolation apps/web/app/test/isolation` | | Permission matrix (hard) | Role/permission seed is the source-of-truth, docs and tests stay aligned. | `pnpm run verify:permission-matrix` | | Auth error envelope (hard) | Auth middleware throws `{ error: { code, messageKey } }` envelopes, never free strings. | `pnpm exec vitest run apps/web/app/utils/loaders.middleware.test.ts` | | STRIDE threat model (doc) | `docs/security/threat-model.md` lists Spoofing/Tampering/Repudiation/Information-disclosure/DoS/Elevation threats and links each to a gate. | (review) | ## Quality & code hygiene | Gate | Contract | Command | | --- | --- | --- | | Phase-C boundaries (hard) | UI packages cannot import `@hivegrid/db`; runtime separation enforced. | `pnpm run verify:phase-c-boundaries` | | ESLint baseline (anti-regression) | `eslint-disable`, `@ts-ignore`, `@ts-expect-error` counts only decrease from the ratcheted baseline. | `pnpm run verify:eslint-baseline` | | Test density (anti-regression) | 12 workspace dirs maintain a minimum test-file-per-source-file ratio. | `pnpm run verify:test-density` | | Test coverage (anti-regression) | `scripts/coverage-targets.json` defines active per-path thresholds and release-floor sprint targets; `@vitest/coverage-v8` emits `coverage-summary.json` for the gate. The latest backlog has no critical-path positive gaps. | `pnpm run verify:test-coverage` | | Hot-swap mock visual (hard) | `verify:ui-visual` + `test:hot-swap` keep mock-driven surface stable. | `pnpm run verify:ui-visual && pnpm run test:hot-swap` | ## Operations & runtime | Gate | Contract | Command | | --- | --- | --- | | Docker non-root (hard) | All runtime stages (`web`, `api`, `worker`) drop to `USER node` before `CMD/ENTRYPOINT`. | `pnpm run verify:docker-non-root` | | Docker baseline (hard) | Dockerfile stage layout + healthchecks per stage stable. | `pnpm run verify:docker-baseline` | | Bundle-size budget (anti-regression) | JS chunks (root/route/vendor/other) and CSS stay under the +20% headroom budget from current state. | `pnpm run verify:bundle-size` | | Production seed artifact (hard) | The compiled production seed bundle is present and idempotent. | `pnpm run verify:production-seed-artifact` | | Migration rollback drill (manual) | `scripts/drill-migration-rollback.sh` replays forward chain + seed against an ephemeral postgres and asserts a re-apply is a no-op. | `./scripts/drill-migration-rollback.sh` | | Health baseline (hard) | `/healthz` and `/readyz` shapes are stable. | `pnpm run verify:health-baseline` | ## Supply chain | Mechanism | Coverage | File | | --- | --- | --- | | Dependabot | weekly npm (grouped: ai-providers / react-stack / test / lint), weekly github-actions, monthly docker | `.github/dependabot.yml` | | Renovate (Gitea) | same group config for self-hosted Gitea forks | `.gitea/renovate.json` | | SBOM | `scripts/generate-sbom.mjs` writes `sbom-pnpm.json` during the build stage; every runtime image carries the SBOM at `/myapp/sbom-pnpm.json` and labels it via `org.opencontainers.image.sbom`. | `Dockerfile`, `scripts/generate-sbom.mjs` | | Production seed bootstrap | `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD` required for prod seed; rejects the local default. | `packages/db/src/production-seed.server.ts` | ## Documentation | Doc | Purpose | | --- | --- | | `docs/quickstart.md` | Install-to-first-local-run path | | `docs/new-project.md` | Adapting the boilerplate to a new project | | `docs/deployment-porting.md` | Gitea infra-string fork procedure | | `docs/security/threat-model.md` | STRIDE per subsystem with mitigation links | | `docs/operations/database-rollback.md` | Forward-only rollback runbook + drill script reference | | `docs/ui-inventory/hot-swap-status.md` | UI registry activation state | ## Optional gates (opt-in) Some verification surfaces require a deployed environment or an external binary and are therefore not wired into the default CI lane. They SKIP cleanly (exit 0) when their prerequisites are missing, so they are safe to run locally or to enable in a downstream pipeline. | Gate | Contract | Command | Prerequisites | | --- | --- | --- | --- | | Load tests (opt-in) | k6 scripts in `tests/load/` exercise login, tenant-scoped read, and tenant-scoped mutating paths against a deployed target. Thresholds: `http_req_failed: rate<0.05`, login `p(95)<400ms` / `p(99)<800ms`, read `p(99)<300ms` and `>200 req/s`, mutating `p(99)<600ms`. | `pnpm run verify:load` | `k6` binary on PATH (`brew install k6` or ); reachable `K6_TARGET_URL` (default `http://localhost:3000`); `LOAD_TENANT_API_KEY` for the read/mutating scripts. See `tests/load/README.md` for the full env contract. | To activate the load suite in a release lane, set `K6_TARGET_URL` and `LOAD_TENANT_API_KEY` for that lane and add `pnpm run verify:load` to the job. The runner SKIPs when k6 is missing or the target is offline — the gate never blocks a CI run on environments that cannot satisfy its prerequisites. ## Composite "all gates" run There is no single mega-script — gates are intentionally separate so CI can parallelise. The canonical CI order is asserted by `verify:gitea-ci-workflow` against `.gitea/workflows/ci.yml`. To dry-run the local subset: ```sh pnpm run verify:ci-baseline pnpm run verify:env-drift pnpm run verify:health-baseline pnpm run verify:i18n pnpm run verify:hardcoded-strings pnpm run verify:phase-c-boundaries pnpm run verify:api-inventory pnpm run verify:openapi-security pnpm run verify:tenant-isolation-report pnpm run verify:docker-baseline pnpm run verify:docker-non-root pnpm run verify:secrets pnpm run verify:eslint-baseline pnpm run verify:test-density pnpm run verify:bundle-size pnpm run verify:test-coverage pnpm typecheck pnpm lint pnpm test ``` Any failure here is a CI failure. Anti-regression gates lock the current ratchet; hard contracts assert immutable structural invariants. Adopt and extend gates rather than disable them.