@polymorphism-tech/morph-spec 7.3.0 → 7.5.0

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -0,0 +1,452 @@
+---
+name: migrate-lp-to-umbraco
+description: Migra uma landing page existente (React/Vite, Next.js estático ou HTML) para o template Umbraco-headless MORPH_Umbraco_LP_Template entregando a LP EXATAMENTE igual à origem (mesmo CSS, imagens, fontes e comportamento) + Umbraco por cima — obtenção automática do template, inventário de seções, lift-and-rewire verbatim de cada seção para módulo editável, conexão do formulário ao backend de leads e gate de paridade determinístico. Repo-agnóstica: roda em qualquer lugar, sem template nem origem pré-baixados.
+version: core
+when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
+user-invokable: true
+cliVersion: "7.5.0"
+---
+
+# migrate-lp-to-umbraco
+
+## Objetivo
+
+Conduzir a migração de uma landing page de origem arbitrária para o stack Umbraco 17 / .NET 10 + Next.js do template `MORPH_Umbraco_LP_Template`, entregando uma LP **visual e funcionalmente idêntica à origem** (mesmo CSS, imagens, fontes, animações e comportamento) com o Umbraco embrulhando o conteúdo por cima — projeto funcional e idempotentemente seedável onde todo conteúdo editorial (textos, imagens, vídeos) fica editável no backoffice, e as credenciais de integração de leads nunca saem do backoffice.
+
+**Princípio central — lift-and-rewire, não rebuild.** A paridade exata é garantida **por construção**: copia-se o markup/CSS/classes/assets de cada seção da origem **verbatim** para o componente do módulo, trocando apenas os literais de conteúdo (texto, `src` de mídia) por leituras do backoffice. O render é idêntico porque o markup é o mesmo; o gate de paridade (passo 6) é uma **confirmação** de que o lift foi limpo, não uma ferramenta para descobrir e remendar drift. Reescrever cada seção do zero ("rebuild-then-compare") nunca converge para "exatamente igual" — não fazer isso.
+
+O processo é reproduzível para qualquer LP (React/Vite, Next.js estático ou HTML). A skill é **repo-agnóstica**: não depende de nenhum repo de exemplo nem do template estarem pré-baixados — ela obtém o template sozinha (passo 0).
+
+## Quando invocar
+
+- Usuário pede "use /migrate-lp-to-umbraco {projeto}" ou equivalente natural ("migrar LP para Umbraco", "portar site para Umbraco headless", "rebuild no template Umbraco").
+- Projeto de origem já existe (brownfield) — LP em React/Vite/Next.js/HTML.
+
+## Argumentos
+
+- `{projeto}` — nome do projeto em kebab-case (ex.: `reserva-das-flores`, `lp-imobiliaria`). Se ausente, perguntar via `AskUserQuestion`.
+
+## Pré-condições
+
+- **Acesso ao template** — `git` + (preferencialmente) `gh` autenticado com acesso ao repo **privado** `polymorphism-tech/MORPH_Umbraco_LP_Template`. O template **não** precisa estar pré-baixado: o passo 0 o obtém. (Para clone via `git` direto, é preciso credencial HTTPS ou chave SSH com acesso à org.)
+- **Origem acessível** — em uma das duas formas (a skill suporta ambas):
+  - **(a) código-fonte local** da LP (React/Vite, Next.js ou HTML) — caminho de **fidelidade máxima**, pois o CSS, o markup e os assets exatos estão disponíveis para o lift verbatim.
+  - **(b) apenas a URL** da LP em produção — fallback: scrapear o HTML renderizado, o CSS computado e baixar todos os assets. O mesmo gate de paridade (passo 6) se aplica.
+- **Docker** disponível para boot local (`docker compose`), ou .NET 10 SDK + Node para boot sem container.
+
+## Passo 0 — Obter o template (sempre)
+
+A skill **sempre** garante uma cópia local do template antes de qualquer outro passo. Roda em qualquer diretório — não assume nada pré-baixado.
+
+**Cache de referência (read-only).** Manter uma cópia canônica do template num cache estável por máquina, para leitura dos arquivos de referência (sinks, `SeedContentHandler`, `moduleRegistry`, e2e) e como base do scaffold:
+
+- bash: `TPL="${MORPH_TEMPLATE_CACHE:-$HOME/.morph/templates}/MORPH_Umbraco_LP_Template"`
+- PowerShell: `$Tpl = "$env:USERPROFILE\.morph\templates\MORPH_Umbraco_LP_Template"`
+
+**Rotina check-local → clone → pull:**
+
+```bash
+# Bash — obtém ou atualiza o cache do template
+TPL="${MORPH_TEMPLATE_CACHE:-$HOME/.morph/templates}/MORPH_Umbraco_LP_Template"
+if [ -d "$TPL/.git" ]; then
+  git -C "$TPL" pull --ff-only || echo "offline — usando cache existente"
+else
+  mkdir -p "$(dirname "$TPL")"
+  gh repo clone polymorphism-tech/MORPH_Umbraco_LP_Template "$TPL" \
+    || git clone https://github.com/polymorphism-tech/MORPH_Umbraco_LP_Template.git "$TPL" \
+    || git clone git@github.com:polymorphism-tech/MORPH_Umbraco_LP_Template.git "$TPL"
+fi
+```
+
+```powershell
+# PowerShell — obtém ou atualiza o cache do template
+$Tpl = "$env:USERPROFILE\.morph\templates\MORPH_Umbraco_LP_Template"
+if (Test-Path "$Tpl\.git") {
+  git -C "$Tpl" pull --ff-only
+} else {
+  New-Item -ItemType Directory -Force (Split-Path $Tpl) | Out-Null
+  gh repo clone polymorphism-tech/MORPH_Umbraco_LP_Template "$Tpl"
+  if (-not (Test-Path "$Tpl\.git")) { git clone https://github.com/polymorphism-tech/MORPH_Umbraco_LP_Template.git "$Tpl" }
+  if (-not (Test-Path "$Tpl\.git")) { git clone git@github.com:polymorphism-tech/MORPH_Umbraco_LP_Template.git "$Tpl" }
+}
+```
+
+Notas:
+- Branch padrão do template é **`master`** — **não** fazer `git checkout` de outra branch (o template já está generalizado: doctype raiz `lpHome`, scripts `new-lp`, sinks de lead, e2e).
+- `gh repo clone` é o caminho primário por ser repo **privado** (usa o token já autenticado). HTTPS/SSH são fallback.
+- O cache é **somente leitura**: nunca rodar `new-lp` nem editar dentro dele — o scaffold (passo 3) trabalha sobre uma **cópia fresca**.
+
+## Fluxo
+
+### 1. Analisar a origem — capturar PARA UM LIFT VERBATIM
+
+O objetivo desta etapa não é "entender" a LP, é **capturar tudo o que é necessário para reproduzi-la byte-a-byte**. Cada item abaixo alimenta o lift do passo 4.
+
+**Inventário de seções** — para cada bloco visual da página, documentar:
+- Nome e ordem na página.
+- **Markup e classes exatos**: a árvore DOM e os nomes de classe de cada seção, como estão (não normalizar nem "limpar").
+- Conteúdo textual: títulos, subtítulos, corpo, CTAs, links.
+- Mídia: imagens, vídeos, posters — registrar o caminho/URL de cada um para baixar abaixo.
+- **Comportamento interativo**: animação de scroll/scroll-expand, carrossel, marquee, autoplay de vídeo, hovers, mapa, máscara/validação de formulário — documentar cada um com detalhe suficiente para reproduzir idêntico.
+- Dados estruturados aninhados (ex.: lista de produtos com nome+imagem+descrição, lista de depoimentos).
+- **Breakpoints responsivos** e o que muda em cada um (mobile/tablet/desktop).
+
+**Tema e CSS — copiar VERBATIM, não reinterpretar:**
+- Capturar o CSS da origem como está: bloco `@theme`/tokens (variáveis `--color-*`, `--font-*`), classes custom, `@layer`, `@keyframes`, media queries. Os valores serão **portados sem alteração** no passo 4 — não arredondar cores nem aproximar espaçamentos.
+- **Config do Tailwind**: portar a config/tema da origem. Tailwind v4 é CSS-based (`@theme` em `globals.css`). ⚠️ A **mesma classe utilitária renderiza diferente** se a versão ou o tema do Tailwind divergir — portar o tema da origem, **nunca** assumir o do template.
+
+**Assets — baixar byte-a-byte e registrar checksum:**
+- Baixar/copiar **todos** os assets: imagens, vídeos, posters, ícones e **fontes** (arquivos `.woff2`/`.ttf` + famílias e pesos exatos). Web-fonts são parte da fidelidade — mesma família, mesmo peso, mesmo arquivo.
+- Registrar o `sha256` de cada asset (vira a base da paridade de checksum no passo 6).
+- **Não reencodar nem otimizar** nenhum asset — qualquer reencode quebra a paridade.
+
+**Formulário de captação** — campos presentes, validação no frontend, endpoint atual, integração de CRM/leads.
+
+**Origem apenas por URL (fallback):** se não houver código-fonte, scrapear o HTML renderizado, extrair o CSS computado dos elementos e baixar todos os assets referenciados (incluindo fontes). O lift parte do markup renderizado + CSS computado.
+
+**Exemplo ilustrativo (LP fictícia):**
+- Origem: `src/App.tsx` (React/Vite) — componentes `Navbar`, `Hero`, `HorizontalScroll`, `Manifesto`, `Galeria`, `Testimonial`, `CTA`, `Footer`.
+- Tema extraído do bloco `@theme` em `src/index.css`: `--color-surface`, `--color-primary`, `--color-tertiary`, etc.; tipografia (ex.) Cormorant Garamond + Jost (baixar os arquivos de fonte).
+- Formulário: campos nome, e-mail, telefone + POST para servidor com integração de leads.
+
+Produzir `docs/origem-inventario.md` no repositório destino com esta análise (incluindo a tabela de assets com `sha256`).
+
+### 2. Mapear origem para doctypes/módulos do template
+
+Comparar cada seção inventariada com os módulos disponíveis no template:
+
+| Módulo (alias uSync) | Propósito |
+|---|---|
+| `heroSection` | Hero genérico com título, subtítulo, imagem/vídeo de fundo e CTA |
+| `diferencialSection` / `diferencialItem` | Lista de diferenciais/features com ícone e descrição |
+| `testimonialSection` / `testimonialItem` | Depoimentos com nome, cargo e texto |
+| `galeriaSection` | Galeria de imagens |
+| `videoSection` | Bloco com vídeo embutido |
+| `equipeSection` / `equipeMembro` | Equipe com foto, nome e cargo |
+| `certificacoesSection` / `certificacaoItem` | Selos e certificações |
+| `localizacaoSection` | Mapa ou endereço |
+| `contatoSection` | Seção de formulário de captação |
+| `customHtmlSection` | Bloco HTML livre (fallback para conteúdo sem módulo dedicado) |
+
+Para cada seção da origem, determinar (na ótica do lift verbatim — fidelidade primeiro):
+1. **Reuso direto de módulo do template**: **somente** quando o markup e o CSS renderizados do módulo do template já são idênticos aos da origem. Se houver qualquer diferença visual, **não** reusar — isso introduz drift. Na dúvida, prefira lift verbatim.
+2. **Módulo do template com ajuste de campos**: o módulo serve mas precisa de propriedades extras — adicionar no uSync `.config` do módulo e no componente frontend. O markup permanece o da origem.
+3. **Módulo novo via lift verbatim (caso padrão)**: a seção vira um novo doctype + componente que **reproduz o markup/CSS/classes da origem verbatim** (ver passo 4). Criar o doctype + componente + registro no `moduleRegistry.ts`. Nomear o alias em camelCase com sufixo `Section` (ex.: `manifestoSection`, `galeriaSection`).
+
+> Regra prática: a decisão default é **lift verbatim** (opção 3). Reusar um módulo do template (opções 1/2) só quando a paridade visual é garantida — caso contrário a LP migrada deixa de ser "exatamente igual".
+
+Documentar decisões e justificativas em `docs/mapeamento-modulos.md`.
+
+**Exemplo ilustrativo — módulos lifted da origem:**
+- `heroSection` (lift): Hero com efeito scroll-expand + vídeo de fundo expansível — markup e animação copiados verbatim da origem.
+- `brandStorySection`: Bloco editorial de história da marca com imagem e texto em colunas.
+- `galeriaSection` / `galeriaItem`: Grade de itens com imagem, nome e descrição.
+- `processoSection` / `processoStep`: Processo em etapas (passo a passo numerado).
+- `marqueeSection`: Faixa de texto em loop (palavras-chave da marca).
+- `statsSection`: Contador de métricas (anos, projetos, etc.).
+- Módulos reutilizados diretamente (só porque o render bate com a origem): `testimonialSection`, `contatoSection`.
+
+### 3. Scaffold via new-lp
+
+Criar o projeto destino a partir de uma **cópia fresca** do template (nunca dentro do cache do passo 0) e rodar o bootstrap nessa cópia:
+
+```bash
+# Bash (Linux/macOS/WSL) — cópia fresca do cache para o diretório do projeto
+TPL="${MORPH_TEMPLATE_CACHE:-$HOME/.morph/templates}/MORPH_Umbraco_LP_Template"
+cp -r "$TPL" ./{projeto} && cd ./{projeto}
+rm -rf .git && git init   # desacopla do histórico do template
+# --lead-integration: none | ghl | prospectpro | webhook
+# --reset-db: primeiro boot limpo de um scaffold novo
+./scripts/new-lp.sh "Nome do Projeto" admin@projeto.com \
+  --lead-integration ghl \
+  --reset-db
+```
+
+```powershell
+# PowerShell (Windows) — cópia fresca do cache para o diretório do projeto
+$Tpl = "$env:USERPROFILE\.morph\templates\MORPH_Umbraco_LP_Template"
+Copy-Item $Tpl ".\{projeto}" -Recurse; Set-Location ".\{projeto}"
+Remove-Item .git -Recurse -Force; git init   # desacopla do histórico do template
+# new-lp.ps1 usa parâmetros NOMEADOS (não posicionais/--flag):
+.\scripts\new-lp.ps1 -ProjectName "Nome do Projeto" -AdminEmail admin@projeto.com `
+  -LeadIntegration ghl -ResetDb
+```
+
+> Alternativa: em vez de copiar do cache, fazer um clone fresco direto no diretório do projeto (`gh repo clone polymorphism-tech/MORPH_Umbraco_LP_Template {projeto}`) e então `rm -rf .git && git init`.
+
+O script:
+- Gera `.env` com `UMBRACO_ADMIN_EMAIL`, `UMBRACO_ADMIN_PASSWORD` (senha aleatória), `UMBRACO_GLOBAL_ID`, `REVALIDATE_SECRET`, `PROJECT_NAME` e `LEAD_INTEGRATION`.
+- Integração de lead selecionada em `--lead-integration` (`none`/`ghl`/`prospectpro`/`webhook`). Em modo não-interativo sem a flag, assume `none`.
+
+Nunca commitar `.env`. O cache do passo 0 permanece intacto (read-only) — todo o trabalho acontece nesta cópia.
+
+**Smoke-boot antes de qualquer customização** — boot limpo do template para confirmar que o ambiente funciona:
+
+```bash
+docker compose up --build
+```
+
+Backend sobe em `http://localhost:5001`, frontend em `http://localhost:3000`. Acessar `http://localhost:3000` e confirmar que a página carrega sem erro 500. Isso elimina problemas de ambiente antes de introduzir customizações — falha precoce = horas economizadas.
+
+**Atenção (gotcha Build do Next.js):** o Dockerfile do frontend executa `next build` na imagem — nesse momento o backend precisa estar acessível para o Next.js buscar conteúdo via Delivery API. Se o build rodar antes do backend estar pronto, o build falha com erro de fetch. O `docker compose` com `depends_on: backend` mitiga isso, mas em CI adicionar um `healthcheck` no serviço `backend` e `condition: service_healthy` no `depends_on` do `frontend`.
+
+### 4. Lift verbatim — portar markup, mídia e tema
+
+**Esta é a etapa que garante a paridade exata.** Para cada seção, o trabalho é um **lift-and-rewire**, não um rebuild:
+
+1. **Copiar o componente da origem verbatim** para `frontend/src/components/modules/NomeSection.tsx` — mesmo JSX/HTML, mesmas classes, mesmo CSS, mesma estrutura. Não "limpar", não refatorar, não trocar libs de animação.
+2. **Trocar apenas os literais de conteúdo** (texto, `src` de imagem/vídeo, labels) por leituras do `data` prop do Umbraco. Tudo o que é layout/estilo/markup permanece igual.
+3. **Seedar** esses valores via `SeedContentHandler` para baterem com a origem (passo 4b) → o primeiro render é idêntico **por construção**; a editabilidade no backoffice fica por cima sem mudar o markup renderizado.
+4. **Copiar os assets sem reencode** (passo 4b) e **portar o CSS/tema verbatim** (passo 4c).
+
+Os passos 4a-4d abaixo detalham cada parte. A regra que atravessa todos: **se mudou o markup ou o CSS renderizado, não é mais "exatamente igual"**.
+
+#### 4a. Módulos novos — uSync ContentType
+
+Para cada módulo novo identificado no passo 2, criar o arquivo `.config` em `backend/uSync/v17/ContentTypes/`. Espelhar a estrutura dos módulos existentes (ex.: `heroSection.config`):
+
+```xml
+<!-- Exemplo: atelierSection.config -->
+<?xml version="1.0" encoding="utf-8"?>
+<ContentType Key="{novo-guid}" Alias="atelierSection" Level="2">
+  <Info>
+    <Name>Atelier Section</Name>
+    <Icon>icon-layers</Icon>
+    <Thumbnail>folder.png</Thumbnail>
+    <Description></Description>
+    <AllowAtRoot>False</AllowAtRoot>
+    <IsListView>False</IsListView>
+    <Variations>Nothing</Variations>
+    <IsElement>true</IsElement>
+    <Folder>Sections</Folder>
+    <Compositions />
+    <DefaultTemplate></DefaultTemplate>
+    <AllowedTemplates />
+  </Info>
+  <Structure />
+  <GenericProperties>
+    <GenericProperty>
+      <Key>{guid-prop}</Key>
+      <Name>Titulo</Name>
+      <Alias>titulo</Alias>
+      <Definition>0cc0eba1-9960-42c9-bf9b-60e150b429ae</Definition>
+      <Type>Umbraco.TextBox</Type>
+      <Mandatory>true</Mandatory>
+      <Description><![CDATA[]]></Description>
+      <SortOrder>0</SortOrder>
+      <Tab Alias="content/content">Content</Tab>
+      <Variations>Nothing</Variations>
+    </GenericProperty>
+    <!-- propriedades adicionais -->
+  </GenericProperties>
+</ContentType>
+```
+
+Cada módulo carrega suas próprias propriedades diretamente — os módulos do template não usam compositions compartilhadas para campos de seção (o `<Compositions />` é vazio nos módulos existentes; as compositions em `lpHome.config` são para SEO, cookie e analytics — composições transversais da home, não dos módulos filhos).
+
+Para que o novo módulo apareça como opção de bloco na home, registrá-lo no DataType de Block List (`modules` em `lpHome.config`). O `<Definition>649d20e8-e4d5-42a0-9f27-28a537f9ebda</Definition>` aponta para esse DataType — adicionar o novo `ContentTypeKey` no XML do DataType em `backend/uSync/v17/DataTypes/` (arquivo correspondente) e no `SeedContentHandler` para o bloco ser incluído no seed programático.
+
+#### 4b. Seed de conteúdo — SeedContentHandler
+
+O `SeedContentHandler` (`backend/Infrastructure/SeedContentHandler.cs`) roda na notificação `uSyncImportCompletedNotification` — após o Umbraco importar todos os schemas — e cria a home com conteúdo inicial se ainda não existir. É **idempotente**: verifica se já há um nó raiz do tipo `lpHome` (ou alias equivalente) antes de criar.
+
+Padrão de seed de uma seção com mídia:
+
+```csharp
+// 1. Importar asset para a Media Library (idempotente por nome de arquivo)
+var mediaItem = CreateOrGetMedia("hero-video.mp4", mediaFolder, "umbracoMediaVideo");
+// mediaItem.Key é um Guid estável entre boots
+
+// 2. Serializar referência como MediaPicker3 JSON
+var mediaJson = JsonSerializer.Serialize(new[] {
+    new { key = Guid.NewGuid(), mediaKey = mediaItem.Key }
+});
+
+// 3. Setar na propriedade do nó de conteúdo
+sectionNode.SetValue("videoFundo", mediaJson);
+```
+
+Coloque os assets de seed em `backend/seed-assets/` (imagens, vídeos, ícones da LP de origem).
+
+**O que vai no SeedContentHandler:** textos de inauguração, mídia local (arquivos em `seed-assets/`), ordem das seções, configuração inicial. O conteúdo fica editável no backoffice após o primeiro boot — o seed é apenas o estado inicial.
+
+**O que NÃO vai no SeedContentHandler:** tokens de integração (GHL API Key, webhook URL). Esses ficam no nó `leadsConfig` que o operador preenche diretamente no backoffice após o boot (ver passo 5).
+
+#### 4c. Tema — portabilidade do index.css
+
+Copiar as variáveis de design da origem para `frontend/src/app/globals.css` no bloco `@theme`:
+
+```css
+/* Antes (origem — index.css/CSS da LP) */
+@theme {
+  --color-surface: #F5F0EB;
+  --color-primary: #8B1A1A;
+  --color-primary-hover: #A82020;
+  --color-tertiary: #1A1A1A;
+  --font-display: 'Cormorant Garamond', serif;
+  --font-body: 'Jost', sans-serif;
+}
+
+/* Depois (destino — frontend/src/app/globals.css) */
+@theme {
+  --color-surface: #F5F0EB;   /* portado diretamente */
+  --color-primary: #8B1A1A;
+  --color-primary-hover: #A82020;
+  --color-tertiary: #1A1A1A;
+  --font-display: 'Cormorant Garamond', serif;
+  --font-body: 'Jost', sans-serif;
+}
+```
+
+Atualizar os `<link>` de Google Fonts em `frontend/src/app/layout.tsx` para carregar as fontes corretas.
+
+#### 4d. Componentes frontend dos módulos novos
+
+Para cada módulo novo, criar o componente em `frontend/src/components/modules/NomeSection.tsx` **a partir do componente da origem copiado verbatim** — colar o JSX/markup/classes/CSS da origem e trocar só os literais de conteúdo por `data.*`:
+
+```tsx
+// Padrão: componente com 'use client', recebe { data: SectionProps },
+// faz cast para o tipo tipado, e lê props via data.property.
+// O corpo do return é o MARKUP DA ORIGEM VERBATIM — mesmas tags, mesmas classes,
+// mesma animação. Só os literais (texto, src) viram leituras de `d`.
+'use client'
+import type { SectionProps, NomeSectionProps } from '@/lib/types'
+
+type Props = { data: SectionProps }
+
+export default function NomeSection({ data }: Props) {
+  const d = data as NomeSectionProps
+  // return ( <markup da origem, idêntico, com {d.titulo} no lugar do texto fixo> )
+}
+```
+
+Declarar o tipo correspondente em `frontend/src/lib/types.ts` com os aliases de propriedade do uSync.
+
+Registrar o módulo em `frontend/src/components/modules/moduleRegistry.ts`:
+
+```ts
+nomeSection: () => import('./NomeSection'),
+```
+
+### 5. Conectar o formulário ao backend de leads
+
+O template usa uma arquitetura de **multi-sink**: o backend seleciona automaticamente a integração correta pelo valor de `leadIntegration` configurado no nó `leadsConfig` do backoffice.
+
+**Sinks disponíveis no template:**
+
+| `Key` do sink | Classe | Integração |
+|---|---|---|
+| `ghl` | `GhlLeadSink` | GoHighLevel CRM |
+| `prospectpro` | `ProspectProLeadSink` | ProspectPRO |
+| `webhook` | `WebhookLeadSink` | Webhook HTTP genérico |
+
+O `LeadController` (`backend/Controllers/LeadController.cs`) recebe `IEnumerable<ILeadSink>` via DI e despacha para `sinks.FirstOrDefault(s => s.Key == cfg.Integration)`. Adicionar uma nova integração = implementar `ILeadSink` + uma linha no `LeadComposer.cs`.
+
+**Configuração pós-boot (nunca em código):**
+
+1. Acessar o backoffice em `http://localhost:5001/umbraco`.
+2. Navegar até o nó **Leads Config** (criado automaticamente pelo `SeedContentHandler`).
+3. Preencher:
+   - `Lead Integration`: selecionar `ghl` / `prospectpro` / `webhook`.
+   - `API Key` / `Webhook URL` / campos específicos da integração.
+4. Publicar o nó.
+
+O token nunca aparece no código-fonte nem em variáveis de ambiente — lido do cache publicado pelo `ReadConfig()` do controller via `IUmbracoContextFactory`.
+
+**Frontend:** o componente `ContactSection` (`frontend/src/components/modules/ContactSection.tsx`) faz POST para `/api/leads` (rota do Next.js que faz thin-proxy para `{NEXT_PUBLIC_UMBRACO_URL}/api/leads`). Nenhuma credencial no frontend.
+
+**Campos mínimos esperados pelo LeadController:** `name`, `email`, `phone`. Campos extras são aceitos no payload como propriedades livres e repassados ao sink.
+
+**Normalização de telefone:** aplicar máscara no frontend antes do POST para garantir o formato `+55XXXXXXXXXXX` — o GHL rejeita telefones sem DDI. O template tem o helper `LeadHelpers.NormalizePhoneBR()` no backend como fallback (idempotente: preserva o `+55` se já presente), mas normalizar no frontend evita ambiguidade.
+
+### 6. Gate de paridade — confirmar que ficou EXATAMENTE igual
+
+Objetivo: **provar** que a LP migrada é idêntica à origem. Com o lift verbatim (passo 4), os checks determinísticos abaixo passam **por construção** — se algum falha, é sinal de que o lift introduziu drift naquela seção; voltar e corrigir o lift, não "ajustar até parecer".
+
+**Hierarquia do gate:** os checks **determinísticos** (6b) são o **bloqueio**. O **screenshot diff** (6c) é **corroboração secundária** — nunca o bloqueio único, porque font hinting/antialiasing diferem entre ambientes mesmo com CSS byte-idêntico.
+
+#### 6a. Boot + checklist manual (sanidade)
+
+```bash
+docker compose up --build
+```
+
+Percorrer a página em `http://localhost:3000` e conferir, lado a lado com a origem: todas as seções na ordem certa, textos/mídias corretos, formulário visível, navegação e footer funcionando. Isso é só uma sanidade rápida antes dos checks automáticos.
+
+#### 6b. Checks determinísticos (o bloqueio)
+
+A skill **scaffolda** o harness de paridade no projeto destino (o template **não** o traz): criar `frontend/e2e/parity.spec.ts` e `frontend/compare-sections.mjs`. O harness compara `http://localhost:3000` (destino) contra a origem (URL de produção ou um build local da origem) e **falha** se qualquer dimensão divergir:
+
+1. **Estrutura DOM + nomes de classe** por seção — `compare-sections.mjs` extrai o esqueleto de tags+classes de cada `<section>`/`<nav>`/`<footer>` dos dois lados (agrupado por chave semântica/texto âncora) e aponta diferenças. Adaptar o array `KEYS` (`[nome, matchFn]`) aos textos âncora das seções do projeto.
+2. **Estilo computado** em elementos amostrados — para cada seção, comparar `getComputedStyle` de elementos-chave (cor, `font-family`, `font-size`, `font-weight`, paddings/margins, `border-radius`) origem × destino. Divergência = falha.
+3. **Checksum de assets** — o conjunto de `sha256` de todas as imagens/vídeos/fontes servidas pelo destino deve igualar o conjunto capturado da origem no passo 1. Asset reencode/otimizado quebra aqui (proposital).
+4. **Comportamento por interação** — uma asserção Playwright por comportamento capturado no passo 1 (scroll-expand, carrossel, marquee, autoplay de vídeo, hover, máscara/validação de telefone, submit do formulário com `/api/leads` mockado retornando `{"ok":true}`).
+
+```bash
+cd frontend
+npx playwright test            # roda parity.spec.ts + smoke (home.spec.ts do template)
+node compare-sections.mjs http://localhost:3000/ https://origem-em-producao.com.br/
+```
+
+#### 6c. Screenshot diff (corroboração secundária)
+
+Captura full-page origem × destino em múltiplos viewports (mobile/tablet/desktop). Para não gerar ruído:
+- **desabilitar animações** (`prefers-reduced-motion` / CSS de teste), **aguardar as web-fonts** (`document.fonts.ready`), **congelar vídeo/carrossel** num frame fixo;
+- usar **tolerância ciente de antialiasing** (ex.: `maxDiffPixelRatio` pequeno, threshold de cor).
+
+Um diff acima da tolerância é um **alerta para investigar** (provável seção com lift incompleto), não uma reprovação automática se os checks de 6b passam.
+
+#### 6d. Critérios de aceite
+
+A migração é "exata" quando **todos** são verdade:
+- **6b determinístico passa**: DOM+classes, estilo computado, checksum de assets e comportamento batem com a origem em todas as seções.
+- **6c screenshot diff** abaixo da tolerância em todos os breakpoints (mobile/tablet/desktop).
+- Todas as seções renderizam com conteúdo real (não placeholders) e na ordem da origem.
+- Formulário envia lead com sucesso para a integração configurada (testar com dado real em staging; `--demo-seed` popula a home com módulos de demonstração via `SEED_DEMO_CONTENT=true`, não envia lead de teste).
+- Backoffice: editar um campo de texto, publicar — a mudança reflete na página (revalidação por tag ou ISR) **sem** alterar o markup/estilo renderizado.
+- Nenhuma chave de API ou token aparece em arquivo versionado.
+
+## Anti-padrões
+
+- Não commitar `.env` nem nenhum arquivo com tokens ou senhas.
+- Não colocar credenciais de integração em variáveis de ambiente do container — elas pertencem ao nó `leadsConfig` no backoffice.
+- Não criar módulos novos com alias que conflite com os do template (verificar `lpHome.config` e os `.config` existentes antes de nomear).
+- Não usar `Guid.NewGuid()` em `SeedContentHandler` para o `Key` de um `mediaKey` que deve ser estável entre boots — calcular o GUID deterministicamente a partir do nome do arquivo ou recuperar o existente com `GetByKey`.
+- Não saltear o smoke-boot (passo 3) — problemas de ambiente devem ser detectados antes de portar conteúdo.
+- Não reutilizar `customHtmlSection` para tudo — módulos dedicados permitem edição granular no backoffice e ISR por tag.
+- **Não reinterpretar layout/CSS nem "limpar" o markup** — portar verbatim; o módulo Umbraco só embrulha o mesmo markup da origem. Rebuild = drift.
+- **Não reencodar nem otimizar assets** na migração — quebra a paridade de checksum (6b) e altera o render.
+- **Não assumir o tema do template** — portar o Tailwind/`@theme` (e as fontes) da origem; a mesma classe utilitária renderiza diferente entre versões/temas.
+- **Não tratar o screenshot diff como gate único** — o bloqueio são os checks determinísticos (6b); o diff visual é secundário.
+
+## Output esperado
+
+- `docs/origem-inventario.md` — inventário de seções, conteúdo, mídia e identidade visual da LP de origem.
+- `docs/mapeamento-modulos.md` — tabela de mapeamento seção → doctype/módulo com decisão (reuso direto / ajuste / lift verbatim).
+- `backend/uSync/v17/ContentTypes/*.config` — novos doctypes para os módulos lifted da origem.
+- `backend/Infrastructure/SeedContentHandler.cs` — seed idempotente com textos e mídia iniciais.
+- `backend/seed-assets/` — assets de seed (imagens, vídeos copiados da origem).
+- `frontend/src/components/modules/*.tsx` — componentes dos módulos novos.
+- `frontend/src/components/modules/moduleRegistry.ts` — atualizado com novos aliases.
+- `frontend/src/lib/types.ts` — tipos TypeScript para as props dos novos módulos.
+- `frontend/src/app/globals.css` — tema portado verbatim da origem (paleta + tipografia + fontes).
+- `frontend/e2e/home.spec.ts` — smoke test adaptado para o projeto.
+- `frontend/e2e/parity.spec.ts` — **gerado pela skill**: gate determinístico (DOM+classes, estilo computado, checksum de assets, comportamento) + screenshot diff.
+- `frontend/compare-sections.mjs` — **gerado pela skill**: comparação de esqueleto estrutural origem × destino.
+- `.env` gerado pelo `new-lp.sh` / `new-lp.ps1` — **não versionado** (`.gitignore`).
+
+## Referências
+
+Repo do template (privado, branch `master`): `polymorphism-tech/MORPH_Umbraco_LP_Template` — obtido automaticamente no passo 0.
+
+- `MORPH_Umbraco_LP_Template/scripts/new-lp.sh` e `new-lp.ps1` — scaffold de nova LP
+- `MORPH_Umbraco_LP_Template/backend/Lead/LeadComposer.cs` — registro dos sinks no DI
+- `MORPH_Umbraco_LP_Template/backend/Lead/ILeadSink.cs` — interface de integração de leads
+- `MORPH_Umbraco_LP_Template/backend/Controllers/LeadController.cs` — controller público + `ReadConfig()` + dispatch
+- `MORPH_Umbraco_LP_Template/backend/Lead/GhlLeadSink.cs`, `ProspectProLeadSink.cs`, `WebhookLeadSink.cs` — sinks concretos
+- `MORPH_Umbraco_LP_Template/backend/Infrastructure/SeedContentHandler.cs` — seed idempotente com mídia (MediaPicker3)
+- `MORPH_Umbraco_LP_Template/backend/uSync/v17/ContentTypes/lpHome.config` — doctype raiz da home (Block List `modules`)
+- `MORPH_Umbraco_LP_Template/frontend/src/components/modules/moduleRegistry.ts` — registro dos módulos
+- `MORPH_Umbraco_LP_Template/frontend/src/app/globals.css` — bloco `@theme` para portar o tema da origem
+- `MORPH_Umbraco_LP_Template/frontend/e2e/home.spec.ts` + `playwright.config.ts` — base de e2e (estender com `parity.spec.ts`)
+- `MORPH_Umbraco_LP_Template/docker-compose.yml` — orquestração backend + frontend com variáveis de ambiente

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "7.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-apply
@@ -15,7 +15,7 @@ Executar todas as tasks pendentes de uma feature até `done`, aplicando `morph-e
 
 ## Quando invocar
 
-- Após Gate 2 aprovado (verificar `.morph/state.json → features[X].approvalGates.plan === true`).
+- Após Gate 2 aprovado (verificar `.morph/features/{feature}/feature.json → approvalGates.plan.approved === true`).
 - Usuário pede "use /morph-apply {feature}" ou "implementar {feature}".
 
 ## Argumentos
@@ -26,7 +26,7 @@ Executar todas as tasks pendentes de uma feature até `done`, aplicando `morph-e
 
 - `.morph/features/{feature}/2-plan/tasks.json` existe e é válido (schema check).
 - `.morph/features/{feature}/2-plan/spec.md` e `mandate.md` existem.
