101 lines
5.1 KiB
Markdown
101 lines
5.1 KiB
Markdown
# 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 **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
|