@polymorphism-tech/morph-spec 8.46.0 → 9.0.0

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -1,145 +0,0 @@
----
-name: morph-stack-scan
-description: Varre o codebase existente, detecta stack atual, compara com o stack padrão e registra desvios em stack-scan.md
-version: core
-when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
-user-invokable: true
-cliVersion: "8.46.0"
----
-
-# morph-stack-scan
-
-## Objetivo
-Identificar o estado real do codebase antes de planejar qualquer feature — garantindo que a implementação não adicione inconsistência a um projeto já existente.
-
-## Quando invocar
-Quando o projeto já tem código existente e você precisa entender o estado atual antes de propor uma feature. Normalmente invocado pelo morph-brainstorming, mas pode ser invocado diretamente.
-
-## Stack padrão de referência
-
-O "Esperado" da comparação do passo 2 é o stack baked-in (runtime .NET 10 + VSA, EF Core/Neon, `Guid.CreateVersion7()`, `sealed`, result pattern, MAF, Next.js/Tailwind/Shadcn, Hangfire) e a lista de padrões proibidos (`Guid.NewGuid()`, classes não-sealed, Service/Manager layer, repository genérico, SQL cru sem justificativa) — regra canônica em `MORPH.md` § "Stack baked-in". Os templates de `stack-scan.md` abaixo (greenfield e brownfield) escrevem essa lista por extenso no artefato da feature, para que quem ler o `stack-scan.md` depois não precise reabrir o `MORPH.md`.
-
-## Greenfield short-circuit
-
-Antes de despachar Explore, verifique se o projeto é greenfield:
-
-1. Use `Glob` para detectar presença de qualquer um destes:
-   - `**/*.csproj`
-   - `**/*.sln`
-   - `package.json` (na raiz)
-   - `src/**/*.cs` ou `src/**/*.ts` ou `src/**/*.tsx`
-   - `migrations/**/*`
-
-2. Se **nenhum** for encontrado, o projeto é greenfield. Produza este `stack-scan.md` em `.morph/features/{feature}/0-proposal/` e retorne sem chamar Explore:
-
-   ```markdown
-   # Stack Scan — {feature}
-
-   **Status:** GREENFIELD (sem código source detectado)
-
-   ## Stack
-   Project empty. Aplicar stack padrão de MORPH.md:
-   - Backend: .NET 10 + VSA + EF Core + Neon
-   - Frontend: Next.js App Router + Tailwind + Shadcn + Framer Motion
-   - IA: MAF (quando aplicável à feature)
-   - Jobs: Hangfire (apenas se necessário)
-
-   ## Padrões obrigatórios
-   - IDs: `Guid.CreateVersion7()`
-   - Classes: `sealed` por padrão
-   - Erros: Result pattern (`result.Match()`)
-
-   ## Padrões proibidos
-   `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
-
-   ## Recomendação
-   Compliance trivial (greenfield). Prosseguir para morph-brainstorming.
-   ```
-
-3. Se algum dos arquivos foi encontrado, o projeto é brownfield — siga para o passo seguinte.
-
-## O que fazer (brownfield)
-
-0. **Se houver grafo, ele responde a pergunta do repository genérico melhor que o grep.**
-
-   ```bash
-   morph-spec graph status --json                        # available:false? pule este passo
-   morph-spec graph affected IRepository --uses-only --json
-   morph-spec graph explain IRepository --json           # o registro no DI aparece aqui
-   ```
-
-   A pergunta do passo 1 é *"quantos CONSUMIDORES REAIS"*, e é exatamente aí que o grep erra: no ProspectPRO ele aponta **23 arquivos**, mas 20 são interfaces filhas **herdando** o contrato e só **2** são uso real. Quem lê 23 conclui "está em uso, não é código morto" — e a conclusão certa é a oposta. `--uses-only` exclui `inherits`/`implements`/`extends` e devolve os 2. O `explain` do mesmo símbolo entrega de brinde a outra metade da pergunta: onde ele está registrado no DI.
-
-   **Fallback:** grafo ausente (`no-graph`), símbolo não encontrado ou ambíguo — siga com o `Explore` e o grep do passo 1, e **registre no `stack-scan.md` que a contagem veio do grep**, que superestima consumidores por não separar herança de uso.
-
-1. Despache um `Explore` subagent para varrer o codebase:
-
-   ```
-   Varredura de stack compliance — morph-stack-scan.
-
-   Leia os seguintes arquivos/pastas e reporte o que encontrar:
-
-   BACKEND:
-   - Todos os .csproj: qual TargetFramework? Quais PackageReferences relevantes?
-   - Procure por: Guid.NewGuid() vs Guid.CreateVersion7(), sealed classes, result pattern vs exceptions
-   - Estrutura de src/: segue feature-folder (VSA)? Tem Controllers? Tem repository genérico (IRepository<T>/IUnitOfWork)? Se tiver, reporte como código morto: liste onde está registrado no DI e quantos consumidores reais existem em src/ e tests/
-   - Migrations/: qual ORM? Neon/Postgres ou outro banco?
-   - Microsoft.Agents.* ou Microsoft.Extensions.AI nos PackageReferences?
-
-   FRONTEND:
-   - package.json: Next.js? Tailwind? Framer Motion? Shadcn/ui?
-   - Estrutura de app/ ou pages/: App Router ou Pages Router?
-
-   JOBS:
-   - Hangfire nos PackageReferences?
-
-   Para cada item acima, responda: presente/ausente, e se presente qual versão ou padrão.
-   Não faça sugestões — apenas reporte o que existe.
-   ```
-
-2. Com os resultados da varredura, compare com o stack padrão item por item e classifique cada desvio:
-
-   | Severidade | Critério |
-   |------------|---------|
-   | **Bloqueante** | Runtime diferente (.NET 8 ou anterior), ORM diferente (Dapper puro sem EF Core), banco diferente (MySQL, SQL Server) |
-   | **Alto** | `Guid.NewGuid()` generalizado, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`) presente — código morto: migração é deletar a pasta `Repository/` + as 2 linhas de DI, SQL cru generalizado, exceptions como fluxo de controle |
-   | **Médio** | Classes não-sealed, Pages Router em vez de App Router, biblioteca de UI diferente |
-   | **Baixo** | Versões de pacotes desatualizadas mas compatíveis |
-
-3. Produza `stack-scan.md` em `.morph/features/{feature}/0-proposal/`:
-
-   ```markdown
-   # Stack Scan — {feature}
-
-   ## Resultado
-   {Em compliance / Desvios detectados}
-
-   ## Stack detectado
-   | Camada | Detectado | Esperado | Status |
-   |--------|-----------|----------|--------|
-   | Runtime | .NET X | .NET 10 | ✓ / ✗ |
-   ...
-
-   ## Desvios (ordenados por severidade)
-   ### Bloqueantes
-   - {desvio}: {onde foi encontrado} — impacto: {o que quebra se não migrar} — esforço: {estimativa}
-
-   ### Não bloqueantes
-   - {desvio}: {onde foi encontrado} — migração: {como resolver} — esforço: {estimativa}
-
-   ## Recomendação
-   {Em compliance — prosseguir para morph-brainstorming}
-   {ou: Migração necessária antes de prosseguir — ver Desvios acima}
-   ```
-
-4. Se houver desvios bloqueantes ou altos, pergunte via `AskUserQuestion`: "Esta migração deve ser incluída na feature atual ou tratada numa feature separada?" A resposta é decisão humana — registre-a na seção "Compliance de stack" do `proposal.md` (produzido pela `morph-brainstorming`), não num artefato novo: a lista de desvios com impacto/esforço já vive no `stack-scan.md` acima.
-
-5. Se não houver desvios (ou apenas baixos): informe "codebase em compliance com o stack padrão" e prossiga para morph-brainstorming ou morph-plan conforme o contexto.
-
-## Output esperado
-- `.morph/features/{feature}/0-proposal/stack-scan.md` — resultado da varredura, com desvios ordenados por severidade e esforço estimado
-- Decisão documentada: incluir migração nesta feature ou separar (registrada no proposal.md pela morph-brainstorming)
-
-## Referências
-- `.morph/framework/MORPH.md` — seção 4 (Standards), seção 2 (Fases)
-- `.claude/skills/morph-brainstorming/SKILL.md` — fluxo greenfield/brownfield

