toir-automatization/.claude/worktrees/goofy-haslett/docs/completion-contract.md

Completion Contract

This document defines the definition of done for a KIS-TOiR generation run. It provides prioritized success criteria, failure modes, and recovery procedures to ensure consistent, production-ready outcomes.

These criteria apply to the post-generation repository state. In a repo-wide full regeneration driven by prompts/general-prompt.md, the run intentionally starts without relying on pre-existing generated workspaces or runtime artifacts.

Prioritized Success Criteria

Tier 1: Infrastructure Readiness (Must Pass)

• By the end of the run, server/ exists and builds successfully (npm run build)
• By the end of the run, client/ exists and builds successfully (npm run build)
• node tools/validate-generation.mjs --artifacts-only passes (stable infra/runtime/deploy checks)
• Required scaffold files present (NestJS/Vite essentials)
• Runtime/deploy baseline files are present and coherent: docker-compose.yml, server/Dockerfile, client/Dockerfile, client/nginx/default.conf, env templates, and the realm artifact
• scaffolded package manifests are normalized to the repository-approved exact version policy instead of floating on latest or caret ranges

Tier 2: Domain Fidelity (Must Pass)

• npm run eval:generation passes (DSL fidelity, CRUD behavior, UX invariants)
• DTOs match DSL shapes exactly
• Controllers have correct guards and roles
• React Admin resources use type-correct components
• Natural-key handling correct
• Prisma schema reflects DSL without manual edits
• Reviewed eval contracts lead any new or changed entity behavior before regeneration; automation may scaffold candidate contracts, but it must not silently rewrite the committed eval corpus during every run
• Specialized generator outputs respect frozen-contract write-zones and do not leak unauthorized cross-layer edits

Tier 3: Runtime/Deploy Readiness (Must Pass)

• Production Dockerfiles exist and are valid
• Reverse-proxy nginx config supports SPA routing and /api proxying
• Compose topology matches the repository contract: postgres, server, db-seed, and client, with Keycloak external to the compose stack
• Env examples align with auth/runtime contracts
• Realm artifact matches frontend/backend expectations
• Runtime/deploy artifacts are treated as first-class generation targets, not optional extras

Tier 3A: Prisma Migration Policy (Current Explicit State)

• Current state: accepted temporary technical debt
• Immediate contract: server/prisma/schema.prisma must match the DSL
• Current runtime behavior: if committed migrations exist, runtime uses prisma migrate deploy; if not, bootstrap flows may fall back to prisma db push
• Preferred target: commit reviewed Prisma migrations for each DSL-driven schema change and remove the db push fallback from production/runtime paths

Tier 4: Auth Seam Integrity (Must Pass)

• JWKS resolution works (no silent failures)
• Role extraction from realm_access.roles
• /health remains public
• 401/403 semantics correct

Failure Modes and Recovery

Failure Mode: Scaffold Degradation

Symptoms: Build fails, missing Nest/Vite files. Recovery: Run official CLI repair (nest new or vite create), then regenerate domain code.

Failure Mode: DSL Mismatch

Symptoms: Eval fails on DTO shapes or field mappings. Recovery: Re-read DSL entity block, regenerate affected artifacts, re-run evals.

Failure Mode: Delegated Output Drift

Symptoms: A specialized generator edits unauthorized zones, violates the frozen contract, or hands back output that is not integration-ready. Recovery: Allow one bounded repair pass. If drift remains, reject the output explicitly and only then use parent manual fallback.

Failure Mode: Guard/Header Issues

Symptoms: Eval fails on guards or Content-Range. Recovery: Fix guard order (JwtAuthGuard first), ensure Content-Range format (items), re-run evals.

Failure Mode: Relation Annotation Missing

Symptoms: Prisma schema invalid. Recovery: Add explicit @relation(fields: [...], references: [...]), regenerate schema.

Failure Mode: Runtime/Deploy Gaps

Symptoms: Docker build fails, nginx proxy broken. Recovery: Update prompts/runtime-rules.md, regenerate the affected runtime/deploy artifacts, and verify the deploy baseline again.

Failure Mode: Auth Seam Drift

Symptoms: JWKS fails, roles not extracted. Recovery: Verify JWKS order, ensure realm_access.roles, regenerate auth artifacts.

Recovery Procedures

1. Partial Regenerate: If only one entity fails, regenerate that entity only.
2. Full Reset: If scaffold broken or a repo-wide regeneration is requested, remove the generated Tier 3 app/runtime outputs (server/, client/, db-seed/, root runtime artifacts), re-scaffold from official CLIs, and regenerate all.
3. Rollback: If generation introduces breaking changes, revert to last passing commit.
4. Debug Mode: Run node tools/validate-generation.mjs with --run-runtime for deeper checks.

Acceptance Protocol

Parent acceptance is explicit for all delegated generation outputs.

A delegated output is accepted only if:

• only allowed zones were modified
• the frozen contract is respected
• no unauthorized cross-layer edits occurred
• the result is integration-ready
• relevant checks were attempted where applicable
• unresolved issues are surfaced explicitly

Escalation rule:

• allow at most one bounded repair pass
• reject explicitly if the output still is not usable
• manual fallback is allowed only after rejection

Definition of Complete

A generation run is complete when all Tier 1-4 criteria pass, the explicit Prisma migration policy state is acknowledged, contract freeze and delegated acceptance rules were respected, the reviewer signs off, the package manifests follow the approved version policy, and the app is runnable/deployable with the repository-managed runtime/deploy artifacts and documented external dependencies.