@polymorphism-tech/morph-spec 4.7.0 → 4.7.2

package/.morph/framework/templates/docs/proposal.md

@@ -0,0 +1,182 @@
+# Feature Proposal: {{titleCase FEATURE_NAME}}
+
+> Proposal for a new feature. This document describes WHAT and WHY.
+> For technical details, see `spec.md`.
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Proposed** | {{DATE}} |
+| **Author** | {{AUTHOR}} |
+| **Status** | Draft / Under Review / Approved / Rejected |
+| **Priority** | High / Medium / Low |
+{{#if STACK}}| **Stack** | {{STACK}} |{{/if}}
+
+---
+
+## Overview
+
+{Brief 2-3 sentence summary of the feature}
+
+---
+
+## Problem Statement
+
+### What is the problem?
+
+{Describe the problem this feature solves. Be specific.}
+
+### Who is affected?
+
+{Who suffers from this problem? End users? Developers? Operations?}
+
+### What is the impact?
+
+{What is the impact of NOT solving this problem?}
+- User productivity loss: {X}
+- Revenue/Cost impact: {X}
+- User satisfaction: {X}
+
+---
+
+## Proposed Solution
+
+### Overview
+
+{Describe the proposed solution in 2-3 paragraphs}
+
+### Key Features
+
+1. **{Feature 1}** - {brief description}
+2. **{Feature 2}** - {brief description}
+3. **{Feature 3}** - {brief description}
+
+{{#if (eq STACK "nextjs-supabase")}}
+### Technical Approach
+
+| Layer | Technology | Role |
+|-------|-----------|------|
+| **Database** | Supabase (PostgreSQL + RLS) | {tables, policies, storage} |
+| **Backend API** | .NET 10 Minimal API | {endpoints, business logic} |
+| **Frontend** | Next.js 15 (App Router) | {pages, components, auth} |
+| **Infra** | EasyPanel + Docker | {deployment, SSL} |
+{{/if}}
+
+### User Journey
+
+```
+1. User {initial action}
+2. System {response}
+3. User {next action}
+4. System {final result}
+```
+
+---
+
+{{#if (eq STACK "nextjs-supabase")}}
+## Cost Estimate
+
+| Resource | Provider | Monthly Cost | Notes |
+|----------|----------|-------------|-------|
+| Supabase | Free / Pro | $0 - $25 | {DB, Auth, Storage, Realtime} |
+| VPS (EasyPanel) | {provider} | ${X} | {API + Web containers} |
+| External APIs | {provider} | ${X} | {if applicable} |
+| **Total** | | **${X}/month** | |
+
+---
+
+{{/if}}
+## Success Metrics
+
+How will we know this feature is successful?
+
+| Metric | Current | Target |
+|--------|---------|--------|
+| {Metric 1} | {X} | {Y} |
+| {Metric 2} | {X} | {Y} |
+
+---
+
+## Scope
+
+### In Scope
+
+- {Item 1 that is included}
+- {Item 2 that is included}
+- {Item 3 that is included}
+
+### Out of Scope
+
+- {Item 1 that is NOT included}
+- {Item 2 that is NOT included}
+
+### Future Considerations
+
+- {Item that could be added later}
+
+---
+
+## Risks & Concerns
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| {Risk 1} | High/Med/Low | High/Med/Low | {mitigation strategy} |
+| {Risk 2} | High/Med/Low | High/Med/Low | {mitigation strategy} |
+
+---
+
+## Dependencies
+
+- [ ] {Dependency 1} - {status}
+- [ ] {Dependency 2} - {status}
+
+---
+
+## Estimated Effort
+
+| Phase | Estimate |
+|-------|----------|
+| Design & Spec | {X}h |
+{{#if (eq STACK "nextjs-supabase")}}| Database & Migrations | {X}h |
+| Backend API | {X}h |
+| Frontend | {X}h |
+{{else}}| Implementation | {X}h |
+{{/if}}| Testing | {X}h |
+| **Total** | **{X}h** |
+
+---
+
+## Questions & Clarifications
+
+1. {Question 1 that needs answering}
+2. {Question 2 that needs answering}
+
+---
+
+{{#if (eq STACK "blazor-azure")}}
+## Approval
+
+| Role | Name | Decision | Date |
+|------|------|----------|------|
+| Product Owner | | Pending | |
+| Tech Lead | | Pending | |
+
+---
+
+{{/if}}
+## Next Steps
+
+Once approved:
+1. Create detailed `spec.md` with technical design
+{{#if (eq STACK "nextjs-supabase")}}2. Define contracts (`contracts.cs` + `contracts.ts`)
+3. Record decisions in `decisions.md`
+4. Break down into `tasks.md`
+5. Begin implementation
+{{else}}2. Break down into `tasks.md`
+3. Begin implementation
+{{/if}}
+
+---
+
+*Created with MORPH Framework*

package/.morph/framework/templates/docs/schema-analysis.md

@@ -0,0 +1,119 @@
+# Schema Analysis - {{FEATURE_NAME_TITLE}}
+
+**Feature**: {{FEATURE_NAME}}
+**Date**: {{DATE}}
+**Method**: {{#if method}}{{method}}{{else}}Manual Code Analysis{{/if}}
+**Analyzed By**: {{AUTHOR}}
+
+---
+
+## Summary
+
+**Tables Analyzed**: {{#if tableCount}}{{tableCount}}{{else}}0{{/if}}
+**Code Files Scanned**: {{#if fileCount}}{{fileCount}}{{else}}0{{/if}}
+**MCP Tools Used**: {{#if mcpUsed}}{{mcpUsed}}{{else}}No (manual analysis){{/if}}
+
+---
+
+## Tables Analyzed
+
+{{#each tables}}
+### Table: {{this.name}}
+
+**Source:**
+{{#if this.mcpSource}}- MCP: {{this.mcpSource}}{{/if}}
+{{#if this.codeSource}}- Code: {{this.codeSource}}{{/if}}
+
+**Columns:**
+| Column Name | Type | Nullable | Default | Notes |
+|------------|------|----------|---------|-------|
+{{#each this.columns}}
+| {{this.name}} | {{this.type}} | {{#if this.nullable}}YES{{else}}NO{{/if}} | {{#if this.default}}{{this.default}}{{else}}-{{/if}} | {{#if this.notes}}{{this.notes}}{{else}}-{{/if}} |
+{{/each}}
+
+**Relationships:**
+{{#each this.relationships}}
+- {{this.description}}
+{{/each}}
+
+**Indexes:**
+{{#each this.indexes}}
+- {{this.description}}
+{{/each}}
+
+---
+{{/each}}
+
+## ⚠️ CRITICAL FINDINGS
+
+### Field Name Mismatches (MUST FIX)
+
+{{#if fieldMismatches}}
+{{#each fieldMismatches}}
+- ❌ {{this.description}}
+{{/each}}
+{{else}}
+✅ No field name mismatches found
+{{/if}}
+
+### Type Mismatches
+
+{{#if typeMismatches}}
+{{#each typeMismatches}}
+- ⚠️ {{this.description}}
+{{/each}}
+{{else}}
+✅ No type mismatches found
+{{/if}}
+
+### Relationship Corrections
+
+{{#if relationshipIssues}}
+{{#each relationshipIssues}}
+- ⚠️ {{this.description}}
+{{/each}}
+{{else}}
+✅ All relationships correctly identified
+{{/if}}
+
+---
+
+## Recommendations for contracts.cs
+
+Based on real schema analysis:
+
+\`\`\`csharp
+{{#each dtoRecommendations}}
+// {{this.tableName}} → {{this.dtoName}}
+public record {{this.dtoName}}(
+{{#each this.fields}}
+    {{this.type}} {{this.name}}{{#if this.nullable}}?{{/if}}{{#unless @last}},{{/unless}}  // {{#if this.comment}}{{this.comment}}{{/if}}
+{{/each}}
+);
+
+{{/each}}
+\`\`\`
+
+---
+
+## Analysis Notes
+
+{{#if notes}}
+{{notes}}
+{{else}}
+_No additional notes._
+{{/if}}
+
+---
+
+## Next Steps
+
+- [ ] Verify schema analysis with stakeholders
+- [ ] Generate `contracts.cs` using real field names
+- [ ] Update `spec.md` data model section with findings
+- [ ] Document any schema migrations needed in `decisions.md`
+
+---
+
+*Generated by MORPH-SPEC v{{FRAMEWORK_VERSION}}*
+*Schema analysis helps prevent DTO field name mismatches and ensures contracts match real database schema*

package/.morph/framework/templates/docs/spec.md

@@ -0,0 +1,198 @@
+# Feature Specification: {{titleCase FEATURE_NAME}}
+
+| 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} |
+
+---
+
+## Overview
+
+**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 Design
+
+### Stack
+| Component | Technology |
+|-----------|------------|
+| Frontend | {Blazor Server / Next.js} |
+| Backend | .NET 10 / C# 14 |
+| Database | {Azure SQL / Cosmos DB} |
+
+### Data Model
+
+#### {EntityName}
+| Column | Type | Constraints |
+|--------|------|-------------|
+| Id | Guid | PK |
+| {Property} | {Type} | {Constraints} |
+| CreatedAt | datetime2 | Default: GETUTCDATE() |
+
+### Contracts
+
+> **Ref:** `framework/standards/backend/database/ef-core.md` for background operations
+
+```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}
+
+---
+
+## Aggregate Blueprint (Nível 2+ apenas)
+
+> Omitir esta seção se Nível 1 (CRUD).
+
+### Aggregate Root: {EntityName}
+
+**Invariants:**
+- {Invariant 1 em linguagem natural}
+- {Invariant 2}
+
+**Estados e Transições:**
+```
+{Status.Draft} → Confirm() → {Status.Confirmed} → Cancel() → {Status.Cancelled}
+```
+
+**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}
+```
+
+### 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}
+
+---
+
+## Security
+
+| Action | Required Policy |
+|--------|-----------------|
+| View | CanView{Feature} |
+| Create | CanManage{Feature} |
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {Risk} | {H/M/L} | {Mitigation} |
+
+## Out of Scope
+- {Item}
+
+## Definition of Done
+- [ ] Code implemented
+- [ ] Tests >80% coverage
+- [ ] Code review approved
+- [ ] Deploy to staging
+- [ ] Recap.md generated

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

@@ -0,0 +1,124 @@
+# UI Components: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+| **Stack** | {{STACK}} |
+
+---
+
+{{#if (eq STACK "blazor-azure")}}
+## Component Library: FluentUI Blazor / MudBlazor
+
+**NuGet Package:**
+```xml
+<PackageReference Include="Microsoft.FluentUI.AspNetCore.Components" Version="4.x.x" />
+```
+
+---
+
+### C001: Header Navigation
+
+**Component:** `<FluentHeader>`
+
+```razor
+<FluentHeader>
+    <FluentLabel>{{FEATURE_NAME}}</FluentLabel>
+    <FluentSpacer />
+    <FluentPersona Name="@userName" OnClick="@ShowUserMenu" />
+</FluentHeader>
+```
+
+---
+
+### C002: Primary Button
+
+**Component:** `<FluentButton>`
+
+```razor
+<FluentButton Appearance="Appearance.Accent"
+              OnClick="@HandleSave"
+              Disabled="@(!isValid)">
+    Save
+</FluentButton>
+```
+
+---
+
+### C003: Data Table
+
+**Component:** `<FluentDataGrid>`
+
+```razor
+<FluentDataGrid Items="@items" Pagination="@pagination">
+    <PropertyColumn Property="@(i => i.Name)" Sortable="true" />
+    <PropertyColumn Property="@(i => i.Status)" Sortable="true" />
+    <TemplateColumn Title="Actions">
+        <FluentMenu>
+            <FluentMenuItem OnClick="@(() => EditItem(context))">Edit</FluentMenuItem>
+            <FluentMenuItem OnClick="@(() => DeleteItem(context))">Delete</FluentMenuItem>
+        </FluentMenu>
+    </TemplateColumn>
+</FluentDataGrid>
+```
+
+---
+
+### C004: Form Input
+
+**Component:** `<FluentTextField>`
+
+```razor
+<FluentTextField @bind-Value="model.Name"
+                 Label="Name"
+                 Required="true"
+                 MaxLength="100"
+                 ErrorMessage="@GetValidationError(nameof(model.Name))">
+</FluentTextField>
+```
+
+{{/if}}
+
+{{#if (eq STACK "nextjs-supabase")}}
+## 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*

package/.morph/framework/templates/docs/ui-design-system.md

@@ -0,0 +1,76 @@
+# UI Design System: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+| **Project** | {{PROJECT_NAME}} |
+
+---
+
+## Color Palette
+
+### Primary Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--color-primary` | #0078D4 | Primary actions, links |
+| `--color-primary-hover` | #106EBE | Hover states |
+
+### Semantic Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--color-success` | #107C10 | Success states |
+| `--color-warning` | #F7630C | Warnings |
+| `--color-error` | #D13438 | Errors |
+
+---
+
+## Typography
+
+| Token | Size | Weight | Usage |
+|-------|------|--------|-------|
+| `--text-h1` | 24px | 600 | Section headers |
+| `--text-body` | 14px | 400 | Body text |
+| `--text-caption` | 12px | 400 | Labels |
+
+---
+
+## Spacing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--space-sm` | 8px | Compact spacing |
+| `--space-md` | 16px | Standard spacing |
+| `--space-lg` | 24px | Wide spacing |
+
+---
+
+## Components
+
+### Buttons
+- **Primary**: `--color-primary` background, white text
+- **Secondary**: Transparent, `--color-primary` border
+- **Sizes**: Small (24px), Medium (32px), Large (40px)
+
+### Forms
+- **Input height**: 32px
+- **Focus**: 2px solid `--color-primary`
+- **Error**: 1px solid `--color-error`
+
+---
+
+## Accessibility
+- [ ] 4.5:1 contrast ratio (WCAG AA)
+- [ ] Touch targets minimum 44x44px
+- [ ] Keyboard navigation supported
+
+---
+
+## Responsive Breakpoints
+- **Mobile**: < 768px
+- **Tablet**: 768px - 1199px
+- **Desktop**: ≥ 1200px
+
+---
+
+*Generated with MORPH Framework*