toir-automatization/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.