@rawsql-ts/ztd-cli 0.14.2 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rawsql-ts/ztd-cli",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "DB-agnostic scaffolding and DDL helpers for Zero Table Dependency projects",
   "main": "dist/index.js",
   "bin": {
@@ -25,8 +25,8 @@
     "chokidar": "^5.0.0",
     "commander": "^12.0.0",
     "diff": "^5.1.0",
-    "@rawsql-ts/testkit-core": "0.14.2",
-    "rawsql-ts": "0.14.2"
+    "@rawsql-ts/testkit-core": "0.14.3",
+    "rawsql-ts": "0.14.3"
   },
   "devDependencies": {
     "@types/diff": "^5.0.1",

package/templates/AGENTS.md

@@ -1,14 +1,22 @@
 # Appendix: Development Workflow Using Zero Table Dependency (ZTD)
 
-This application uses **Zero Table Dependency (ZTD)** as an internal development workflow for writing, testing, and maintaining SQL logic.  
+This application uses **Zero Table Dependency (ZTD)** as an internal development workflow for writing, testing, and maintaining SQL logic.
 ZTD is not part of the application's runtime behavior; rather, it provides a framework for:
 
-- Maintaining consistent SQL across the project  
-- Keeping schema, domain specifications, and enums synchronized  
-- Ensuring deterministic SQL unit tests  
-- Enabling structured collaboration between humans and AI  
+- Maintaining consistent SQL across the project
+- Keeping schema, domain specifications, and enums synchronized
+- Ensuring deterministic SQL unit tests
+- Enabling structured collaboration between humans and AI
 
-This section documents how ZTD is used *inside this repository* as a development methodology.
+This section documents how ZTD is used inside this repository as a development methodology.
+
+---
+
+## Defaults (important)
+
+- This project adopts **ZTD as the default development and testing methodology**.
+- ZTD is assumed unless explicitly stated otherwise.
+- Detailed rules about test execution modes are defined in `templates/tests/AGENTS.md`.
 
 ---
 
@@ -61,14 +69,14 @@ The `src/` directory should contain pure TypeScript logic that operates on the r
 ### Sequence / identity column policy (important)
 
 - Sequence / identity columns (auto-generated IDs) are infrastructure concerns.
-- Do **not** explicitly assign values to sequence / identity columns in `INSERT` statements unless explicitly instructed.
+- Do not explicitly assign values to sequence / identity columns in `INSERT` statements unless explicitly instructed.
 - Repository method inputs should omit sequence / identity columns by default.
 - Only treat an ID as input data when it represents a business rule (e.g. natural keys, externally assigned IDs).
 
 ### No test-driven fallbacks in production code (important)
 
-- **Do not add fallbacks in `src/` that exist only to accommodate ZTD/testkit/rewriter limitations.**
-- If a query fails to be rewritten into ZTD form (e.g. rawsql-ts parsing/rewrite failure), **do not “paper over” it** by changing runtime behavior, adding `max(id)+1`, or introducing alternative logic paths.
+- Do not add fallbacks in `src/` that exist only to accommodate ZTD/testkit/rewriter limitations.
+- If a query fails to be rewritten into ZTD form (e.g. rawsql-ts parsing/rewrite failure), do not paper over it by changing runtime behavior, adding `max(id)+1`, or introducing alternative logic paths.
 - Instead, stop and report the issue with evidence:
   - The exact SQL that fails
   - The error message / symptoms
@@ -81,51 +89,11 @@ Rationale: Production code must not diverge from the intended SQL semantics due
 
 ## ZTD Test Guide (tests/)
 
-Fixtures come from the `ztd/ddl/` definitions and power `pg-testkit`. Always import table types from `tests/generated/ztd-row-map.generated.ts` when constructing scenarios, and rerun `npx ztd ztd-config` whenever schema changes to keep the fixtures and row map synchronized.
-
-If you are working inside this repository's `ztd-playground`, regenerate the generated artifacts with `pnpm --filter ztd-playground exec ztd ztd-config`.
-
-- Set `ZTD_EXECUTION_MODE=traditional` or pass `{ mode: 'traditional', traditional: { isolation: 'schema', cleanup: 'drop_schema' } }` to `createTestkitClient()` when you must exercise real Postgres semantics (locks, isolation, constraints). Traditional mode still runs the DDL inside `ztd/ddl/`, seeds the fixtures, executes any optional `setupSql`, and honors the configured `cleanup` strategy (`drop_schema` by default, `custom_sql`, or `none` for debugging) so the environment stays tidy. Use `isolation: 'none'` when your queries explicitly reference an existing schema and you cannot rely on schema-based isolation.
-
-
-### Tests: What to Care About
-
-#### Test Intent
-- Each test should have a single clear observation point.
-- Decide whether the test verifies:
-  - Query semantics (input to output behavior), or
-  - Structural properties (ordering, filtering, boundary cases).
-
-#### Fixtures
-- Keep fixtures minimal and intention-revealing.
-- Prefer small datasets over large ones.
-- Avoid adding rows or columns that are not directly related to the test intent.
-
-#### Assertions
-- Assert only on relevant columns and values.
-- Do not rely on implicit ordering; if order matters, make it explicit in SQL and assertions.
-- Avoid custom verification logic; rely on query results and straightforward assertions.
-
-#### Relationship to Repositories
-- Tests for repositories should focus on observable behavior, not internal implementation details.
-- Avoid duplicating repository logic inside tests.
-
-### Notes
-- These guidelines are intentionally lightweight.
-- They are expected to evolve based on actual usage and failure cases.
-- If user instructions conflict with these guidelines, follow user instructions.
-
-### ID expectations in tests (important)
-
-- Do not assert auto-generated ID values (sequence / identity), such as "the next id is 11".
-- When creating rows, assert only that an ID exists and has the correct type, or that it differs from known existing IDs.
-- Only assert specific ID values when the ID is part of a business rule (not infrastructure), e.g. a natural key or a fixed, meaningful identifier.
+Testing under ZTD follows dedicated, directory-scoped rules.
 
-## Parallel test policy (important)
-
-- ZTD tests should be safe to run in parallel against a single Postgres instance because pg-testkit rewrites CRUD into fixture-backed SELECT queries (no physical schema changes).
-- Do not start multiple Postgres instances per test file/worker, and do not isolate tests by creating per-test databases or schemas. This is unnecessary for ZTD and adds failure modes.
-- Prefer one shared Postgres instance + multiple connections, limited only by your DB resources.
+- Test design, execution mode selection, and constraints are defined in:
+  - `templates/tests/AGENTS.md`
+- This file intentionally avoids duplicating test-specific operational rules to prevent divergence.
 
 ---
 
@@ -153,25 +121,40 @@ The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points
 
 ---
 
+# Protected directories and edit ownership (important)
+
+- DDL editing is human-led: `ztd/ddl/`
+- Domain specs editing is human-led: `ztd/domain-specs/`
+- Enums editing is human-led: `ztd/enums/`
+- Application code is shared ownership: `src/`
+- Tests are shared ownership: `tests/`
+  - Detailed test constraints live in `templates/tests/AGENTS.md`.
+
+Additionally:
+- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction.
+- When changes are required in human-led directories, prefer proposing a patch and explaining the impact before applying it.
+
+---
+
 # Principles of ZTD in This Repository
 
-### 1. Humans own the **definitions**
+### 1. Humans own the definitions
 - Physical schema (DDL)
 - Domain semantics (domain-specs)
 - Enumerations (enums)
 - Repository interfaces
 
-### 2. AI assists with **implementation**
+### 2. AI assists with implementation
 - Generating repository SQL
 - Updating fixtures
 - Producing intermediate TypeScript structures
 - Ensuring SQL adheres to DDL, enums, and domain-specs
 
-### 3. ZTD enforces **consistency**
+### 3. ZTD enforces consistency
 ZTD tests verify that:
-- SQL logic matches DDL shapes  
-- SQL semantics match domain-specs  
-- SQL values match enumerations  
+- SQL logic matches DDL shapes
+- SQL semantics match domain-specs
+- SQL values match enumerations
 
 If anything diverges, ZTD failures surface immediately and deterministically.
 
@@ -183,27 +166,20 @@ Different types of changes start from different entry points. Use the workflow a
 
 ---
 
-# Workflow A — Starting From *DDL Changes*
+# Workflow A - Starting From DDL Changes
 Modifying tables, columns, constraints, indexes.
 
 1. Edit DDL files in `ztd/ddl/`.
-2. Run:
-
-   ```bash
-   npx ztd ztd-config
-   ```
-
-   This regenerates `tests/generated/ztd-row-map.generated.ts` from the updated schema.
-
+2. Run `npx ztd ztd-config`.
 3. Update repository SQL to match the new schema.
 4. Update fixtures if result shapes changed.
 5. Run tests.
 
-**Flow:** DDL -> Repository SQL -> Fixtures/Tests -> Application
+Flow: DDL to Repository SQL to Fixtures and Tests to Application
 
 ---
 
-# Workflow B — Starting From *Repository Interface Changes*
+# Workflow B - Starting From Repository Interface Changes
 Changing method signatures, adding new repository methods, etc.
 
 1. Modify the repository interface or implementation in `/src`.
@@ -212,11 +188,11 @@ Changing method signatures, adding new repository methods, etc.
 4. Run ZTD tests.
 5. Regenerate config if SQL output shape changed.
 
-**Flow:** Interface -> SQL -> Specs (if needed) -> Tests
+Flow: Interface to SQL to Specs (if needed) to Tests
 
 ---
 
-# Workflow C — Starting From *Repository SQL Logic Changes*
+# Workflow C - Starting From Repository SQL Logic Changes
 Bug fixes, refactoring, rewriting queries.
 
 1. Edit SQL inside the repository.
@@ -225,46 +201,27 @@ Bug fixes, refactoring, rewriting queries.
 4. Update fixtures as needed.
 5. Regenerate config if result shape changed.
 
-**Flow:** SQL -> Domain-specs -> Tests
+Flow: SQL to Domain-specs to Tests
 
 ---
 
-# Workflow D — Starting From *Enum or Domain Specification Changes*
+# Workflow D - Starting From Enum or Domain Specification Changes
 Business rule changes or conceptual model updates.
 
-## Editing enums:
-
-1. Update the relevant `.md` file under `ztd/enums/`.
-2. Run:
-
-   ```bash
-   npx ztd ztd-config
-   ```
-
-3. Update repository SQL referencing enum values.
-4. Update fixtures/tests.
-
-## Editing domain-specs:
-
-1. Update the relevant `.md` file under `ztd/domain-specs/`.
-2. Update repository SQL to reflect the new semantics.
-3. Update or add tests.
-4. Update DDL only if the new rules require schema changes.
-
-**Flow:** Specs/Enums -> SQL -> Tests -> (DDL if required)
+Flow: Specs or Enums to SQL to Tests to (DDL if required)
 
 ---
 
 # Combined Real-World Examples
 
-- Adding a new contract state:  
-  enums -> domain-spec -> SQL -> config -> tests
+- Adding a new contract state:
+  enums to domain-spec to SQL to config to tests
 
-- Adding a new table:  
-  DDL -> config -> SQL -> fixtures -> tests
+- Adding a new table:
+  DDL to config to SQL to fixtures to tests
 
-- Fixing business logic:  
-  SQL -> domain-spec -> tests
+- Fixing business logic:
+  SQL to domain-spec to tests
 
 ZTD ensures the development always converges into a consistent, validated workflow.
 
@@ -278,9 +235,9 @@ Humans maintain:
 - Domain logic definitions (`ztd/domain-specs`)
 - Domain enumerations (`ztd/enums`)
 - Repository interfaces and architectural decisions
-- Acceptance/review of AI-generated patches
+- Acceptance and review of AI-generated patches
 
-Humans decide **what is correct**.
+Humans decide what is correct.
 
 ---
 
@@ -288,14 +245,14 @@ Humans decide **what is correct**.
 
 AI must:
 
-- Use domain-specs as the semantic source of truth  
-- Use enums as the canonical vocabulary source  
-- Use DDL as the physical structure constraint  
-- Generate SQL consistent with all definitions  
-- Update fixtures when needed  
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction  
+- Use domain-specs as the semantic source of truth
+- Use enums as the canonical vocabulary source
+- Use DDL as the physical structure constraint
+- Generate SQL consistent with all definitions
+- Update fixtures when needed
+- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction
 
-AI decides **how to implement**, but not **what is correct**.
+AI decides how to implement, but not what is correct.
 
 ---
 
@@ -303,10 +260,10 @@ AI decides **how to implement**, but not **what is correct**.
 
 ZTD CLI:
 
-- Parses DDL to compute schema shapes  
-- Rewrites SQL via CTE shadowing for testing  
-- Generates `ztd-row-map.generated.ts`  
-- Enables deterministic, parallel SQL unit tests  
+- Parses DDL to compute schema shapes
+- Rewrites SQL via CTE shadowing for testing
+- Generates `ztd-row-map.generated.ts`
+- Enables deterministic, parallel SQL unit tests
 
 ZTD is the verification engine that validates correctness beyond static typing.
 
@@ -314,13 +271,13 @@ ZTD is the verification engine that validates correctness beyond static typing.
 
 # Summary
 
-This appendix documents how ZTD is used strictly as an **internal implementation and maintenance guide**.  
-It does not affect the runtime behavior of the application.  
+This appendix documents how ZTD is used strictly as an internal implementation and maintenance guide.
+It does not affect the runtime behavior of the application.
 Its purpose is ensuring:
 
-- Schema integrity  
-- SQL correctness  
-- Domain consistency  
-- Reliable AI-assisted development  
+- Schema integrity
+- SQL correctness
+- Domain consistency
+- Reliable AI-assisted development
 
-With ZTD, **humans define the meaning**, **AI writes the implementation**, and **tests guarantee correctness**.
+With ZTD, humans define the meaning, AI writes the implementation, and tests guarantee correctness.

package/templates/tests/AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS: ZTD Test Guidelines
+
+This file defines **rules and boundaries for writing tests under `tests/`**.
+Tests are a shared workspace for humans and AI, but must respect ZTD-specific constraints.
+
+---
+
+## Default execution mode (important)
+
+- The default execution mode for tests is **ZTD**.
+- Do not switch to Traditional mode unless explicitly instructed by a human.
+- Do not set `ZTD_EXECUTION_MODE=traditional` or pass `{ mode: "traditional" }` to `createTestkitClient()` without explicit instruction.
+- If instructions are ambiguous, assume ZTD mode and proceed.
+
+---
+
+## Use generated types only (important)
+
+- Do **not** define ad-hoc or duplicate test models.
+- For table-shaped rows, always import types from:
+  - `tests/generated/ztd-row-map.generated.ts`
+- For application-facing return values:
+  - Use DTO or domain model types already defined in `src/`.
+
+Forbidden example:
+
+```typescript
+type CategoryTestRow = {
+  category_id: number;
+  parent_id: number | null;
+  name: string;
+};
+```
+
+If a required type is missing:
+- Regenerate generated artifacts (`npx ztd ztd-config`), or
+- Export the correct type from `src/`.
+
+Do not invent substitute models.
+
+---
+
+## Stateless test design (important)
+
+- ZTD tests are **stateless by design**.
+- Do not write tests that depend on state accumulating across multiple repository calls.
+
+Forbidden patterns include:
+- Updating the same record in multiple steps and verifying later state
+- Calling multiple repository methods assuming earlier calls affected the database
+
+Preferred patterns:
+- Verify results returned by a single statement
+- Verify `RETURNING` values
+- Verify affected row counts
+- Verify query output produced by the same call being tested
+
+If behavior depends on transactions, isolation, or shared mutable state:
+- That test does not belong in ZTD unit tests.
+- Move it to an integration test and explicitly request Traditional mode.
+
+---
+
+## Fixtures (important)
+
+- Fixtures originate from `ztd/ddl/`.
+- Keep fixtures minimal and intention-revealing.
+- Do not add rows or columns unrelated to the test intent.
+- Do not simulate application-side logic in fixtures.
+
+---
+
+## Assertions (important)
+
+- Assert only on relevant fields.
+- Do not assert implicit ordering.
+- Do not assert specific values of auto-generated IDs.
+- Assert existence, type, or relative differences instead.
+
+---
+
+## Repository boundaries
+
+- Tests should verify observable behavior of repository methods.
+- Do not duplicate SQL logic or business rules inside tests.
+- Do not test internal helper functions or private implementation details.
+
+---
+
+## Edit boundaries
+
+- Tests are shared ownership: humans and AI may both edit.
+- However:
+  - Do not redefine models.
+  - Do not change schema assumptions.
+  - Do not edit `ztd/ddl`, `ztd/domain-specs`, or `ztd/enums` from tests.
+
+---
+
+## Conflict resolution
+
+- If test requirements conflict with ZTD constraints:
+  - Stop and ask for clarification.
+  - Do not silently switch modes or weaken assertions.
+
+---
+
+## Guiding principle
+
+ZTD tests exist to validate **SQL semantics in isolation**.
+They are not integration tests, migration tests, or transaction tests.
+
+Prefer:
+- Clear intent
+- Single observation point
+- Deterministic outcomes

package/templates/ztd/AGENTS.md

@@ -1,103 +1,149 @@
 # AGENTS: Zero Table Dependency Definitions
 
+This file defines **protected, human-led domains** under the `ztd/` directory.
+AI must treat these directories as authoritative sources of truth and must not modify them without explicit instruction.
+
+---
+
 ## Generated files (important)
 
 - `tests/generated/` is auto-generated and must never be committed.
 - After cloning the repository (or in a clean environment), run `npx ztd ztd-config`.
 - If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`.
 
-## DDL Specifications
+---
 
-You are an AI assistant responsible for reading and respecting the contents of this /ztd/ddl directory.
+## DDL Specifications (`ztd/ddl/`)
+
+You are an AI assistant responsible for **reading and respecting** the contents of this directory.
 
 ### Purpose
 
-This directory contains all canonical definitions of database structure, including CREATE TABLE, ALTER TABLE, constraints, and indexes. It is considered the **single source of truth** for database schema as interpreted by the ztd-cli.
+This directory contains all canonical definitions of database structure, including:
 
-### Behavior Rules
+- CREATE TABLE
+- ALTER TABLE
+- Constraints
+- Indexes
 
-- **Never modify files in this folder unless explicitly instructed by a human.**
-- You may propose edits, reviews, or new DDL structures when asked, but you must preserve all human-authored structure, naming, and intent.
-- All DDL statements **must be semicolon-terminated** and valid PostgreSQL syntax.
-- You must not reorder statements arbitrarily; semantic meaning and dependency order must be preserved.
-- Respect formatting conventions, identifier styles, and comments written by humans.
-- When generating new tables or columns, infer types and constraints based on other schema examples or enums (if available).
-- Maintain consistency in column ordering, naming style, and constraint patterns.
-- When adding to existing definitions, do not remove human-authored comments unless told to.
-- Do not introduce structural changes that conflict with domain-specs or enums.
+It is the **single source of truth** for the physical database schema as interpreted by ztd-cli.
 
-### Interaction with Other Sources
+### Behavior Rules (strict)
 
-- Refer to /ztd/domain-specs for domain logic and behavioral definitions. These dictate *what* should exist in the schema.
-- Refer to /ztd/enums for allowable value sets when defining enum-like columns or constraints.
-- Always use those definitions as context when writing or editing this schema.
+- **Never modify files in this directory unless explicitly instructed by a human.**
+- Do not apply “helpful” refactors, cleanups, or formatting changes on your own.
+- You may propose edits or review changes when asked, but you must not apply them without approval.
+- All DDL statements must be:
+  - Valid PostgreSQL syntax
+  - Explicitly semicolon-terminated
+- Do not reorder statements; dependency and execution order matters.
+- Preserve all human-authored:
+  - Naming
+  - Formatting
+  - Comments
+  - Structural intent
+- When asked to extend existing definitions:
+  - Do not remove or rewrite existing columns or comments unless explicitly told.
+  - Maintain column order and constraint style.
+- Do not introduce schema changes that conflict with:
+  - `ztd/domain-specs`
+  - `ztd/enums`
 
-If uncertain, defer to human authorship and request clarification.
+If there is uncertainty, stop and request clarification instead of guessing.
 
-## Domain Specifications
+---
 
-You are an AI agent reading this directory to interpret domain logic.
+## Domain Specifications (`ztd/domain-specs/`)
 
-### Instructions
+You are an AI agent that **reads** domain specifications to understand business semantics.
+
+### Purpose
+
+Each file in this directory defines **one domain behavior**.
+These files explain *what the data means*, not how the application is implemented.
 
-- Treat each Markdown file as defining **one domain behavior**.
-- Use the embedded SQL block (`sql ... `) as the **reference SELECT**.
-- Only the first top-level SELECT block should be considered executable logic.
-- Parameters may be written in :named format (e.g., :as_of). You must bind them as positional placeholders (e.g., $1, $2, ?) in generated code.
-- Do not generate or modify files in this directory unless explicitly asked.
+### Instructions
 
-### Assumptions
+- Treat each Markdown file as defining exactly **one behavior**.
+- Use the embedded SQL block as the **reference SELECT**.
+- Only the first top-level SQL block is executable logic.
+- Parameters may be written as `:named` placeholders.
+  - When generating executable SQL, bind them as positional placeholders (`$1`, `$2`, `?`).
+- **Never modify files in this directory unless explicitly instructed.**
 
-- `ztd-config` parses only DDL (`ztd/ddl/**/*.sql`) to generate row shapes.
-- These specifications are for **humans and AI consumption** (documentation + reference SQL).
-- Comments and descriptions exist to help you interpret logic correctly.
+### Rules (strict)
 
-### Rules
+- Never ignore the human-written explanation above the SQL block.
+- Keep exactly one executable SQL block per file.
+- Do not reorder, optimize, or “simplify” SQL unless explicitly instructed.
+- Preserve the exact semantics described by humans.
+- This directory defines **what is correct behavior**.
+  - Your role is to reproduce that behavior elsewhere (`src/`, `tests/`), not reinterpret it.
 
-- Never ignore the human-written description above the SQL block.
-- Keep exactly one executable SQL block per file (one file = one behavior).
-- Do not reorder or optimize the SQL unless explicitly instructed.
-- Preserve the semantic meaning as given in the specification.
-- This folder defines **what** logic means. Your job is to reproduce that logic elsewhere (e.g., in src/ or tests).
+If meaning is ambiguous, defer to human judgment and ask.
 
-If in doubt, ask for clarification or defer to human judgment.
+---
 
-## Domain Enums
+## Domain Enums (`ztd/enums/`)
 
-You are an AI assistant responsible for reading domain enum definitions from this folder.
+You are an AI assistant responsible for **reading and using** domain enum definitions.
 
 ### Purpose
 
-This directory defines canonical value sets (enums) such as status codes and plan tiers. These definitions inform your code generation logic, constraint enforcement, and vocabulary use.
+This directory defines canonical value sets such as:
+
+- Status codes
+- Category types
+- Plan tiers
 
-### Behavior Guidelines
+These enums are the **only allowed vocabulary** for such concepts.
 
-- Read from the Markdown file containing SQL select ... from (values ...) blocks.
-- Never invent magic numbers or enum values. Always use those explicitly defined here.
-- Do not modify or append new enums unless explicitly instructed by a human.
+### Behavior Guidelines (strict)
+
+- Never invent enum values.
+- Never hardcode magic numbers or strings.
+- Never modify or add enum definitions unless explicitly instructed by a human.
 
 ### SQL Rules
 
-- Each SQL block defines an enum set.
-- Keep exactly one executable SQL block per file (one file = one enum set).
-- All blocks follow the form:
+- Each file contains exactly one executable SQL block.
+- Enum definitions follow this canonical pattern:
 
-`sql
+```sql
 select v.*
 from (
   values
     (1, 'some_code', 'some_label')
 ) v(key, value, display_name);
-`
+```
 
-- You must extract key and value pairs as the authoritative mapping.
-- display_name, 
-ranking, or other metadata may be used where helpful (e.g., UI rendering or sorting).
+- `key` and `value` are authoritative.
+- Additional columns (e.g. `display_name`, `ranking`) may be used for:
+  - UI display
+  - Sorting
+  - Documentation
 
 ### Use in Code Generation
 
-- Use these enums when generating SQL WHERE clauses, conditionals, or constants.
-- When translating logic from /ztd/domain-specs, map references like :status__established to corresponding values here.
-- Maintain full consistency with enum names and intent.
+- Always reference enums when generating:
+  - SQL WHERE conditions
+  - Constants
+  - Conditional logic
+- When translating logic from `ztd/domain-specs`, resolve enum references through this directory.
+- Maintain full consistency with naming and intent.
+
+If a required enum does not exist, stop and ask for human clarification.
+
+---
+
+## Absolute Restrictions (important)
+
+- AI must not modify anything under `ztd/` by default.
+- DDL, domain-specs, and enums are **human-led artifacts**.
+- AI may assist by:
+  - Reading
+  - Explaining
+  - Proposing diffs
+- AI may apply changes **only** with explicit instruction.
 
-If a required enum is missing, raise an error or ask for human clarification.
+Violation of these rules leads to silent corruption of domain meaning and is unacceptable.