@polymorphism-tech/morph-spec 4.12.0 → 4.13.0

package/framework/standards/ai-agents/blazor-ui.md

@@ -1,364 +0,0 @@
-# Microsoft Agent Framework - Natural Language First Blazor UI
-
-> **Scope:** blazor-azure
-> **Layer:** 2 (on keyword)
-> **Keywords:** blazor, natural language, ui, llm, voice, ai-first
-> **Load When:** blazor ai-first ui keywords detected
-
-**Ref:** `setup.md` — Core setup | `production.md` — Middleware, tools
-
-Patterns for AI-first user interfaces in Blazor — voice, state-based control, semantic navigation.
-
----
-
-## The Problem
-
-Current AI UIs are "empty text box + button" — users don't know what the app can do. We're in the "pinch and zoom" era of AI interfaces, still discovering what "AI First" means (like early mobile sites before responsive design).
-
-**Solution:** Smart Components + State-Based Control + Natural Language Processing
-
----
-
-## State-Based Control Strategy
-
-Instead of giving the LLM the full DOM, extract component metadata as JSON, let the LLM modify values, apply back.
-
-```
-┌───────────────┐     ┌───────────────┐     ┌───────────────┐
-│  UI Component │ →→→ │  JSON State   │ →→→ │     LLM       │
-│  (Data Grid)  │     │ (sort, filter │     │ (modifies     │
-│               │     │  group, etc.) │     │  values only) │
-└───────────────┘     └───────────────┘     └───────┬───────┘
-                                                     │
-┌───────────────┐                           ┌───────┴───────┐
-│  UI Component │ ←←← Modified JSON  ←←←←← │  JSON Output  │
-│ (state applied)│                           └───────────────┘
-└───────────────┘
-```
-
-### System Prompt
-
-```
-You are a JSON parser. You will use the user's query to modify
-values in JSON format. Only update the values in JSON data.
-Do not modify properties.
-
-JSON Schema:
-{schema}
-
-Current State:
-{currentState}
-
-User Query: {userQuery}
-```
-
-### Key Insight
-
-LLMs treat JSON as a language — they can manipulate, translate, and transform structured data without understanding the underlying UI.
-
----
-
-## Pattern 1: Data Grid Control via Voice
-
-```csharp
-// Extract grid state as JSON
-var gridState = new
-{
-    columns = new[] { "Name", "Amount", "Category", "Date" },
-    sort = new { column = (string?)null, direction = "asc" },
-    filter = new { column = (string?)null, value = (string?)null },
-    groupBy = (string?)null
-};
-
-// Send to agent with user query
-var agent = chatClient.AsAIAgent(
-    instructions: """
-        You modify data grid state based on user commands.
-        Only update values. Return valid JSON.
-        """);
-
-var response = await agent.RunAsync(
-    $"State: {JsonSerializer.Serialize(gridState)}\nQuery: Sort amount descending");
-
-// Parse response and apply to grid component
-var newState = JsonSerializer.Deserialize<GridState>(response.Text);
-```
-
-**Example interactions:**
-
-| User Command | Grid Action |
-|-------------|-------------|
-| "Sort amount descending" | `sort.column = "Amount", sort.direction = "desc"` |
-| "Group by category" | `groupBy = "Category"` |
-| "Show only items over $100" | `filter.column = "Amount", filter.value = ">100"` |
-
----
-
-## Pattern 2: Tool Calling for UI Manipulation
-
-Define granular tools that the agent can call to interact with UI components.
-
-```csharp
-public class FormTools
-{
-    private readonly FormState _formState;
-    private readonly NavigationManager _nav;
-
-    [Description("Updates a specific field in the form")]
-    public void UpdateField(
-        [Description("Field name")] string fieldName,
-        [Description("New value")] string value)
-    {
-        _formState.SetField(fieldName, value);
-    }
-
-    [Description("Clears a specific field (use when bad data received)")]
-    public void ClearField([Description("Field name")] string fieldName)
-    {
-        _formState.ClearField(fieldName);
-    }
-
-    [Description("Validates the form and returns validation result")]
-    public string ValidateForm()
-    {
-        var errors = _formState.Validate();
-        return errors.Any()
-            ? $"Errors: {string.Join(", ", errors)}"
-            : "Form is valid";
-    }
-
-    [Description("Submits the form if valid")]
-    public string SubmitForm()
-    {
-        if (!_formState.IsValid) return "Form has errors. Fix them first.";
-        _formState.Submit();
-        return "Form submitted successfully";
-    }
-
-    [Description("Navigates to a specific page")]
-    public void NavigateTo([Description("Page URL")] string url)
-    {
-        _nav.NavigateTo(url);
-    }
-}
-```
-
-**Critical lessons:**
-- Use **granular tools** (e.g., `ClearField` separate from `UpdateField`) — without `ClearField`, the LLM might clear the entire form when receiving bad data
-- Tool **descriptions** determine which tool the LLM picks — be precise
-
-### Register Agent with Form Tools
-
-```csharp
-var formTools = new FormTools(formState, navigationManager);
-
-var agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
-{
-    Name = "FormAssistant",
-    Instructions = """
-        You help users fill out the RMA form.
-        Walk them through fields one by one.
-        Validate inputs before setting them.
-        Use ClearField when receiving invalid data.
-        """,
-    ChatOptions = new ChatOptions
-    {
-        Tools =
-        [
-            AIFunctionFactory.Create(formTools.UpdateField),
-            AIFunctionFactory.Create(formTools.ClearField),
-            AIFunctionFactory.Create(formTools.ValidateForm),
-            AIFunctionFactory.Create(formTools.SubmitForm)
-        ]
-    }
-});
-```
-
----
-
-## Pattern 3: Semantic Navigation
-
-Store routes as embeddings in a vector store — match user intent to pages by meaning, not exact text.
-
-```csharp
-public class NavigationTools
-{
-    private readonly IVectorStore _vectorStore;
-    private readonly NavigationManager _nav;
-
-    [Description("Gets available pages that match a description")]
-    public async Task<string> FindPageAsync(
-        [Description("What the user is looking for")] string description)
-    {
-        var results = await _vectorStore.SearchAsync(description, maxResults: 3);
-        return string.Join("\n", results.Select(r =>
-            $"- {r.Title} ({r.Url}) — Similarity: {r.Score:P0}"));
-    }
-
-    [Description("Navigates to a specific page in the application")]
-    public void NavigateTo([Description("URL to navigate to")] string url)
-    {
-        _nav.NavigateTo(url);
-    }
-}
-```
-
-**Example:** User says "Show me the returns page" → vector search finds `/rma` (Return Merchandise Authorization) even though the words don't match literally.
-
----
-
-## Pattern 4: Voice Integration
-
-Using Azure Speech Services for speech-to-text and text-to-speech:
-
-```csharp
-public class VoiceTools
-{
-    private readonly ITextToSpeechService _tts;
-
-    [Description("Gets available voice options")]
-    public async Task<List<string>> GetVoicesAsync()
-        => await _tts.GetAvailableVoicesAsync();
-
-    [Description("Changes the assistant's voice")]
-    public void SetVoice([Description("Voice name")] string voiceName)
-        => _tts.SetVoice(voiceName);
-}
-```
-
-**Stack:** Microsoft.Extensions.AI + Azure AI Services (Speech)
-
----
-
-## Pattern 5: Intelligent Validation
-
-The LLM understands data types and can validate contextually:
-
-| Input | Expected | LLM Response |
-|-------|----------|--------------|
-| "555 Main Street" | Email field | "That looks like an address. What's your email?" |
-| "I want my money back" | Dropdown (Refund/Replace/Repair) | Maps to "Refund" option |
-| Text in Swedish | English form | Extracts and translates field values automatically |
-
----
-
-## Multilingual Support (Free)
-
-Because the LLM translates between the user's language and the form schema, users can interact in any language without code changes.
-
-```
-User (Swedish): "Mitt namn är Erik och min e-post är erik@test.se"
-→ LLM maps: firstName="Erik", email="erik@test.se"
-→ Form filled in English schema
-```
-
----
-
-## UX Best Practices
-
-| Practice | Why |
-|----------|-----|
-| Suggested prompt buttons | Reduce barrier — users see what's possible |
-| Hybrid input (voice + text + click) | Don't force a single modality |
-| Double validation (LLM + app) | Defense in depth |
-| Progressive disclosure | Start simple, reveal complexity on demand |
-| Feedback on agent actions | Show what the agent changed |
-
----
-
-## Blazor Component Template
-
-```razor
-@page "/ai-form"
-@inject IServiceProvider ServiceProvider
-
-<div class="ai-form-container">
-    <EditForm Model="_formState">
-        @* Standard form fields *@
-        <InputText @bind-Value="_formState.Name" placeholder="Name" />
-        <InputText @bind-Value="_formState.Email" placeholder="Email" />
-        <InputSelect @bind-Value="_formState.RequestType">
-            <option value="">Select...</option>
-            <option value="Refund">Refund</option>
-            <option value="Replace">Replace</option>
-            <option value="Repair">Repair</option>
-        </InputSelect>
-    </EditForm>
-
-    @* AI Assistant Panel *@
-    <div class="ai-assistant">
-        <div class="messages">
-            @foreach (var msg in _messages)
-            {
-                <div class="message @msg.Role">@msg.Text</div>
-            }
-        </div>
-        <input @bind="_userInput" @onkeydown="HandleKeyDown" placeholder="Ask for help..." />
-    </div>
-</div>
-
-@code {
-    private AIAgent _agent = default!;
-    private FormState _formState = new();
-    private List<ChatMessage> _messages = new();
-    private string _userInput = "";
-
-    protected override void OnInitialized()
-    {
-        var chatClient = ServiceProvider.GetRequiredService<IChatClient>();
-        var formTools = new FormTools(_formState, NavigationManager);
-
-        _agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
-        {
-            Name = "FormAssistant",
-            Instructions = "Help fill the RMA form. Walk through fields. Validate inputs.",
-            ChatOptions = new ChatOptions
-            {
-                Tools =
-                [
-                    AIFunctionFactory.Create(formTools.UpdateField),
-                    AIFunctionFactory.Create(formTools.ClearField),
-                    AIFunctionFactory.Create(formTools.ValidateForm),
-                    AIFunctionFactory.Create(formTools.SubmitForm)
-                ]
-            }
-        });
-    }
-
-    private async Task HandleKeyDown(KeyboardEventArgs e)
-    {
-        if (e.Key != "Enter" || string.IsNullOrWhiteSpace(_userInput)) return;
-
-        _messages.Add(new(ChatRole.User, _userInput));
-        var response = await _agent.RunAsync(_userInput);
-        _messages.Add(new(ChatRole.Assistant, response.Text));
-        _userInput = "";
-        StateHasChanged();
-    }
-}
-```
-
----
-
-## Checklist
-
-- [ ] State-based control strategy: UI metadata extracted as JSON
-- [ ] Tool definitions: granular (Update, Clear, Validate, Submit separately)
-- [ ] Tool descriptions: precise and action-oriented
-- [ ] Suggested prompts: buttons showing example interactions
-- [ ] Double validation: LLM validates + app validates
-- [ ] Semantic navigation: routes stored as embeddings (if applicable)
-- [ ] Voice integration: Azure Speech Services (if applicable)
-- [ ] Multilingual: schema stays in one language, LLM translates
-
----
-
-## References
-
-- `.wiki/microsoft-agent-framework/natural-language-first-blazor-ai-user-experience.md`
-- `setup.md` — Core setup
-- `../backend/database/vector-search-rag.md` — Embeddings for semantic navigation
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/architecture/ddd/aggregates.md

