@rawsql-ts/ztd-cli 0.14.4 → 0.16.0

package/templates/ztd/AGENTS.md

@@ -1,7 +1,8 @@
-# AGENTS: Zero Table Dependency Definitions
+# 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.
+These rules govern the `ztd/` contents after project initialization and apply regardless of mapper, writer, or runtime architecture decisions.
 
 ---
 
@@ -10,6 +11,7 @@ AI must treat these directories as authoritative sources of truth and must not m
 - `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`.
+- Generated artifacts exist solely to support validation and testing and MUST NEVER influence definitions under `ztd/`.
 
 ---
 
@@ -45,105 +47,28 @@ It is the **single source of truth** for the physical database schema as interpr
 - 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`
+  - Do not introduce schema changes that conflict with existing constraints or indexes.
+- The `public.user_account` and `public.user_profile` tables exist to support the mapper/writer sample; any modification to those tables is a maintenance obligation that requires concurrent updates to `src/repositories/user-accounts.ts` and `tests/writer-constraints.test.ts` so the workflow keeps functioning.
+- DDL defines physical truth only and MUST NEVER be reshaped to accommodate mapper, writer, or test tooling.
+- Runtime convenience is never a valid reason to alter DDL.
 
 If there is uncertainty, stop and request clarification instead of guessing.
 
 ---
 
-## Domain Specifications (`ztd/domain-specs/`)
-
-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.
-
-### Instructions
-
-- 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.**
-
-### Rules (strict)
-
-- 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.
-
-If meaning is ambiguous, defer to human judgment and ask.
-
----
-
-## Domain Enums (`ztd/enums/`)
-
-You are an AI assistant responsible for **reading and using** domain enum definitions.
-
-### Purpose
-
-This directory defines canonical value sets such as:
-
-- Status codes
-- Category types
-- Plan tiers
-
-These enums are the **only allowed vocabulary** for such concepts.
-
-### 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 file contains exactly one executable SQL block.
-- Enum definitions follow this canonical pattern:
-
-```sql
-select v.*
-from (
-  values
-    (1, 'some_code', 'some_label')
-) v(key, value, display_name);
-```
-
-- `key` and `value` are authoritative.
-- Additional columns (e.g. `display_name`, `ranking`) may be used for:
-  - UI display
-  - Sorting
-  - Documentation
-
-### Use in Code Generation
-
-- 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.
+- Only `ztd/ddl` is part of the canonical `ztd` contract; do not create or assume additional subdirectories without explicit human direction.
 
 ---
 
 ## Absolute Restrictions (important)
 
 - AI must not modify anything under `ztd/` by default.
-- DDL, domain-specs, and enums are **human-led artifacts**.
+- DDL is the only **human-led artifact** in this directory.
 - AI may assist by:
   - Reading
   - Explaining
   - Proposing diffs
 - AI may apply changes **only** with explicit instruction.
+- No tooling limitation, test strategy, or runtime design justifies modifying `ztd/` artifacts.
 
 Violation of these rules leads to silent corruption of domain meaning and is unacceptable.

package/templates/ztd/README.md

@@ -1,84 +1,15 @@
-# ZTD Definitions
+# ZTD Definitions
 
-This directory hosts the schema, domain-spec, and enum definitions that feed native ZTD workflows.
+This directory hosts the schema definitions under `ztd/ddl/`. Every DDL file in that folder is the single source of truth for database objects; parser tools and tests read these files to learn table structures, columns, indexes, and constraints.
 
-## DDL Definitions
+## DDL Guidelines
 
-The ztd/ddl/ directory stores **Data Definition Language (DDL)** files that describe the database schema. These files include CREATE TABLE, ALTER TABLE, index declarations, and constraint definitions. ZTD treats the SQL files here as the single source of truth for schemas, so both humans and AI must reference this directory when evolving the structure.
+- Place every schema definition under `ztd/ddl/` with valid PostgreSQL and semicolon-terminated statements.
+- Keep the files deterministic: avoid generated output, enforce column ordering, and document any non-obvious constraints with comments.
+- When you rename or drop a column, update the corresponding DDL file rather than trying to patch test artifacts manually.
+- Treat `ztd/ddl/` as a human-maintained catalog; AI may assist but must not invent or diverge from the files stored there.
 
-### Allowed Content and Structure
+## Workflow expectations
 
-- **Schema Definition Files:** Core table structures live in ztd/ddl/ using CREATE TABLE statements, but you may also add related DDL such as ALTER TABLE commands or explicit index declarations that contribute to the schema contract.
-- **Semantic Flexibility:** The directory supports multiple ways to describe schema changes (e.g., altering tables inline or via subsequent ALTER TABLE statements). The key is clarity and correctness so the CLI tooling can interpret the intended shape.
-
-### File Format and Execution
-
-- **Executable SQL Scripts:** Every file should be valid PostgreSQL with semicolon-terminated statements and a consistent dependency ordering.
-- **Integration with ZTD CLI:** The CLI parses these files to understand schema shapes. Treat this directory as authoritative: every schema change should be captured here as if it were applied to a clean database.
-
-### Maintenance Guidelines
-
-- **Human-Maintained Schema:** Developers own the schema structure; AI tooling may only assist with targeted edits.
-- **Conventions:** Follow the established naming, formatting, and typing patterns. Include comments to explain non-obvious schema choices.
-
-### Relationships
-
-- /ztd/domain-specs: Translates schema structures into behavioral expectations.
-- /ztd/enums: Provides the enum sets referenced by constraints or column defaults.
-
-## Domain Specifications
-
-The ztd/domain-specs/ directory documents key domain behaviors as human-readable specifications.
-
-### Purpose
-
-Each Markdown file describes one business concept, explains it in natural language, and pairs it with an example SELECT query inside a fenced SQL block. These specifications help AI agents understand **what** the domain logic should do without prescribing implementation details.
-
-### Format and Best Practices
-
-- One file per concept with a prose explanation followed by an example SELECT.
-- Keep exactly one executable SQL block per file (one file = one behavior).
-- Named parameters (e.g., :as_of) signal intent; you may translate them into positional placeholders when generating code.
-- Focus on semantics—use Markdown structuring (tables, bullets, etc.) to clarify the behavior.
-- Always update the description before touching the SQL when the behavior evolves.
-
-### Relationships
-
-- /ztd/ddl: Supplies the physical schema that backs the behavior.
-- /ztd/enums: Provides the vocabularies referenced in the domain logic.
-
-## Domain Enums
-
-The ztd/enums/ directory contains enumerated value sets such as statuses, tiers, or lifecycle states.
-
-### Purpose
-
-These enums are human-maintained and support:
-
-- AI-assisted SQL/code generation
-- TypeScript constant generation
-- Schema enforcement (e.g., CHECK constraints)
-- Frontend label rendering via display names
-
-### Format and Structure
-
-- The folder uses Markdown to keep the definitions readable.
-- Each enum is documented in a single file using SELECT ... FROM (VALUES ...) blocks with explicit column aliases.
-
-### Required Structure
-
-- Each row must include at least key and value columns.
-- Optional metadata like display_name, 
-ranking, or sort_order may be added for UI/logic purposes.
-
-### Guidelines
-
-- Keep naming conventions consistent and avoid duplicate value identifiers across unrelated enums.
-- Ensure compatibility with /ztd/domain-specs and /ztd/ddl when expanding enums.
-- Preserve human-readable display_name values as needed for front-end contexts.
-
-### Relationships
-
-- /ztd/ddl: Referenced by constraints or lookup tables.
-- /ztd/domain-specs: Provides the vocabulary for behavioral rules.
-- src/: Maps enums to generated constants or query logic.
+- Regenerate `tests/generated/ztd-row-map.generated.ts` via `npx ztd ztd-config` whenever the DDL changes.
+- Do not assume any other subdirectories under `/ztd` exist unless a human has explicitly created them for a specific purpose.