# Validation Rules Use this document during the **G. Validation** and **H. Final Review** stages defined in `prompts/general-prompt.md`. ## Purpose Define the repository gates that convert a plausible generation run into a verified one. These gates validate the post-generation repository state. They are not prerequisites for the clean-slate start of a repo-wide full regeneration run. Validation ownership rule: - parent owns integration, validation, acceptance/rejection decisions, and escalation to reviewer - reviewers are the final review gate, not a substitute for parent validation ## 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 - the validator is the structural gate for infrastructure, runtime/deploy artifacts, and low-level wiring contracts - evals are the semantic gate for DSL fidelity, CRUD behavior, UX invariants, and domain-contract compliance - validation must not silently ignore a forbidden pattern - build verification must not be reported as green when it was skipped - reviewed eval fixtures are the authoritative semantic gate; do not auto-rewrite the committed eval corpus as part of every regeneration run - if a new or changed entity behavior is not already represented, add or review the failing eval fixture before regeneration so evals lead the change - approved dependency-version pinning is currently a manual review requirement unless or until the structural validator grows package-manifest checks ## 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 - `client/src/vite-env.d.ts` remains present as part of the official Vite React TypeScript scaffold unless the scaffold contract is explicitly revised - package manifests must follow the approved exact-version policy from `AGENTS.md` and `prompts/general-prompt.md`; until the validator enforces this directly, treat it as a manual completion check - 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 ### Runtime / Deploy Checks - docker topology remains PostgreSQL-only - required Dockerfiles and nginx proxy config remain present when the runtime rules name them - env examples stay aligned with repository defaults - auth/runtime/realm artifacts remain coherent - `/health` remains public - Prisma lifecycle commands remain available where required ### 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 ### Realm Checks - a root `*-realm.json` artifact exists - required roles, audience delivery, and claims remain explicit - SPA and backend client structure remains explicit ### Semantic Eval Checks - `npm run eval:generation` runs fixture-based semantic checks - eval failures block completion - prompt changes that break evals are regressions, not acceptable simplifications - eval helpers may scaffold candidate contracts from source-of-truth, but the committed eval corpus remains a reviewed artifact rather than an auto-regenerated byproduct of each full run - evals own DSL fidelity, CRUD behavior, HTTP method/path behavior, DTO field coverage and decorator coverage, natural-key semantics, FK/reference wiring, Content-Range behavior, and React Admin UX/component invariants ## Split Rule The validator must not be the place where entity-level DSL fidelity is graded. - keep in the validator: scaffold health, buildability, required artifact presence, auth/runtime/deploy seams, env defaults, Docker/nginx/compose invariants, realm structure, and whether build verification was actually executed or explicitly skipped - keep in evals: per-entity file coverage, DTO field presence, decorator/type mapping, controller verb/path fidelity, list/header behavior, natural-key behavior, FK/reference UX, and other DSL-driven CRUD semantics - any validator checks that resemble output-contract checks exist only as stable syntax-level guardrails; they are justified as mechanical wiring checks, not as the semantic source of truth for generation correctness