toir-automatization/prompts/validation-rules.md

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