(llm-first): context budget, validation, and eval harness, orchestration general-prompt

2026-04-03 14:17:21 +03:00
parent 79c9589658
commit c42a88dff6
189 changed files with 15538 additions and 9109 deletions
--- a/.codex/AGENTS.md
+++ b/.codex/AGENTS.md
@@ -0,0 +1,108 @@
+# Codex CLI — KIS-TOiR workspace supplement
+
+This file supplements the repository root `AGENTS.md` with Codex-specific
+operational notes. The root `AGENTS.md` is the authoritative contract —
+if anything here contradicts root, root wins.
+
+---
+
+## Agent role summary
+
+| Role | Config file | Sandbox | Write boundary |
+|------|-------------|---------|----------------|
+| `generator` | `agents/generator.toml` | workspace-write | Tier 3 generation zones |
+| `explorer` | `agents/explorer.toml` | read-only | None |
+| `reviewer` | `agents/reviewer.toml` | read-only | Proposes patches only |
+| `docs_researcher` | `agents/docs-researcher.toml` | read-only | None |
+
+Use `/agent generator` for implementation work. Use `/agent explorer` first for
+discovery, `/agent docs_researcher` when framework or prompt patterns need
+verification, and `/agent reviewer` before claiming a generation run is complete.
+
+---
+
+## Mutation boundary map
+
+```
+Tier 1 — Source of truth (NEVER written by any agent)
+  domain/*.api.dsl              — single source of truth for all generation
+  prompts/*.md                  — generation spec / rules
+  AGENTS.md                     — agent operating rules
+  .codex/AGENTS.md (this file)  — Codex-specific supplement
+
+Tier 2 — Deterministic derivatives (written only by npm scripts, not by agents)
+  api-summary.json              ← npm run generate:api-summary
+  openapi.json                  ← npm run generate:openapi  (auxiliary)
+
+Tier 3 — LLM-generated artifacts (written ONLY by generator agent)
+  server/src/modules/<entity>/
+  client/src/resources/<entity>/
+  server/src/app.module.ts
+  client/src/App.tsx
+  server/prisma/schema.prisma   ← LLM-generated per prompts/prisma-rules.md
+  server/src/auth/
+  client/src/auth/
+  client/src/dataProvider.ts
+  toir-realm.json
+  docker-compose.yml
+  server/.env.example
+  client/.env.example
+
+Tier 4 — Handwritten / framework-managed support files
+  framework scaffold and other manual support files outside prompt-governed outputs
+```
+
+---
+
+## Standard generation invocation
+
+```bash
+# 1. Read AGENTS.md + prompts/general-prompt.md
+# 2. Read the entity-scoped DSL block from domain/toir.api.dsl
+# 3. Load only the stage-specific companion rules you need
+# 4. Run generation or repair with the appropriate agent
+# 5. Refresh api-summary.json only if validator/tooling expects the auxiliary freshness artifact
+# 6. Verify (both stages must pass)
+node tools/validate-generation.mjs --artifacts-only
+npm run eval:generation
+```
+
+---
+
+## MCP servers (project-local)
+
+Defined in `.codex/config.toml`:
+
+- **github** — repository access
+- **context7** — library documentation lookup (use for framework questions)
+- **exa** — web search
+- **memory** — persistent cross-session context
+- **playwright** — browser automation for smoke tests
+- **sequential-thinking** — structured multi-step reasoning
+
+Add heavier or credential-backed servers in `~/.codex/config.toml`.
+
+---
+
+## Validation gate
+
+Run before every commit and after every generation:
+
+```bash
+# Stage 1 — structural gate
+node tools/validate-generation.mjs --artifacts-only
+
+# Stage 2 — eval harness
+npm run eval:generation
+```
+
+The pre-commit hook (`tools/hooks/pre-commit`) runs both stages automatically
+after `npm run install-hooks`.
+
+---
+
+## Security notes
+
+- Never commit secrets. Use environment variables from `.env.example` templates.
+- Run `npm audit` when adding new dependencies to `server/` or `client/`.
+- Auth contracts live in `prompts/auth-rules.md`. Do not deviate from them.