package/framework/templates/docs/proposal.md

@@ -1,192 +0,0 @@
-# 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}
-
----
-
-## Acceptance Criteria
-
-Verifiable conditions that mean this feature is done:
-
-- [ ] {Criterion 1 — observable / testable}
-- [ ] {Criterion 2}
-- [ ] {Criterion 3}
-
----
-
-## 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-neon")}}
-### Technical Approach
-
-| Layer | Technology | Role |
-|-------|-----------|------|
-| **Database** | Neon (PostgreSQL + RLS) | {tables, policies, storage} |
-| **Backend API** | .NET 10 Minimal API | {endpoints, business logic} |
-| **Frontend** | Next.js 15 (App Router) | {pages, components, auth} |
-| **Infra** | Coolify + 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-neon")}}
-## Cost Estimate
-
-| Resource | Provider | Monthly Cost | Notes |
-|----------|----------|-------------|-------|
-| Neon | Free / Launch | $0 - $19 | {DB, Connection Pooling, Branching} |
-| VPS (Coolify) | {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} |
-
----
-
-## Conflitos com o acervo
-
-UCs (`.morph/specs/usecases/`), ADRs ativos (`.morph/specs/adrs/`) and `.morph/context/*.md` that
-this request contradicts. `Nenhum conflito encontrado.` when there is none — the section is always present.
-
-| Fonte | O que diz hoje | O que o pedido muda | Decisão |
-|-------|----------------|---------------------|---------|
-| {UC-133} | {Public Sans + Lora em toda a interface} | {admin passa a Geist} | {vale o novo no admin; a vitrine mantém o antigo — decisions.md ADR-001} |
-
----
-
-## Dependencies
-
-- [ ] {Dependency 1} - {status}
-- [ ] {Dependency 2} - {status}
-
----
-
-## Estimated Effort
-
-| Phase | Estimate |
-|-------|----------|
-| Design & Spec | {X}h |
-{{#if (eq STACK "nextjs-neon")}}| 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}
-
----
-
-## Next Steps
-
-Once approved:
-1. Create detailed `spec.md` with technical design
-{{#if (eq STACK "nextjs-neon")}}2. Define contracts (`contracts.cs` + `contracts.ts`)
-3. Record decisions in `decisions.md`
-4. Break down into `tasks.json`
-5. Begin implementation
-{{else}}2. Break down into `tasks.json`
-3. Begin implementation
-{{/if}}
-
----
-
-*Created with MORPH Framework*

package/framework/templates/docs/spec.md

@@ -1,57 +0,0 @@
-# Feature Specification: {{titleCase FEATURE_NAME}}
-
-| Field | Value |
-|-------|-------|
-| **ID** | {{FEATURE_NAME}} |
-| **Created** | {{DATE}} |
-| **Stack** | {{STACK}} |
-
-> Behavior lives in the use cases (`2-plan/usecases/UC-*.md`). This file says HOW they are realized —
-> do not repeat postconditions here.
-
-## Architecture
-
-{Components, how they connect, main data flows. Enough to implement without basic questions.}
-
-### Data Model
-
-| Entity | Field | Type | Notes |
-|--------|-------|------|-------|
-| {Entity} | {field} | {type} | {constraint, index, relation} |
-
-### Contracts
-
-```
-{METHOD} /api/{route}
-Request:  { ... }
-Response: { ... }  |  ProblemDetails 400/404/409
-```
-
-## Technical edge cases
-
-- {Edge case} → {how it is handled}
-
-## UCs e ADRs que esta feature altera ou revoga
-
-> Read by `morph-spec finish`: in the archive commit, each row marks the project acervo — a UC turns
-> `status: superseded` + `superseded_by` (+ `scope` when partial); an ADR leaves `.morph/specs/adrs/`
-> (total) or keeps its file with the scope where it still holds (partial). Columns are positional.
-> `morph-spec usecase check {feature}` reports a bad row while this file can still change (it freezes at Gate 2).
-> Nothing revoked → replace the table with `Nenhum.`
-
-| Id | Mudança | Substituto | Escopo em que o antigo ainda vale |
-|----|---------|------------|-----------------------------------|
-| UC-{nn} | parcial | UC-{nn} | {where the old one still holds} |
-| {feature}/ADR-{nnn} | total | — | — |
-
-## Contrato de implementação
-
-- **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}

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

@@ -1,52 +0,0 @@
-# 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*

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

@@ -1,76 +0,0 @@
-# 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*

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

@@ -1,167 +0,0 @@
-# UI Flows: {{titleCase FEATURE_NAME}}
-
-| Field | Value |
-|-------|-------|
-| **Feature** | {{FEATURE_NAME}} |
-| **Created** | {{DATE}} |
-
----
-
-## User Stories
-
-### US001: {Primary User Story}
-
-**As** a {user type}
-**I want** to {capability}
-**So that** {benefit}
-
-**Acceptance Criteria:**
-1. {Criterion 1}
-2. {Criterion 2}
-
----
-
-## Flow Inventory
-
-| Flow ID | Name | Priority |
-|---------|------|----------|
-| **F001** | Create New Item | High |
-| **F002** | Edit Existing Item | High |
-| **F003** | Delete Item | Medium |
-
----
-
-## F001: Create New Item
-
-### Happy Path
-
-```
-START
-  ↓
-[User clicks "Add New"]
-  ↓
-[Modal opens with form]
-  ↓
-[User fills required fields]
-  ↓
-[User clicks "Submit"]
-  ↓
-[Validation passes] ✓
-  ↓
-[API call: POST /api/items]
-  ↓
-[Success response]
-  ↓
-[Modal closes]
-  ↓
-[Success toast: "Item created"]
-  ↓
-[Table refreshes]
-  ↓
-END
-```
-
-**Duration:** 15-30 seconds
-**Success Rate Target:** 95%
-
----
-
-### Alternative Path: Validation Error
-
-```
-[User clicks "Submit"]
-  ↓
-[Validation fails] ✕
-  ↓
-[Error messages shown inline]
-  ↓
-[User corrects errors]
-  ↓
-[Real-time validation clears errors]
-  ↓
-→ Returns to Happy Path
-```
-
----
-
-### Edge Cases
-
-| Scenario | Behavior |
-|----------|----------|
-| **Duplicate Name** | Show warning, allow submit |
-| **Network Error** | Show error toast, preserve data |
-| **Session Expired** | Redirect to login |
-
----
-
-## F002: Edit Existing Item
-
-```
-[User clicks "Edit"]
-  ↓
-[Modal opens with pre-filled form]
-  ↓
-[User modifies fields]
-  ↓
-[User clicks "Save"]
-  ↓
-[API call: PUT /api/items/{id}]
-  ↓
-[Success toast]
-  ↓
-[Table refreshes]
-END
-```
-
----
-
-## F003: Delete Item
-
-```
-[User clicks "Delete"]
-  ↓
-[Confirmation dialog: "Delete item?"]
-  ↓
-[User confirms]
-  ↓
-[API call: DELETE /api/items/{id}]
-  ↓
-[Success toast]
-  ↓
-[Table refreshes]
-END
-```
-
----
-
-## Toast Notifications
-
-| Event | Type | Message | Duration |
-|-------|------|---------|----------|
-| **Item Created** | Success | "Item created successfully" | 3s |
-| **Item Updated** | Success | "Item updated successfully" | 3s |
-| **Item Deleted** | Success | "Item deleted successfully" | 3s |
-| **Error** | Error | "Something went wrong" | 5s |
-
----
-
-## Keyboard Shortcuts
-
-| Shortcut | Action |
-|----------|--------|
-| **Ctrl+N** | New Item |
-| **Escape** | Close modal |
-| **Enter** | Submit form |
-
----
-
-## Performance Targets
-
-| Flow | Target |
-|------|--------|
-| **Create Item** | < 2s (API response) |
-| **Search** | < 500ms |
-
----
-
-*Generated with MORPH Framework*