-- Gate 2 está marcado aprovado no state.json (ou trust:auto está ativo).
+- Gate 2 está marcado aprovado no `feature.json` da feature (ou trust:auto está ativo).
 
 ## Fluxo
 
@@ -41,18 +41,26 @@ Executar todas as tasks pendentes de uma feature até `done`, aplicando `morph-e
 
 ### 2. Análise de DAG — decisão sequencial vs paralelo
 
-Construir o grafo de dependências e detectar subsets independentes.
+Construir o grafo de dependências e detectar fluxos de trabalho independentes. Há duas formas de paralelismo a detectar — e a segunda é a que mais aparece na prática:
+
+```js
+const groups = groupTasks(data); // { backend: [ids], frontend: [ids], tests: [...], infra: [...], docs: [...] }
+const independentRoots = data.tasks.filter(t => t.dependencies.length === 0);
+```
 
 **Regras de decisão:**
 
 1. Se `data.tasks.length <= 3`: **sequencial** (overhead de Agent dispatch não compensa).
-2. Identificar tasks **100% independentes** (`dependencies: []`):
-   - Se `>= 3` tasks independentes existem: dispachar essas em **paralelo**, depois cair em sequencial para o resto.
-3. Caso contrário: **sequencial puro** com auto-advance.
+2. **Fluxos de domínio independentes (o caso comum — backend ‖ frontend).** Use `groupTasks(data)` para separar as tasks por `group`. Dois grupos formam fluxos paralelos quando **nenhuma task de um grupo depende de uma task de outro grupo** (as cadeias só convergem, se convergirem, numa task final de integração). Se existem **≥ 2 fluxos de domínio independentes** — ex: a cadeia `backend` `T1→…→T11` e a cadeia `frontend` `T12→T13` não se cruzam até `T14` —, dispache **um sub-agent por fluxo, em paralelo**, cada um com a persona e o standard do seu domínio (ver passo 3b). Esse é exatamente o caso que a regra antiga de "≥3 raízes independentes" deixava passar (duas cadeias contam como 2 raízes, não 3).
+3. **Raízes independentes (fan-out na largura).** Identificar tasks **100% independentes** (`dependencies: []`). Se `independentRoots.length >= 3`: dispachar essas raízes em **paralelo**, depois cair em sequencial para o resto.
+4. Caso contrário: **sequencial puro** com auto-advance.
+
+> O cap de **4 agentes simultâneos** (anti-padrão abaixo) vale para ambas as formas. Se um fluxo de domínio é uma cadeia longa, despache o **fluxo inteiro** a um sub-agent (que executa a cadeia em ordem internamente) — um agente por fluxo, não um agente por task.
 
-Logar a decisão:
+Logar a decisão (mostre qual forma disparou):
 ```
