toir-automatization/.claude/worktrees/goofy-haslett/docs/source-of-truth.md

Source-of-Truth Hierarchy

This document is the authoritative reference for which files own which decisions.

---

Tier 1: Authoritative sources (hand-authored; never generated)

domain/*.api.dsl

Single source of truth for the entire domain and API contract:

• Entity names and structure
• Attribute names, scalar types, descriptions
• Primary keys (including natural string keys)
• Foreign keys and relations
• Enum definitions and their values
• Database-level constraints: is required, is unique, default
• DTO shapes per operation (Create, Update, Read, ListRequest, ListResponse)
• Which fields appear in each DTO and with what TypeScript modifier (! or ?)
• HTTP method and path for each endpoint (via label "METHOD /path")
• Endpoint names (camelCase identifiers)
• Pagination request/response contract

Drives: server/prisma/schema.prisma, server/src/modules/, client/src/resources/, server/src/app.module.ts, client/src/App.tsx, and the generated auth/runtime/deploy artifacts named by the companion prompt contracts.

prompts/*.md and AGENTS.md

Authoritative for:

• Agent generation workflow and reading order
• Parent-versus-specialist orchestration ownership
• Approved stack versions and dependency pinning policy
• Auth seam patterns (Keycloak, JWT, PKCE S256, JWKS resolution chain)
• Runtime conventions (env examples, docker-compose topology)
• Framework scaffold baseline requirements (NestJS CLI, Vite React TypeScript)
• Filtering and sorting contract
• Naming conventions and implicit rules (pluralization, sort field priority, type mappings)
• Mutation boundaries (what agents must not overwrite)
• Runtime/deploy artifact classification and preservation rules

docs/completion-contract.md

Operational definition of done for generation runs:

• prioritized success tiers
• failure modes and recovery procedures
• reviewer signoff requirement
• runtime/deploy readiness requirements

---

Tier 2: Deterministic derivatives (never edit manually)

File	Generated from	Command
api-summary.json	domain/*.api.dsl	npm run generate:api-summary

These files are regenerated from their sources. Manual edits are overwritten on the next generation run.

---

Tier 3: LLM-generated artifacts (never edit manually after generation)

These are end-state outputs. A repo-wide full regeneration may begin with some or all Tier 3 artifacts absent and then recreate them from Tier 1 inputs plus official CLI scaffolding.

Zone	Generated from
server/prisma/schema.prisma	domain/*.api.dsl + prompts/prisma-rules.md
server/src/modules/<entity>/	domain/*.api.dsl + prompts/backend-rules.md
client/src/resources/<entity>/	domain/*.api.dsl + prompts/frontend-rules.md
server/src/app.module.ts	Module list derived from api.dsl api blocks
client/src/App.tsx	Resource list derived from api.dsl api blocks
docker-compose.yml	prompts/runtime-rules.md
server/Dockerfile	prompts/runtime-rules.md
client/Dockerfile	prompts/runtime-rules.md
client/nginx/default.conf	prompts/runtime-rules.md
server/.env.example	prompts/runtime-rules.md
client/.env.example	prompts/runtime-rules.md
server/docker-entrypoint.sh	prompts/runtime-rules.md
db-seed/Dockerfile	prompts/runtime-rules.md
db-seed/import.sh	prompts/runtime-rules.md
server/src/auth/	prompts/auth-rules.md
client/src/auth/	prompts/auth-rules.md
client/src/dataProvider.ts	prompts/auth-rules.md
toir-realm.json	prompts/auth-rules.md

To change DSL-driven domain artifacts: update domain/*.api.dsl and regenerate. To change auth/runtime/deploy artifacts: update the governing prompt contracts and regenerate or repair them through the orchestrator.

Ownership rule for Tier 3:

• parent owns shared scaffold, auth platform skeleton, deploy/runtime skeleton, env conventions, integration, and validation
• generator_prisma owns server/prisma/schema.prisma
• generator_nest_resources owns server/src/modules/** plus delegated backend registration touchpoints
• generator_react_admin_resources owns client/src/resources/** plus delegated frontend registration touchpoints
• generator_data_access owns client/src/dataProvider.ts and any parent-delegated narrow frontend integration seam
• specialized generators must not redesign shared auth/runtime/platform seams outside their delegated zones

Contract freeze rule:

• before specialized generation, the parent must freeze a structured handoff covering entities, fields, types, ids/composite keys, relations, enums, endpoint/path conventions, naming rules, auth surface expectations, validator/eval constraints, and allowed write-zones per generator
• this handoff is an orchestration protocol, not a replacement for the DSL

---

Tier 4: Framework-managed support

• Prisma migrations under server/prisma/migrations/ when created by the official Prisma CLI
• Framework config: nest-cli.json, tsconfig*.json, vite.config.*, etc.
• All prompts/*.md, AGENTS.md, domain/dsl-spec.md, domain/*.api.dsl

Runtime/deploy policy:

• Tier 3 runtime/deploy outputs are first-class generation targets and should be regenerated or repaired from the companion rules when they drift.
• Tier 4 support files are framework-managed rather than hand-authored sources of truth.

---

Validation gate

Stage 1 — Structural gate

node tools/validate-generation.mjs --artifacts-only

Verifies scaffold/build readiness, required runtime/deploy artifacts, auth/runtime seams, realm structure, and other stable repository invariants. This gate validates the post-generation state, not the clean-slate starting state for a full regeneration run.

Stage 2 — Eval harness

npm run eval:generation

Fixture-based semantic checks from tools/eval/fixtures/ for DSL fidelity, CRUD behavior, natural-key handling, and UI invariants.

Both stages must pass before any generation task is considered complete.