rebase generation
This commit is contained in:
MaKarin
144
.claude/worktrees/goofy-haslett/docs/source-of-truth.md
Normal file
144
.claude/worktrees/goofy-haslett/docs/source-of-truth.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user