-DAG analysis: 12 tasks, 4 independent → parallel batch (T1, T3, T7, T9) + sequential remainder
+DAG analysis: 14 tasks, groups {backend:9, frontend:2, tests:2, infra:1}; backend ‖ frontend independentes até T14 → 2 fluxos paralelos (1 agente backend, 1 agente frontend) + T14 sequencial no fim
+DAG analysis: 12 tasks, 4 raízes independentes → parallel batch (T1, T3, T7, T9) + sequential remainder
 ```
 
 ### 3a. Modo Sequencial (auto-advance)
@@ -68,39 +76,69 @@ while (true):
   updateTaskStatus(data, task.id, 'in_progress')
   writeTasksJson(tasksPath, data)
 
-  invoke Skill(morph-implement) with task
-
-  result = invoke Skill(morph-eval) with implementation output
-
-  if result.score >= 8:
+  // Loop de correção autônomo — a barra de qualidade é >= 9 (ver MORPH.md §0).
+  // Entre tasks NÃO há pausa humana: score < 9 dispara re-implementação, não AskUserQuestion.
+  attempt = 0
+  best = { score: 0, output: null }
+  while attempt < 3:
+    attempt += 1
+    invoke Skill(morph-implement) with task
+      (no attempt > 1: passar o feedback priorizado do morph-eval anterior como input)
+    result = invoke Skill(morph-eval) with implementation output
+    if result.score > best.score: best = result
+    // Persista o score no feature.json autoritativo da feature, sob taskScores — torna o
+    // evalScore um signal de disco no MOMENTO da implementação (não no fim). O hook
+    // gate-guard.js e o Gate 3 leem dali. Edit em .morph/features/** é permitido. Grave:
+    //   taskScores[task.id] = { lastScore: result.score, bestScore: best.score, attempts: attempt, updatedAt: <ISO> }
+    edit .morph/features/{feature}/feature.json com o taskScores acima
+
+    if result.score >= 9:
+      break
+
+  if best.score >= 9:
     updateTaskStatus(data, task.id, 'done')
   else:
-    // forçar pausa — qualidade é guardrail, trust não ignora aqui
-    AskUserQuestion: "Task {id} com score {score} — aceitar, reimplementar ou pular?"
-    options: [aceitar mesmo assim, reimplementar, pular task]
+    // 3 tentativas sem atingir 9 — AQUI sim escala ao humano (escape definido).
+    // Esta é a única pausa do loop de implement, e só após esgotar o loop de correção.
+    registrar em recap.md: as 3 tentativas e o melhor score (best.score) com o feedback
+    AskUserQuestion: "Task {id} não atingiu score 9 após 3 tentativas (melhor: {best.score}) — aceitar mesmo assim, continuar tentando, ou pular?"
+    options: [aceitar (marca done com ressalva no recap), continuar tentando (+3 tentativas), pular task (marca blocked)]
 
   writeTasksJson(tasksPath, data)
 ```
 