@@ -1,120 +0,0 @@
-# Architecture Standard: DDD Aggregates
-
-## Overview
-Aggregates are the primary unit of consistency in DDD. An aggregate root is the only entry point.
-
-## Design Rules
-1. **Small aggregates**: Keep aggregates small (3-5 entities max)
-2. **Reference by ID**: Aggregates reference each other by ID only (not navigation properties across aggregate boundaries)
-3. **Consistency boundary**: All invariants within an aggregate must hold after every command
-4. **Single repository**: One repository per aggregate root
-
-## Aggregate Root Pattern
-```csharp
-public abstract class AggregateRoot : Entity
-{
-    private readonly List<DomainEvent> _domainEvents = [];
-
-    public IReadOnlyList<DomainEvent> DomainEvents => _domainEvents.AsReadOnly();
-
-    protected void RaiseDomainEvent(DomainEvent @event)
-    {
-        @event = @event with { Version = _domainEvents.Count + 1 };
-        _domainEvents.Add(@event);
-    }
-
-    public void ClearDomainEvents() => _domainEvents.Clear();
-}
-
-public abstract class Entity
-{
-    public Guid Id { get; protected set; } = Guid.NewGuid();
-    public DateTime CreatedAt { get; protected set; } = DateTime.UtcNow;
-    public DateTime? UpdatedAt { get; protected set; }
-}
-```
-
-## Order Aggregate Example
-```csharp
-public class Order : AggregateRoot
-{
-    private readonly List<OrderItem> _items = [];
-
-    // Private constructor — use factory method
-    private Order(Guid userId) { UserId = userId; Status = OrderStatus.Draft; }
-
-    public Guid UserId { get; private set; }
-    public OrderStatus Status { get; private set; }
-    public IReadOnlyList<OrderItem> Items => _items.AsReadOnly();
-    public decimal Total => _items.Sum(i => i.Subtotal);
-
-    // Factory method — validates invariants before creating
-    public static Order Create(Guid userId, IEnumerable<OrderItem> items)
-    {
-        if (userId == Guid.Empty) throw new DomainException("UserId required");
-        var order = new Order(userId);
-        foreach (var item in items) order.AddItem(item);
-        order.RaiseDomainEvent(new OrderCreatedEvent(order.Id, userId));
-        return order;
-    }
-
-    public void AddItem(OrderItem item)
-    {
-        if (Status != OrderStatus.Draft)
-            throw new DomainException($"Cannot add items to order in {Status} status");
-
-        var existing = _items.FirstOrDefault(i => i.ProductId == item.ProductId);
-        if (existing != null)
-            existing.IncreaseQuantity(item.Quantity);
-        else
-            _items.Add(item);
-
-        UpdatedAt = DateTime.UtcNow;
-    }
-
-    public void Confirm()
-    {
-        if (Status != OrderStatus.Draft)
-            throw new DomainException("Can only confirm draft orders");
-        if (!_items.Any())
-            throw new DomainException("Order must have at least one item");
-
-        Status = OrderStatus.Confirmed;
-        UpdatedAt = DateTime.UtcNow;
-        RaiseDomainEvent(new OrderConfirmedEvent(Id));
-    }
-}
-```
-
-## Repository Interface (per aggregate root)
-```csharp
-public interface IOrderRepository
-{
-    Task<Order?> GetAsync(Guid id, CancellationToken ct = default);
-    Task AddAsync(Order order, CancellationToken ct = default);
-    Task UpdateAsync(Order order, CancellationToken ct = default);
-}
-```
-
-## EF Core Configuration
-```csharp
-public class OrderConfiguration : IEntityTypeConfiguration<Order>
-{
-    public void Configure(EntityTypeBuilder<Order> builder)
-    {
-        builder.HasKey(o => o.Id);
-        builder.OwnsMany(o => o.Items, items =>
-        {
-            items.ToTable("OrderItems");
-            items.WithOwner().HasForeignKey("OrderId");
-        });
-        builder.Ignore(o => o.DomainEvents); // Not persisted
-    }
-}
-```
-
-## Anti-Patterns
-- Never expose mutable collections: use `IReadOnlyList<>`, never `List<>`
-- Never set state directly from outside: all mutations through aggregate methods
-- Never cross aggregate boundaries in a single transaction
-- Never put query logic in aggregates — use separate read models

