git init

docs/source-of-truth.md

@@ -0,0 +1,96 @@
+# 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`.
+
+### `prompts/*.md` and `AGENTS.md`
+
+**Authoritative for:**
+
+- Agent generation workflow and reading order
+- 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)
+
+---
+
+## 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)
+
+| 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  |
+
+To change these files: update `domain/*.api.dsl` and regenerate.
+
+---
+
+## Tier 4: Handwritten (not generated; not derived)
+
+- Auth seams: `client/src/auth/`, `server/src/auth/`
+- `toir-realm.json`
+- `docker-compose.yml`
+- `server/.env.example`, `client/.env.example`
+- Framework config: `nest-cli.json`, `tsconfig*.json`, `vite.config.*`, etc.
+- All `prompts/*.md`, `AGENTS.md`, `domain/dsl-spec.md`, `domain/*.api.dsl`
+
+---
+
+## Validation gate
+
+### Stage 1 — Structural gate
+
+```
+node tools/validate-generation.mjs --artifacts-only
+```
+
+Verifies that generated artifacts satisfy the contracts declared in Tier 1 sources.
+
+### Stage 2 — Eval harness
+
+```
+npm run eval:generation
+```
+
+Fixture-based semantic checks from `tools/eval/fixtures/`.
+
+Both stages must pass before any generation task is considered complete.