+> **Por que loop e não pausa:** MORPH.md §0 manda auto-avançar entre tasks. Score baixo numa task individual é um problema de qualidade que o modelo deve **corrigir sozinho**, não delegar ao humano no meio da implementação. A pausa só existe quando o loop de correção se esgota (3 tentativas) — o "escape" do modelo autônomo. O trust mode não muda esse loop: ele governa os **gates** (proposal/plan/review), não o ciclo de correção intra-task.
+
 ### 3b. Modo Paralelo (para o subset independente)
 
-Para cada task independente:
+**Antes de despachar, escope cada agente ao seu domínio.** Um agente genérico sem persona nem standard não "conhece" as convenções daquele domínio — produz código fora do padrão. Para cada fluxo/task a despachar, resolva:
+
+- **Persona:** em `agents.json`, encontre o agente cujo `domains` cobre o `group`/domínio da task (ex: `backend` → `dotnet-senior`, `frontend` → `nextjs-expert`/`ui-designer`, `database` → `ef-modeler`). Pegue o texto do campo `persona`.
+- **Standard(s):** do array `standards` desse mesmo agente em `agents.json` (e/ou do `mandate.md`), selecione o(s) path(s) `.md` relevante(s) à task.
+
 ```
 dispatch Agent (subagent_type: "general-purpose") with prompt:
+  persona: <texto do campo `persona` do agente de domínio em agents.json>
   contexto: spec.md, mandate.md, task description completa, doneCriteria
+  standard: <path(s) .md do(s) standard(s) do domínio — leia-o(s) antes de implementar>
   instrução: |
-    Implemente esta task isoladamente. Não modifique spec.md, mandate.md.
+    Adote a persona acima. Leia o(s) standard(s) indicado(s) antes de escrever código.
+    Implemente esta task (ou cadeia de tasks do fluxo) isoladamente.
+    Não modifique spec.md, mandate.md.
     Retorne:
       - sumário das mudanças
       - arquivos modificados (paths)
+      - standard(s) consultado(s)
       - auto-score 0-10 (rubric: completeness, correctness, mandate compliance)
 ```
 
