git init

prompts/validation-rules.md

@@ -0,0 +1,101 @@
+# Validation Rules
+
+<!-- prompt-version: 2.0 -->
+<!-- applies-to: tools/validate-generation.mjs and npm run eval:generation -->
+<!-- validated-by: self -->
+
+Use this document during the **Verification / Success Gate** stage defined in `prompts/general-prompt.md`.
+
+## Purpose
+
+Define the repository gates that convert a plausible generation run into a verified one.
+
+## Primary Gates
+
+- `node tools/validate-generation.mjs --artifacts-only`
+- `npm run eval:generation`
+
+## Auxiliary Freshness Prep
+
+- `npm run generate:api-summary`
+
+Run the freshness prep when the repository validator or supporting tooling expects `api-summary.json` to exist and match the current DSL. This artifact is auxiliary to validation and inventory, not the generation source of truth.
+
+## Prompt-Gate Alignment Rule
+
+- every invariant marked required in the active prompt corpus must either be enforced by a gate or called out as manual/runtime-only
+- validation must not silently ignore a forbidden pattern
+- build verification must not be reported as green when it was skipped
+
+## Gate Groups
+
+### Build Checks
+
+- at least one `domain/*.api.dsl` file exists
+- required artifacts exist:
+  - `server/prisma/schema.prisma`
+  - env examples
+  - required scaffold files
+  - auth/runtime/realm artifacts
+- if the current validator policy checks `api-summary.json`, it exists and is fresh relative to the DSL
+- `server/` remains a valid Nest workspace
+- `client/` remains a valid Vite workspace
+- if dependencies are installed, backend and frontend build verification runs
+- if dependencies are missing, build verification is reported as skipped with reason instead of green
+
+### Auth Checks
+
+- frontend auth seam files exist
+- backend auth seam files exist
+- `401` and `403` semantics remain split
+- auth code keeps the required Keycloak/JWT contracts
+- JWKS resolution order remains:
+  1. explicit `KEYCLOAK_JWKS_URL`
+  2. OIDC discovery
+  3. certs fallback
+
+### Filter And UI Checks
+
+- list resources expose filter UI including `FilterButton`
+- reference filters use `ReferenceInput` + `AutocompleteInput` with `filterToQuery`
+- `dataProvider` preserves repeated query params for array filters
+- backend FK filters remain exact-match
+- repeated enum params map to Prisma `in`
+- Create/Edit forms keep type-correct inputs
+- navigable references keep `ReferenceField link="show"`
+- resources keep `show={...}` registration in `App.tsx`
+
+### Natural-Key Checks
+
+- response records expose `id`
+- route/update contracts use the real primary key
+- natural-key sort/update paths do not regress to a fake physical `id`
+
+### Realm Checks
+
+- a root `*-realm.json` artifact exists
+- required roles, audience delivery, and claims remain explicit
+- SPA and backend client structure remains explicit
+
+### Runtime Checks
+
+- Docker topology remains PostgreSQL-only
+- Prisma lifecycle commands remain available where required
+- `/health` remains public
+- backend build runs inside `server/`
+- frontend build runs inside `client/`
+- client/server `.env.example` stay aligned with repository defaults
+
+### Output Contract Checks
+
+- every generated Create/Update DTO imports from `'class-validator'`
+- DTO fields have type-correct decorators
+- optional/nullable fields carry `@IsOptional()` before the type decorator
+- controllers carry the required guards and roles
+- React Admin components use correct input/field types
+
+### Eval Harness
+
+- `npm run eval:generation` runs fixture-based semantic checks
+- eval failures block completion
+- prompt changes that break evals are regressions, not acceptable simplifications