package/framework/standards/architecture/ddd/bounded-contexts.md

@@ -1,105 +0,0 @@
-# DDD Bounded Contexts
-
-> **Scope:** universal
-> **Layer:** 2
-> **Keywords:** bounded-context, ddd, domain, context-map, modular-monolith, integration-events
-
-Bounded Context (BC) é a fronteira onde um modelo de domínio tem significado único.
-Use apenas em sistemas com múltiplos domínios distintos (Nível 3 de complexidade).
-
----
-
-## Estrutura de Pastas (Nível 3)
-
-```
-src/{App}.Domain/
-  Billing/
-    Aggregates/
-      Subscription.cs
-      Invoice.cs
-    ValueObjects/
-      PlanTier.cs
-      BillingCycle.cs
-    Events/
-      SubscriptionCreatedEvent.cs
-    Exceptions/
-      SubscriptionNotFoundException.cs
-
-  Orders/
-    Aggregates/
-      Order.cs
-    ValueObjects/
-      Money.cs
-    Events/
-      OrderConfirmedEvent.cs
-
-src/{App}.Application/
-  Billing/
-    Commands/
-      CreateSubscriptionCommand.cs
-    Queries/
-      GetActiveSubscriptionQuery.cs
-    Handlers/
-      CreateSubscriptionHandler.cs
-
-src/{App}.Infrastructure/
-  Billing/
-    Repositories/
-      SubscriptionRepository.cs
-    Configurations/
-      SubscriptionConfiguration.cs
-```
-
----
-
-## Regras de Comunicação Cross-BC
-
-```csharp
-// ✅ CORRETO: referenciar outro BC por ID
-public class Order : AggregateRoot
-{
-    public Guid CustomerId { get; private set; }  // ID, não navigation property
-}
-
-// ✅ CORRETO: comunicação via Integration Events
-public class OrderConfirmedHandler : INotificationHandler<OrderConfirmedIntegrationEvent>
-{
-    public async Task Handle(OrderConfirmedIntegrationEvent notification, CancellationToken ct)
-    {
-        await _billingService.ChargeForOrderAsync(notification.OrderId, ct);
-    }
-}
-
-// ❌ ERRADO: acesso direto ao repositório de outro BC
-public class OrderService
-{
-    private readonly ICustomerRepository _customerRepo; // cross-BC — PROIBIDO
-}
-```
-
----
-
-## Linguagem Ubíqua por BC
-
-O mesmo termo pode ter significados diferentes em BCs distintos:
-
-| Termo | BC: Orders | BC: Support |
-|-------|-----------|-------------|
-| `Customer` | Quem fez pedido, tem `Orders[]` | Quem abriu ticket, tem `SLA` |
-| `Status` | `Draft/Confirmed/Shipped` | `Open/InProgress/Resolved` |
-
-Documente em `1-design/ubiquitous-language.md` por feature.
-
----
-
-## Quando NÃO usar Bounded Contexts
-
-- App single-domain (ex: sistema de agendamentos)
-- MVP ou projeto com um único time
-- Quando os "domínios" compartilham o mesmo modelo sem conflito
-
-Em todos esses casos: use Nível 2 (Aggregates sem BC isolation).
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/architecture/ddd/complexity-levels.md