+> Este template é deliberadamente paritário com o template sequencial em `morph-implement` §4: ambos passam **persona + standard escopados**. A única diferença é que aqui múltiplos agentes rodam ao mesmo tempo, um por fluxo independente.
+
 Aguardar todos os agentes terminarem (Promise.all equivalente). Depois, sequencialmente:
 - Para cada output retornado:
   - Aplicar `Skill(morph-eval)`.
-  - Se score >= 8: marcar `done`.
-  - Se score < 8: marcar `pending` novamente com nota — será re-executada no modo sequencial.
+  - Se score >= 9: marcar `done`.
+  - Se score < 9: marcar `pending` novamente com nota — volta ao modo sequencial, onde o loop de correção (até 3 tentativas) busca o score 9.
 
 Depois do batch paralelo, executar o restante em modo sequencial (passo 3a).
 
@@ -115,25 +153,29 @@ Quando `getPendingTasks(data).length === 0`:
 
 Sinais de risco para Gate 3:
 
-- Score médio < 8 no review-report.
+- Score médio < 9 no review-report.
 - Presença de erros não resolvidos.
 - Mudanças incidentais em standards/.morph/framework/.
 
 Mesma lógica do Gate 1/Gate 2 via `shouldPauseGate(config, signals)`:
 
+**Persista a decisão no `feature.json` autoritativo da feature ANTES de apresentar ou auto-aprovar** — grave
+`gateDecisions.review = { pause, reason, signals, trust, decidedAt: <ISO> }` em `.morph/features/{feature}/feature.json`
+(o `signals.evalScore` aqui é o score composto do review-report; Edit em `.morph/features/**` é permitido). O hook `gate-guard.js` confere depois se a ação bateu. Sem o registro o guard não verifica.
+
 - Pause: `AskUserQuestion` com options `["aprovado, fechar feature", "preciso ajustar", "rollback"]`.
