@polymorphism-tech/morph-spec 8.44.0 → 8.46.0

package/framework/templates/code/dotnet/feature/request.cs.hbs

@@ -1,4 +1,4 @@
-namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
-
-// TODO: Add properties matching the {{pascalCase SLICE_NAME}} command
-public sealed record {{pascalCase SLICE_NAME}}Request();
+namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
+
+// TODO: Add properties matching the {{pascalCase SLICE_NAME}} command
+public sealed record {{pascalCase SLICE_NAME}}Request();

package/framework/templates/code/dotnet/feature/response.cs.hbs

@@ -1,4 +1,4 @@
-namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
-
-// TODO: Add properties matching the {{pascalCase SLICE_NAME}} response
-public sealed record {{pascalCase SLICE_NAME}}Response(Guid Id);
+namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
+
+// TODO: Add properties matching the {{pascalCase SLICE_NAME}} response
+public sealed record {{pascalCase SLICE_NAME}}Response(Guid Id);

package/framework/templates/code/sql/ai-agents/pgvector-embeddings-migration.sql.template

@@ -1,91 +1,91 @@
--- TEMPLATE: pgvector-embeddings-migration.sql
--- PURPOSE: Creates the kb_embeddings table for custom RAG — chunk storage with pgvector.
--- READS STANDARD: ai-agents-rag-custom-pgvector
--- PLACEHOLDERS:
---   {{SCHEMA}}  — target schema (default: public)
--- LAST-VERIFIED: 2026-05-19
---
--- PREREQUISITES:
---   - pgvector extension enabled in Neon (see infrastructure-neon-pgvector).
---   - NpgsqlDataSourceBuilder.UseVector() called in the project's DB setup.
---
--- DIMENSION NOTE:
---   embedding vector(1536) matches text-embedding-3-small (default 1536 dimensions).
---   If the project uses a different embedding model, adjust the dimension to match.
---   NEVER mix embedding models on a single column — vectors live in different spaces.
-
--- ============================================================
--- 1. EXTENSION
--- ============================================================
-
-CREATE EXTENSION IF NOT EXISTS vector;
-
--- ============================================================
--- 2. TABLE
--- ============================================================
-
-CREATE TABLE {{SCHEMA}}.kb_embeddings (
-    id          uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id   uuid         NOT NULL,
-    source      text         NOT NULL,   -- document identifier or source URL
-    chunk_index int          NOT NULL,   -- position of this chunk within the source document
-    content     text         NOT NULL,   -- chunk text returned to the agent as context
-    embedding   vector(1536) NOT NULL,   -- vector dimension must match embedding model
-    metadata    jsonb        NOT NULL DEFAULT '{}',
-    created_at  timestamptz  NOT NULL DEFAULT now()
-);
-
-COMMENT ON TABLE  {{SCHEMA}}.kb_embeddings               IS 'RAG knowledge base — chunk text and pgvector embeddings for semantic search.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.tenant_id     IS 'Tenant partition. Every query MUST filter on this column. Never query across tenants.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.source        IS 'Document identifier or URL. Used for citation and re-indexing detection.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.chunk_index   IS 'Zero-based position of this chunk within the source document.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.content       IS 'Chunk text returned to the agent. Plain text, no markup.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.embedding     IS 'Float vector. Dimension MUST match the embedding model declared in model-registry.json.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.metadata      IS 'Arbitrary JSON metadata (section headers, page numbers, doc type, etc.). Used for filtering.';
-
--- ============================================================
--- 3. INDEXES
--- ============================================================
-
--- HNSW index for cosine similarity — production-grade recall, no training data required.
--- vector_cosine_ops: use <=> operator (cosine distance, ascending = most similar first).
--- m=16, ef_construction=64 are pgvector defaults. Tune per infrastructure-neon-pgvector §HNSW Parameters.
-CREATE INDEX ix_kb_embeddings_hnsw
-    ON {{SCHEMA}}.kb_embeddings
-    USING hnsw (embedding vector_cosine_ops)
-    WITH (m = 16, ef_construction = 64);
-
--- Index for the mandatory tenant_id filter (applied in every search query).
-CREATE INDEX ix_kb_embeddings_tenant
-    ON {{SCHEMA}}.kb_embeddings (tenant_id);
-
--- Composite index for source-level operations (re-indexing, deletion by document).
-CREATE INDEX ix_kb_embeddings_source
-    ON {{SCHEMA}}.kb_embeddings (tenant_id, source);
-
--- ============================================================
--- 4. ROW-LEVEL SECURITY (multi-tenant)
--- ============================================================
-
--- RLS enforces tenant isolation at the database level as a second line of defence.
--- The application already filters on tenant_id in every query; RLS is the backstop.
---
--- See templates/code/sql/postgresql-rls-policy.sql for the policy pattern that
--- binds app.current_tenant_id (a session-level setting) to the RLS policy.
---
--- Uncomment and adapt once RLS is wired in the project:
---
--- ALTER TABLE {{SCHEMA}}.kb_embeddings ENABLE ROW LEVEL SECURITY;
---
--- CREATE POLICY kb_embeddings_tenant_isolation
---     ON {{SCHEMA}}.kb_embeddings
---     USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
-
--- ============================================================
--- ROLLBACK
--- ============================================================
-
--- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_hnsw;
--- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_tenant;
--- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_source;
--- DROP TABLE IF EXISTS {{SCHEMA}}.kb_embeddings CASCADE;
+-- TEMPLATE: pgvector-embeddings-migration.sql
+-- PURPOSE: Creates the kb_embeddings table for custom RAG — chunk storage with pgvector.
+-- READS STANDARD: ai-agents-rag-custom-pgvector
+-- PLACEHOLDERS:
+--   {{SCHEMA}}  — target schema (default: public)
+-- LAST-VERIFIED: 2026-05-19
+--
+-- PREREQUISITES:
+--   - pgvector extension enabled in Neon (see infrastructure-neon-pgvector).
+--   - NpgsqlDataSourceBuilder.UseVector() called in the project's DB setup.
+--
+-- DIMENSION NOTE:
+--   embedding vector(1536) matches text-embedding-3-small (default 1536 dimensions).
+--   If the project uses a different embedding model, adjust the dimension to match.
+--   NEVER mix embedding models on a single column — vectors live in different spaces.
+
+-- ============================================================
+-- 1. EXTENSION
+-- ============================================================
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- ============================================================
+-- 2. TABLE
+-- ============================================================
+
+CREATE TABLE {{SCHEMA}}.kb_embeddings (
+    id          uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id   uuid         NOT NULL,
+    source      text         NOT NULL,   -- document identifier or source URL
+    chunk_index int          NOT NULL,   -- position of this chunk within the source document
+    content     text         NOT NULL,   -- chunk text returned to the agent as context
+    embedding   vector(1536) NOT NULL,   -- vector dimension must match embedding model
+    metadata    jsonb        NOT NULL DEFAULT '{}',
+    created_at  timestamptz  NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE  {{SCHEMA}}.kb_embeddings               IS 'RAG knowledge base — chunk text and pgvector embeddings for semantic search.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.tenant_id     IS 'Tenant partition. Every query MUST filter on this column. Never query across tenants.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.source        IS 'Document identifier or URL. Used for citation and re-indexing detection.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.chunk_index   IS 'Zero-based position of this chunk within the source document.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.content       IS 'Chunk text returned to the agent. Plain text, no markup.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.embedding     IS 'Float vector. Dimension MUST match the embedding model declared in model-registry.json.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.metadata      IS 'Arbitrary JSON metadata (section headers, page numbers, doc type, etc.). Used for filtering.';
+
+-- ============================================================
+-- 3. INDEXES
+-- ============================================================
+
+-- HNSW index for cosine similarity — production-grade recall, no training data required.
+-- vector_cosine_ops: use <=> operator (cosine distance, ascending = most similar first).
+-- m=16, ef_construction=64 are pgvector defaults. Tune per infrastructure-neon-pgvector §HNSW Parameters.
+CREATE INDEX ix_kb_embeddings_hnsw
+    ON {{SCHEMA}}.kb_embeddings
+    USING hnsw (embedding vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64);
+
+-- Index for the mandatory tenant_id filter (applied in every search query).
+CREATE INDEX ix_kb_embeddings_tenant
+    ON {{SCHEMA}}.kb_embeddings (tenant_id);
+
+-- Composite index for source-level operations (re-indexing, deletion by document).
+CREATE INDEX ix_kb_embeddings_source
+    ON {{SCHEMA}}.kb_embeddings (tenant_id, source);
+
+-- ============================================================
+-- 4. ROW-LEVEL SECURITY (multi-tenant)
+-- ============================================================
+
+-- RLS enforces tenant isolation at the database level as a second line of defence.
+-- The application already filters on tenant_id in every query; RLS is the backstop.
+--
+-- See templates/code/sql/postgresql-rls-policy.sql for the policy pattern that
+-- binds app.current_tenant_id (a session-level setting) to the RLS policy.
+--
+-- Uncomment and adapt once RLS is wired in the project:
+--
+-- ALTER TABLE {{SCHEMA}}.kb_embeddings ENABLE ROW LEVEL SECURITY;
+--
+-- CREATE POLICY kb_embeddings_tenant_isolation
+--     ON {{SCHEMA}}.kb_embeddings
+--     USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
+
+-- ============================================================
+-- ROLLBACK
+-- ============================================================
+
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_hnsw;
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_tenant;
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_source;
+-- DROP TABLE IF EXISTS {{SCHEMA}}.kb_embeddings CASCADE;

package/framework/templates/docs/spec.md

@@ -3,206 +3,33 @@
 | Field | Value |
 |-------|-------|
 | **ID** | {{FEATURE_NAME}} |
-| **Status** | Draft / In Review / Approved / In Progress / Done |
 | **Created** | {{DATE}} |
 | **Stack** | {{STACK}} |
-| **Complexity** | Low / Medium / High |
-| **Estimated Cost** | $X/month |
-| **Agents** | Core: All / Specialists: {list} |
 
----
+> Behavior lives in the use cases (`2-plan/usecases/UC-*.md`). This file says HOW they are realized —
+> do not repeat postconditions here.
 
-## Overview
+## Architecture
 
-**Problem:** {What problem this feature solves}
-
-**Solution:** {High-level solution}
-
-**Success Criteria:**
-- [ ] {Criterion 1}
-- [ ] {Criterion 2}
-
----
-
-## Requirements
-
-**Functional:** FR1: {desc} | FR2: {desc} | FR3: {desc}
-
-**Non-Functional:** NFR1: Performance - {target} | NFR2: Reliability - {target}
-
----
-
-## User Stories
-
-### US001: {Title}
-**As** {user type} **I want** {feature} **so that** {benefit}
-
-**Acceptance Criteria:** 1. {criterion} 2. {criterion}
-
-**Edge Cases:** {edge case}: {handling}
-
----
-
-## Technical Architecture
-
-### Stack
-| Component | Technology |
-|-----------|------------|
-| Frontend | {Next.js / .NET 10} |
-| Backend | .NET 10 / C# 14 |
-| Database | {Azure SQL / Cosmos DB} |
+{Components, how they connect, main data flows. Enough to implement without basic questions.}
 
 ### Data Model
 
-#### {EntityName}
-| Column | Type | Constraints |
-|--------|------|-------------|
-| Id | Guid | PK |
-| {Property} | {Type} | {Constraints} |
-| CreatedAt | datetime2 | Default: GETUTCDATE() |
+| Entity | Field | Type | Notes |
+|--------|-------|------|-------|
+| {Entity} | {field} | {type} | {constraint, index, relation} |
 
 ### Contracts
 
-```csharp
-public interface I{{pascalCase FEATURE_NAME}}Service
-{
-    Task<{{pascalCase FEATURE_NAME}}Dto> GetByIdAsync(int id);
-    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request);
-}
-```
-
-**Contracts Workflow:** Generate `contracts.cs` FIRST → validate names → reference in spec → approve with user.
-
-**Validation Checklist:**
-- [ ] Property names are descriptive (not generic "Data", "Value")
-- [ ] Records use correct types (Stream vs byte[], Guid vs string)
-- [ ] Response DTOs have all properties needed for UI
-- [ ] Request DTOs have implicit validations (required, nullable)
-
----
-
-## Domain Complexity
-
-**Nível:** {1 — CRUD / 2 — Business Logic / 3 — Bounded Context}
-
-**Justificativa:** {Por que este nível foi escolhido — mencionar invariants, eventos ou BCs se Nível 2+}
-
-**Padrões Aplicados:**
-- {Nível 1: Entity simples, Service CRUD, DTOs}
-- {Nível 2: AggregateRoot, Value Objects, Domain Events, CQRS}
-- {Nível 3: Bounded Context isolation, cross-BC events, Linguagem Ubíqua}
-
-**Padrões Omitidos:**
-- {ex: Bounded Contexts — sistema single-domain}
-
----
-
-## Architecture Style: Vertical Slice
-
-> Preencher SOMENTE se `config.architecture.style === "vertical-slice"`. Omitir em projetos DDD.
-
-**Architecture Style:** Vertical Slice Architecture (VSA)
-
-**Entity Fields:**
-| Field | Type | Constraints |
-|-------|------|-------------|
-| Id | Guid | PK, `Guid.CreateVersion7()` |
-| {Field} | {C# Type} | {Required / Optional / Unique} |
-| CreatedAt | DateTimeOffset | Auto |
-
-**Operations:**
-| Slice | HTTP | Route | Has Validator |
-|-------|------|-------|---------------|
-| Create{Entity} | POST | {ROUTE} | Yes |
-| GetAll{Entity}s | GET | {ROUTE} | No |
-| Get{Entity}ById | GET | {ROUTE}/{id} | Yes |
-| Update{Entity} | PUT | {ROUTE}/{id} | Yes |
-| Delete{Entity} | DELETE | {ROUTE}/{id} | Yes |
-
-**Error Types ({Entity}Errors):**
-- `{Entity}Errors.{ErrorName}()` — {description}
-
-**Validation Rules:**
-| Field | Rules |
-|-------|-------|
-| {Field} | NotEmpty(), MaxLength({N}), {etc.} |
-
----
-
-## Aggregate Blueprint (Nível 2+ apenas)
-
-> Omitir esta seção se Nível 1 (CRUD) ou se Architecture Style = Vertical Slice.
-
-### Aggregate Root: {EntityName}
-
-**Invariants:**
-- {Invariant 1 em linguagem natural}
-- {Invariant 2}
-
-**Estados e Transições:**
 ```
-{Status.Draft} → Confirm() → {Status.Confirmed} → Cancel() → {Status.Cancelled}
+{METHOD} /api/{route}
+Request:  { ... }
+Response: { ... }  |  ProblemDetails 400/404/409
 ```
 
-**Domain Events:**
-- `{EntityName}CreatedEvent` — publicado ao criar
-- `{EntityName}StatusChangedEvent` — publicado em mudança de estado
-
-**Value Objects:**
-- `{ValueObjectName}` — {por que não é primitivo simples}
-
-**Referências Cross-Aggregate (por ID):**
-- `{OtherEntity}Id: Guid`
-
-### Linguagem Ubíqua
-
-| Termo | Definição | Código |
-|-------|-----------|--------|
-| {Termo} | {Definição do negócio} | `{ClassName.MethodName()}` |
-
----
-
-## UI/UX Design (if front-end)
-
-### Wireframes
-```
-{ASCII wireframe per screen - include states: loading, error, empty}
-```
+## Technical edge cases
 
-### User Flow
-1. {Step} → {System response}
-
----
-
-## Flows
-
-### {Flow Name}
-**Trigger:** {what starts this flow}
-1. {Actor} {action} → {system response}
-2. If {condition}: Path A / Else: Path B
-**End State:** {final state}
-
----
-
-## Cost Estimate
-
-| Resource | SKU | Monthly Cost | Justification |
-|----------|-----|--------------|---------------|
-| {Resource} | {SKU} | ${X} | {Why} |
-| **Total** | | **${X}/month** | |
-
----
-
-## ADRs (Architectural Decision Records)
-
-### ADR-001: {Decision Title}
-**Status:** Proposed / Accepted
-**Context:** {Why decide now}
-**Decision:** {What we chose}
-**Alternatives:** 1. {Alt} (pros/cons) 2. {Alt} (pros/cons)
-**Trade-offs:** {key trade-offs}
-
----
+- {Edge case} → {how it is handled}
 
 ## UCs e ADRs que esta feature altera ou revoga
 
@@ -217,27 +44,14 @@ public interface I{{pascalCase FEATURE_NAME}}Service
 | UC-{nn} | parcial | UC-{nn} | {where the old one still holds} |
 | {feature}/ADR-{nnn} | total | — | — |
 
----
-
-## Security
-
-| Action | Required Policy |
-|--------|-----------------|
-| View | CanView{Feature} |
-| Create | CanManage{Feature} |
+## Contrato de implementação
 
-## Risks
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| {Risk} | {H/M/L} | {Mitigation} |
+- **Standards:** {ids from `morph-spec standards --find`, plus `architecture-code-comments` and the stack's test standard}
+- **Proibições desta feature:** {beyond MORPH.md "Stack baked-in", or "nenhuma"}
+- **Verificação de runtime:** {how the stack comes up (`morph-spec e2e up {feature}`), which flows the evaluator navigates, which become Playwright specs, auth setup — or why it does not apply}
+- **Baseline:** {the COMMAND that measures it — `dotnet test`, `npm test` — never a number}
+- **Pré-requisito:** {a PREDICATE — `git merge-base --is-ancestor origin/main HEAD` exits 0 — never a SHA}
 
 ## Out of Scope
-- {Item}
 
-## Definition of Done
-- [ ] Code implemented
-- [ ] Tests >80% coverage
-- [ ] Code review approved
-- [ ] Deploy to staging
-- [ ] Recap.md generated
+- {Item}

package/framework/templates/docs/ui-components.md

@@ -1,52 +1,52 @@
-# UI Components: {{titleCase FEATURE_NAME}}
-
-| Field | Value |
-|-------|-------|
-| **Feature** | {{FEATURE_NAME}} |
-| **Created** | {{DATE}} |
-| **Stack** | {{STACK}} |
-
----
-
-{{#if (eq STACK "nextjs-neon")}}
-## Component Library: shadcn/ui
-
-### C001: Button
-
-```tsx
-import { Button } from '@/components/ui/button';
-
-<Button onClick={handleSave} disabled={!isValid}>
-  Save
-</Button>
-```
-
-### C002: Data Table
-
-```tsx
-import { DataTable } from '@/components/ui/data-table';
-
-<DataTable columns={columns} data={items} />
-```
-
-{{/if}}
-
----
-
-## Form Validation
-
-| Field | Rule | Error Message |
-|-------|------|---------------|
-| **Name** | Required, max 100 | "Name is required" |
-| **Email** | Valid email | "Invalid email" |
-
----
-
-## Accessibility
-- [ ] All inputs have labels
-- [ ] Error messages announced
-- [ ] Keyboard navigation works
-
----
-
-*Generated with MORPH Framework*
+# UI Components: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+| **Stack** | {{STACK}} |
+
+---
+
+{{#if (eq STACK "nextjs-neon")}}
+## Component Library: shadcn/ui
+
+### C001: Button
+
+```tsx
+import { Button } from '@/components/ui/button';
+
+<Button onClick={handleSave} disabled={!isValid}>
+  Save
+</Button>
+```
+
+### C002: Data Table
+
+```tsx
+import { DataTable } from '@/components/ui/data-table';
+
+<DataTable columns={columns} data={items} />
+```
+
+{{/if}}
+
+---
+
+## Form Validation
+
+| Field | Rule | Error Message |
+|-------|------|---------------|
+| **Name** | Required, max 100 | "Name is required" |
+| **Email** | Valid email | "Invalid email" |
+
+---
+
+## Accessibility
+- [ ] All inputs have labels
+- [ ] Error messages announced
+- [ ] Keyboard navigation works
+
+---
+
+*Generated with MORPH Framework*