@@ -1,108 +0,0 @@
-# DDD Complexity Levels
-
-> **Scope:** universal
-> **Layer:** 2
-> **Keywords:** ddd, complexity, aggregate, crud, bounded-context, domain, level
-
-Define o nível de complexidade de domínio para cada feature. O nível determina qual
-template de contracts.cs será usado e quais padrões DDD são mandatórios.
-
----
-
-## Os 3 Níveis
-
-### Nível 1 — CRUD
-
-**Quando usar:**
-- Feature é essencialmente Create/Read/Update/Delete
-- Entidade não tem regras de negócio (apenas validações de campos)
-- Nenhum outro domínio precisa reagir às mudanças desta entidade
-- Exemplos: `Category`, `Tag`, `UserProfile`, `Notification`
-
-**O que gerar:**
-- `Entity` simples (sem AggregateRoot)
-- Service interface CRUD
-- DTOs (record)
-- Repository interface básica
-- **SEM** Domain Events, **SEM** Value Objects obrigatórios, **SEM** CQRS
-
----
-
-### Nível 2 — Business Logic
-
-**Quando usar:**
-- Entidade tem estados com transições controladas por regras (ex: Draft → Confirmed → Shipped)
-- Invariants existem: "só pode cancelar se estiver Ativo"
-- Cálculos derivados (Total, Saldo, Desconto)
-- Outros módulos precisam reagir a mudanças desta entidade
-- Exemplos: `Order`, `Subscription`, `Invoice`, `Project`, `Ticket`
-
-**O que gerar:**
-- `AggregateRoot` com factory method estático
-- Value Objects para tipos com regras (Money, Email, PhoneNumber)
-- Domain Events para mudanças de estado relevantes
-- Commands + Queries (CQRS com MediatR)
-- Repository interface por aggregate root
-- **SEM** Bounded Context isolation (módulos se comunicam diretamente)
-
----
-
-### Nível 3 — Bounded Context
-
-**Quando usar (opt-in explícito apenas):**
-- Sistema tem 3+ domínios distintos onde o mesmo conceito tem modelos diferentes
-  - Exemplo: "Customer" em Billing ≠ "Customer" em Support
-- Times distintos trabalharão em cada domínio
-- Domínios precisam evoluir independentemente
-- Exemplos: plataforma multi-produto, marketplace, ERP
-
-**O que gerar:**
-- Tudo do Nível 2 +
-- Pasta `{BoundedContext}/` em Domain + Application
-- Integration Events para comunicação cross-BC (via MediatR/Service Bus)
-- Referências cross-BC por ID (nunca navigation properties)
-- Glossário de Linguagem Ubíqua por BC
-
-**⚠️ Não use Nível 3 por default.** Declare explicitamente na proposta.
-
----
-
-## Como Detectar o Nível
-
-O `domain-architect` analisa a proposta e responde:
-
-```
-1. A entidade principal tem estados com transições? → Sim = Nível 2+
-2. Existem invariants de negócio? → Sim = Nível 2+
-3. Cálculos derivados existem? → Sim = Nível 2+
-4. Outros domínios precisam reagir a mudanças? → Sim = Nível 2+
-5. Diferentes contextos usam modelos diferentes do mesmo conceito? → Sim = Nível 3
-6. O usuário declarou explicitamente Bounded Context? → Sim = Nível 3
-Se nenhuma das anteriores: Nível 1
-```
-
----
-
-## Template por Nível
-
-| Nível | Template |
-|-------|----------|
-| 1 | `code/dotnet/contracts/contracts-level1.cs` |
-| 2 | `code/dotnet/contracts/contracts-level2.cs` |
-| 3 | `code/dotnet/contracts/contracts-level3.cs` |
-
----
-
-## Anti-Patterns
-
-| Anti-Pattern | Nível Afetado | Correção |
-|---|---|---|
-| AggregateRoot para CRUD simples | Nível 1 desnecessário | Use Entity simples |
-| Domain Events sem consumidores | Nível 2 excessivo | Remova ou use Nível 1 |
-| Bounded Context para app single-domain | Nível 3 prematuro | Use Nível 2 |
-| Entidade anêmica com regras no Service | Todos | Mova regras para o Aggregate |
-| Value Objects para todo primitivo | Nível 2 excessivo | Só quando há regras/validação |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*