-- Auto: exibir summary do review-report e prosseguir.
+- Auto: exibir summary do review-report, aprovar via `morph-spec approve {feature} review --mode auto`, e prosseguir.
 
 ### 6. Pós Gate 3
 
-- Atualizar `state.features[feature].status = "completed"` via state-sync (hook detecta "aprovado" em AskUserQuestion answer).
+- Aprovar o Gate 3: em auto, `morph-spec approve {feature} review --mode auto`; em manual, o hook state-sync registra a resposta "aprovado" em AskUserQuestion. O gate fica gravado no `feature.json` autoritativo da feature — nunca via Edit à mão de `state.json`.
 - Sinalizar: "Feature {nome} concluída. Rode `/morph-archive {feature}` para arquivar."
 - Não arquivar automaticamente.
 
 ## Anti-padrões
 
 - Não dispachar paralelo se há deps cruzadas entre as tasks selecionadas (corrompe ordem).
-- Não pular `morph-eval` — silêncio em score >= 8 é o sinal correto.
+- Não pular `morph-eval` — uma task só avança com score >= 9; abaixo disso, o loop de correção roda (não pausa).
 - Não reescrever spec.md/mandate.md durante implement (são read-only após Gate 2 — `protect-spec-files.js` hook bloqueia).
 - Não dispachar mais que 4 agentes em paralelo (sobrecarga de contexto + custo).
 
@@ -142,8 +184,8 @@ Mesma lógica do Gate 1/Gate 2 via `shouldPauseGate(config, signals)`:
 - Todas as tasks em `tasks.json` com status `done` ou `skipped`.
 - `.morph/features/{feature}/3-implement/recap.md` produzido por morph-implement.
 - `.morph/features/{feature}/4-review/review-report.md` produzido por morph-review.
-- Gate 3 marcado aprovado em `.morph/state.json` (via state-sync hook ou Edit direto).
-- `state.features[feature].status === "completed"`.
+- Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo) — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual.
+- Feature com Gate 3 aprovado e pronta para `morph-spec archive` (que carimba `status: "completed"` + `archivedAt`).
 
 ## Referências