@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

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

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 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: "8.28.0"
+cliVersion: "8.31.0"
 stacks:
   - umbraco
 ---
@@ -35,6 +35,7 @@ O processo é reproduzível para qualquer LP (React/Vite, Next.js estático ou H
   - **(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.
+- **Se a origem é scroll-driven** (canvas frame-scrub, pin, parallax, smooth scroll), leia antes os standards `frontend/scroll-driven/frame-scrub.md`, `smooth-scroll.md` e `scroll-components.md`. Eles carregam o conhecimento que o lift precisa preservar; o passo 4e diz onde os assets dessa animação vivem no destino.
 
 ## Passo 0 — Obter o template (sempre)
 
@@ -192,15 +193,31 @@ O script:
 
 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:
+**Smoke-boot antes de qualquer customização** — boot limpo do template para confirmar que o ambiente funciona. Suba **na ordem**, backend primeiro, e só depois construa o frontend:
 
 ```bash
-docker compose up --build
+docker compose up -d backend
+# espere a Delivery API, não o backoffice (ver abaixo)
+until [ "$(curl -s -o /dev/null -w '%{http_code}' \
+  'http://localhost:5001/umbraco/delivery/api/v2/content?take=1')" = "200" ]; do sleep 5; done
+docker compose up --build -d frontend
 ```
 
-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.
+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 economiza horas.
 
-**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`.
+**Atenção (gotcha Build do Next.js):** o Dockerfile do frontend executa `next build` na imagem, e nesse momento o Next busca conteúdo via Delivery API para o SSG. Se a API não responder **conteúdo**, o build falha, e a mensagem que chega é só `npm run build ... exit code 1`, sem dizer que o problema é o backend. Por isso `docker compose up --build` sozinho, do zero, não é um comando confiável: ele constrói o frontend junto com o backend.
+
+> **O critério de prontidão é a Delivery API responder 200, nunca o backoffice.** Um healthcheck
+> que bate em `/umbraco` fica **healthy** enquanto `/umbraco/delivery/api/v2/content` ainda devolve
+> **500**: o backoffice sobe, o uSync importa, o seed grava, e a API só quebra quando alguém pede o
+> conteúdo. `depends_on: condition: service_healthy` apontando para o healthcheck errado dá uma
+> falsa sensação de ordem resolvida e o build do frontend morre mesmo assim. Aponte o healthcheck
+> do backend para a Delivery API.
+>
+> **E se ela devolver 500, não é questão de esperar mais.** Um 500 persistente na Delivery API com
+> banco recém-seedado é quase sempre **dado seedado no formato errado**, não lentidão de boot.
+> Aumentar timeout não resolve; vá para a seção "Gotchas de campo" e diagnostique pelo log do
+> Umbraco antes de seguir.
 
 ### 4. Lift verbatim — portar markup, mídia e tema
 
@@ -401,6 +418,33 @@ Registrar o módulo em `frontend/src/components/modules/moduleRegistry.ts`:
 nomeSection: () => import('./NomeSection'),
 ```
 
+#### 4e. Sequências de frames e assets de animação (LP scroll-driven)
+
+Se a origem tem hero (ou seção) com **canvas frame-scrub** (o scroll avançando um vídeo quadro a quadro), a animação atravessa a migração intacta, mas só se os assets forem para o balde certo. O modelo abaixo é o que roda em produção; foi decidido uma vez e não deve ser reaberto por engano.
+
+**Dois baldes, e a fronteira não é opinião:**
+
+| O quê | Onde | Editável no backoffice |
+|---|---|---|
+| Sequência de frames (`hero-frames/`, `oficio-frames/`), fontes, monograma da marca, ícones posicionais | `frontend/public/` | não, é asset estrutural |
+| Poster do scrub, fotos editoriais, logo, imagem de OG | `backend/seed-assets/` → Media Library → MediaPicker3 | sim |
+
+**Por que os frames não vão para a Media Library.** Três razões, em ordem de gravidade:
+
+1. O processamento on-the-fly do ImageSharp (`?format=webp`) exige URL assinada por HMAC, e no Umbraco 17 o HMAC não é relaxável por configuração. Uma sequência servida de `/media/` perde o webp e não tem como recuperá-lo no frontend headless.
+2. São 145 arquivos por sequência. Como requests assinadas ao backend, é um custo por visitante que não existe servindo de `/public`.
+3. O `SeedContentHandler` só enxerga `backend/seed-assets/` e o banco. Deixando os frames em `frontend/public/`, eles ficam fora do universo do seed: sobrevivem a re-seed, a re-import do uSync e a um `--reset-db` completo, sem nenhum tratamento especial.
+
+**O poster é o que fica editável.** É ele que aparece no mobile e sob `prefers-reduced-motion`, então é o único da dupla que o cliente tem motivo para trocar. Frames fixos, poster no MediaPicker.
+
+**Cache-bust é obrigatório e manual.** `frontend/public/` não recebe hash de build (o Dockerfile copia o diretório verbatim e o Next só versiona `.next/static`), então reextrair frames mantendo os mesmos nomes serve os bytes antigos de qualquer cache intermediário. O `framePath` carrega um `?v=N` que sobe a cada reextração:
+
+```ts
+const framePath = (i: number) => `/hero-frames/frame_${String(i).padStart(3, '0')}.jpg?v=2`
+```
+
+**No lift, não trocar a lib de animação.** O template não traz `gsap` nem `lenis`; se a origem usa, adicione ao `frontend/package.json` do destino. Portar o registry de motion e o runtime de scroll como componentes `'use client'`, com o guard de SSR no registro do ScrollTrigger (ele toca `document`) e o runtime montado uma vez na page. Detalhe completo em `frontend/scroll-driven/smooth-scroll.md` e `frontend/scroll-driven/frame-scrub.md` no acervo de standards.
+
 ### 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.
@@ -446,8 +490,12 @@ Objetivo: **provar** que a LP migrada é idêntica à origem. Com o lift verbati
 
 #### 6a. Boot + checklist manual (sanidade)
 
+Mesma ordem do passo 3: backend primeiro, Delivery API respondendo 200, e só então o frontend.
+
 ```bash
-docker compose up --build
+docker compose up -d backend
+until [ "$(curl -s -o /dev/null -w '%{http_code}' 'http://localhost:5001/umbraco/delivery/api/v2/content?take=1')" = "200" ]; do sleep 5; done
+docker compose up --build -d frontend
 ```
 
 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.
@@ -459,7 +507,27 @@ A skill **scaffolda** o harness de paridade no projeto destino (o template **nã
 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}`).
+4. **Comportamento por interação** — uma asserção Playwright por comportamento capturado no passo 1 (scroll-expand, **canvas frame-scrub**, carrossel, marquee, autoplay de vídeo, hover, máscara/validação de telefone, submit do formulário com `/api/leads` mockado retornando `{"ok":true}`).
+
+> **Scrub e qualquer efeito dirigido por scroll se verificam COM MOVIMENTO.** Um screenshot
+> estático não distingue um scrub vivo de um canvas quebrado: o canvas pode estar 1x1 desenhando
+> um pixel esticado, ou ignorando o scroll por completo, e a foto continua plausível. Dirija o
+> scroll e compare o que foi desenhado em posições diferentes:
+>
+> ```js
+> const lenis = window.__lenis
+> const h = document.querySelector('header.hero-scrub').getBoundingClientRect().height
+> for (const p of [0, .15, .3, .45, .6, .8, 1]) {
+>   lenis.scrollTo(Math.round((h - innerHeight) * p), { immediate: true })
+>   await new Promise(r => setTimeout(r, 350))   // deixa o scrub:0.4 assentar
+>   // capture aqui: screenshot, ou uma assinatura de pixels via ctx.getImageData
+> }
+> ```
+>
+> A espera não é opcional: com `scrub: 0.4` o desenho não salta, e sem ela você fotografa o frame
+> anterior. **Critério de aprovação:** as capturas diferem entre si. Todas iguais significa scrub
+> morto, mesmo que a página pareça correta. Confirmar também que os frames respondem 200 com o
+> `?v=N` em uso e que os beats de texto trocam ao longo do percurso.
 
 ```bash
 cd frontend
@@ -487,6 +555,22 @@ A migração é "exata" quando **todos** são verdade:
 - `robots.txt`/`sitemap.xml` de produção apontam pro domínio real (não o placeholder `minha-landing-page.com.br` do template) — só acontece se `NEXT_PUBLIC_SITE_URL` foi setada como Build Variable no provedor.
 - Nenhuma chave de API ou token aparece em arquivo versionado.
 
+## Gotchas de campo
+
+Furos que já custaram build quebrado ou deploy revertido em migração real. Nenhum deles aparece como erro óbvio no caminho feliz.
+
+**Property editor guarda JSON, não escalar. Seedar string crua derruba a Delivery API inteira.** `Umbraco.DropDown.Flexible` persiste **array JSON mesmo com `Multiple: false`**. Dentro do JSON de um Block List a tentação é escrever `"ctaAcao": "ancora"` como qualquer outro campo do bloco; o correto é `["ancora"]`. O erro não fica no campo: a exceção sobe pelo `BlockListPropertyValueConverter` e **derruba o documento inteiro** (500 na home), o que mata o `next build` com SSG e chega até você como `npm run build ... exit code 1`. Só aparece com banco novo, então passa despercebido até o primeiro `--reset-db` ou deploy limpo.
+
+Regra, diagnóstico pela letra citada no `JsonException` e o procedimento de A/B estão em `references/umbraco-lp-patterns.md` (seção 6) da skill `create-umbraco-lp`, instalada em `.claude/skills/create-umbraco-lp/`. Leia essa seção antes de seedar qualquer dropdown.
+
+**MediaPicker3 sempre volta array, mesmo em single-pick.** Na Delivery API, todo campo de mídia chega como array (`poster`, `logo`, `favicon`, `imageSeo`, `modalLogo`), embutido sem `expand`. Acessar `campo.url` direto funciona enquanto o campo está vazio e passa a estourar no instante em que um editor o preenche. Pior: em `generateMetadata` o Next trata a exceção como fatal e derruba o build inteiro, então o sintoma é um deploy que quebra sozinho depois de alguém publicar no backoffice, sem nenhuma mudança de código. Tipar como `UmbracoImage[]` e indexar em `[0]`, sempre com fallback para o asset estático de `/public`.
+
+**Label de Block List aninhado usa UFM.** O backoffice do Umbraco 17 (Bellissima) renderiza o label do bloco com Umbraco Flavored Markdown, `{=alias}`, e não com o `{{ alias }}` do backoffice AngularJS antigo. Com a sintaxe velha o header do bloco mostra a chave literal para o editor. É só display do backoffice, não afeta o render da LP, e por isso passa despercebido em toda validação automática.
+
+**Reverse proxy e bind do Next.** Atrás de Traefik ou Coolify, o backend precisa de `UseForwardedHeaders` (X-Forwarded-Proto/For), senão o OpenIddict do backoffice não vê HTTPS e o login em `/umbraco` falha com `ID2083: This server only accepts HTTPS requests`. E o runner do frontend precisa de `HOSTNAME=0.0.0.0`: sem isso o `server.js` do Next standalone faz bind no id do container, o healthcheck via `localhost:3000` nunca passa, o container nunca fica healthy e o deploy dá rollback sem erro de aplicação nenhum.
+
+**Antes de escrever qualquer um destes, confira se o template já resolveu.** Correções são portadas do projeto de volta para o `MORPH_Umbraco_LP_Template`, então parte desta lista pode já estar no scaffold que o passo 0 baixou. Ensinar de novo uma correção existente cria divergência.
+
 ## Anti-padrões
 
 - Não commitar `.env` nem nenhum arquivo com tokens ou senhas.
@@ -531,3 +615,4 @@ Repo do template (privado, branch `master`): `polymorphism-tech/MORPH_Umbraco_LP
 - `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
+- `.claude/skills/create-umbraco-lp/references/umbraco-lp-patterns.md` — padrões e gotchas do template (controller público, multi-sink, leitura server-side, segurança da Delivery API, uSync, **dropdown como JSON array (seção 6)**, seed idempotente, build do Next.js exigindo backend). Instalado junto com a skill irmã; carregue sob demanda.

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: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-apply
@@ -143,11 +143,20 @@ while (true):
 
 ```
 dispatch Agent (subagent_type: "morph-{id}") with prompt:
-  contexto: spec.md, mandate.md, task description completa, doneCriteria
+  contexto: spec.md, mandate.md, task description completa, doneCriteria,
+            task.reuse (veredito REUSAR/ESTENDER/CRIAR por conceito) e os paths
+            dos alvos de reuso
   standard: <path(s) .md do(s) standard(s) do domínio — leia-o(s) antes de implementar>
   instrução: |
     Leia o(s) standard(s) indicado(s) antes de escrever código.
-    Implemente esta task (ou cadeia de tasks do fluxo) isoladamente.
+    Implemente esta task (ou cadeia de tasks do fluxo) sem depender do trabalho
+    dos outros agentes deste batch: seu ISOLAMENTO é de ESTADO e de ÁRVORE DE
+    TRABALHO — nunca de conhecimento do codebase. Antes de criar tipo,
+    componente, hook ou serviço NOVO, verifique se já existe: `morph-spec graph
+    explain <nome>` e `graph affected <conceito> --uses-only`; sem grafo
+    (`no-graph`), caia para `grep -rn "<nome>"` e siga — a ausência de grafo
+    nunca bloqueia. Se algo cobre o caso, reuse ou estenda; se criar mesmo
+    assim, diga por que em uma linha no relatório.
     Não modifique spec.md, mandate.md.
 
     Contrato do relatório final:

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

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-brainstorming

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

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-eval

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

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-hotfix

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

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-implement
@@ -60,9 +60,19 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
 
    Spec: [description completa do tasks.json]
    Standard: [path do .md do standard identificado no passo 2]
-   Arquivos relevantes: [lista de paths]
+   Arquivos relevantes: [os `target` de task.reuse + o que o scout/grafo apontou
+     — este campo não é decorativo: é por ele que o código já existente chega
+     ao sub-agente, que trabalha em contexto fresco e não conhece o projeto]
+   Reuso: [task.reuse do tasks.json — `CONCEITO: VEREDITO → alvo`, uma linha por
+     conceito; ausente numa task que não introduz conceito]
    Done quando: [doneCriteria do tasks.json]
 
+   Antes de criar tipo, componente, hook ou serviço NOVO, verifique se já
+   existe: `morph-spec graph explain <nome>` e `graph affected <conceito>
+   --uses-only`. Sem grafo (`no-graph`), caia para `grep -rn "<nome>"` e siga —
+   a ausência de grafo nunca bloqueia. Se algo cobre o caso, reuse ou estenda;
+   se criar mesmo assim, diga por que em uma linha no relatório.
+
    Contrato do relatório final:
    1. GRAVE `.morph/features/{feature}/3-implement/reports/[ID].md` ANTES de
       encerrar — é o retorno autoritativo, não a sua mensagem final (que é

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

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-plan
@@ -24,6 +24,41 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
 1. **Garanta que `proposal.md` e `stack-scan.md` estão no seu contexto antes de planejar.** Se não tem o conteúdo atual em contexto (sessão fresca, ou conteúdo possivelmente desatualizado), **use a tool Read para carregá-los** — não confie em cache de turnos anteriores. Na dúvida, Read. `.morph/features/{feature}/0-proposal/proposal.md` (problema, escopo, riscos — o comportamento é destilado aqui no passo 2, não vem pronto do proposal) e `.morph/features/{feature}/0-proposal/stack-scan.md` (contexto técnico detectado: greenfield vs brownfield, stack atual, drift). Em brownfield, o stack-scan informa decisões de spec/mandate — não invente padrões que conflitam com o detectado.
 
+1b. **Scout — mapa do território antes de planejar (opcional, mas o default em feature grande ou brownfield).** É o call-site do "scout opcional antes do plan" que a MORPH.md promete. Dispare quando a feature toca área que você não tem em contexto, ou quando o `stack-scan.md` acusou brownfield com desvios.
+
+   ```
+   subagent_type: "morph-scout"
+   ```
+
+   Peça: os arquivos que a feature vai tocar, o blast radius dos símbolos centrais dessa área e o que quebra junto. O scout começa por `morph-spec graph affected|explain` e **cai para grep sozinho quando não há grafo** — nunca trate a ausência de grafo como impedimento para planejar.
+
+   **Fallback** (se `morph-scout` não estiver registrado nos subagent types deste projeto): `general-purpose` com o campo `persona` do agente `scout` colado no prompt (Read em `.morph/framework/agents.json`), registrando o fallback no `decisions.md`.
+
+   Pular o scout é aceitável em feature pequena dentro de domínio já carregado — nesse caso **registre a decisão em uma linha no `decisions.md`**.
+
+1c. **Mapa de reuso — o que desta feature JÁ EXISTE no codebase.** Antes de destilar os use cases, responda por conceito: *isto já está implementado?* É o passo que falta hoje e cujo efeito é medido — 17 duplicações intra-feature no ProspectPRO, `SimpleBuilding` redefinido em cinco arquivos da MESMA pasta, um deles já sem um campo. Sem este passo, quem implementa não tem como saber, e o framework nunca pergunta.
+
+   **Insumos, nesta ordem:**
+   1. **O grafo** — para cada conceito central (entidade, DTO, componente, hook, serviço, helper) que a feature vai introduzir: `morph-spec graph explain <nome-candidato>` (existe? onde?) e `morph-spec graph affected <conceito> --uses-only` (quem usa de verdade, sem contar quem só implementa).
+   2. **O inventário do projeto** — `.morph/context/README.md` (gerado por `morph-spec context refresh`): entidades, endpoints com método e rota, páginas e **componentes com path**. É a granularidade de *conceito* que o grafo, que casa por símbolo, não dá. **Este passo é o consumidor declarado desse arquivo** — se ele não existir, rode `morph-spec context refresh` ou siga sem ele.
+   3. **Sem grafo** (`no-graph`, projeto sem Python) — **caia para `grep -rn "<nome-candidato>"` no diretório de código e siga**; a ausência de grafo nunca bloqueia o plano (ADR-002). Registre a queda no `decisions.md`.
+
+   **Produza `.morph/features/{feature}/2-plan/reuse-map.md`** — artefato, não prosa solta:
+
+   ```markdown
+   | Conceito | Já existe? | Onde | Decisão |
+   |---|---|---|---|
+   | SimpleBuilding | SIM (5×) | features/roulette/types/roulette.types.ts | REUSAR |
+   | FilterValues | SIM (ambíguo) | dashboard + leads + store | ESTENDER o de dashboard |
+   | RouletteScore | NÃO | — | CRIAR — nenhum tipo cobre pontuação por sorteio |
+   ```
+
+   **`CRIAR` exige justificativa em uma linha, na própria célula** — a mesma forma que `morph-uiux` §"Consistência" já impõe para token de design (*"um token novo precisa de justificativa: o existente não cobre o caso"*). Sem a justificativa, o veredito não vale.
+
+   **Distinga "extrair para shared" de "importar de outra feature".** Reuso não é desculpa para acoplar slices: se o conceito é de duas features, o alvo é um módulo comum, não um import cruzado — a rubrica `architecture` penaliza dependência cross-feature e continua valendo.
+
+   O veredito viaja para o implementador pelo campo `reuse` de cada task (passo 5). Quem cobra o resultado é o `morph-spec verify`: o validador `reuse` acusa símbolo novo cujo nome já existe no grafo, na mesma linguagem — **intra-feature reprova**, cross-feature avisa, e um `CRIAR` declarado no plano rebaixa o achado a aviso.
+
 2. **Destile os use cases — ANTES de escrever `spec.md` e `tasks.json`.**
 
    Um arquivo por use case em `.morph/features/{feature}/2-plan/usecases/UC-{nn}-{slug}.md`:
@@ -87,7 +122,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 4. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
    - Stack exata do projeto (leia de `.morph/config/config.json` → `project.stack` ou do CLAUDE.md).
    - Standards obrigatórios: descubra-os com `morph-spec standards --find "<domínio/tecnologia>"` (top 3 `id · path · digest` — o digest decide) por domínio tocado; liste os IDs escolhidos.
-   - Patterns proibidos — **copie por extenso no mandate.md** a lista canônica de `MORPH.md` § "Stack baked-in" (`Guid.NewGuid()`→`Guid.CreateVersion7()`, 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) mais qualquer proibição específica da feature. Copie o texto completo — o mandate.md é lido por implementadores em contexto fresco, sem `MORPH.md` carregado, então um ponteiro sozinho não basta aqui.
+   - Patterns proibidos — **copie por extenso no mandate.md** a lista canônica de `MORPH.md` § "Stack baked-in" (`Guid.NewGuid()`→`Guid.CreateVersion7()`, 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, redeclarar tipo/componente que já existe na mesma feature) mais qualquer proibição específica da feature. Copie o texto completo — o mandate.md é lido por implementadores em contexto fresco, sem `MORPH.md` carregado, então um ponteiro sozinho não basta aqui.
    - Política de acesso a dados (registre no mandate): `ApplicationDbContext` injetado direto no slice — para CRUD e para queries específicas (joins, projeção, paginação). Para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
    - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `.morph/framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via `morph-spec standards --find "<tema>" --category ai-agents`. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - **Verificação de runtime** — como se PROVA que a feature funciona rodando, não só compilando.
@@ -146,7 +181,8 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
          "group": "backend",
          "usecase": "UC-07",
          "agent": "dotnet-senior",
-         "standards": ["standards/backend/dotnet/vsa-handler-patterns.md"]
+         "standards": ["standards/backend/dotnet/vsa-handler-patterns.md"],
+         "reuse": [{ "concept": "SimpleBuilding", "verdict": "REUSAR", "target": "features/roulette/types/roulette.types.ts" }]
        }
      ]
    }
@@ -161,12 +197,15 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    - `outputs` (opcional): array de paths que serão criados/modificados.
    - `usecase` (opcional): o **ID** do use case que a task realiza — `UC-07`, nunca o nome do arquivo. Task puramente técnica (build, config, migração) não tem.
    - `agent` (opcional): o `id` da persona de `agents.json` responsável pelo domínio da task — **sem** o prefixo `morph-` (ex.: `"dotnet-senior"`, não `"morph-dotnet-senior"`). Carimbado no passo 5a abaixo; ausente numa task sem domínio de agente claro (config/docs) ou num plano legado.
+   - `reuse` (opcional): os vereditos do `reuse-map.md` (passo 1c) que ESTA task realiza — `[{concept, verdict: REUSAR|ESTENDER|CRIAR, target}]`. Só nas tasks que tocam o conceito; task que não introduz conceito nenhum não tem. **A justificativa do CRIAR fica no `reuse-map.md`, não aqui** — o mesmo fato escrito em dois lugares diverge. É este campo que o `morph-spec verify` lê para saber se a criação de um símbolo homônimo foi decidida no Gate 2 ou aconteceu por descuido.
    - `standards` (opcional): array de paths relativos de `.morph/framework/standards/` (ex.: `["standards/backend/dotnet/vsa-handler-patterns.md"]`) — os standards da persona resolvida em `agent`, mais qualquer standard específico que a task exija.
 
    **5a. Carimbe `agent` e `standards` — uma leitura de `agents.json`, N tasks.** Antes de fechar o array `tasks`, **use a tool Read UMA VEZ** em `.morph/framework/agents.json` (não releia por task — é essa releitura repetida por task, hoje feita em `morph-implement`/`morph-apply` a cada dispatch, que este passo existe para eliminar). Para cada task do plano, resolva:
    - `agent`: o `id` da persona (chave do objeto `agents`, sem prefixo `morph-`) cujo `domains` cobre o `group`/domínio da task — o mesmo casamento que `morph-implement` §3 e `morph-apply` §3b fariam manualmente a cada dispatch; aqui você faz uma vez, no plano.
    - `standards`: o array `standards` dessa persona, mais qualquer standard adicional que a task especificamente exija (some, não substitua).
 
+   **5b. Carimbe `reuse` — do `reuse-map.md` para a task que realiza o conceito.** Para cada linha do mapa produzido no passo 1c, encontre a task que vai escrever aquele conceito e copie o veredito para `reuse` (`concept` + `verdict` + `target`). Um conceito sem task é sinal de plano incompleto — ou o mapa listou o que a feature não vai tocar, ou falta task. Resolva antes do Gate 2.
+
    **Task que cria ou altera superfície de UI** (componente, página, estilo, fluxo de navegação) carimba `agent: "ui-designer"` — inclusive numa feature que não tomou o ramo uiux (MORPH.md §2.1): o critério de agente é por domínio da task, não por fase percorrida.
 
    Uma task cujo domínio não bate com nenhuma persona registrada (ex.: task pura de config/docs) fica sem `agent` — `morph-implement` cai no fallback de Read de `agents.json` nesse caso.
@@ -226,6 +265,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 - `.morph/features/{feature}/2-plan/usecases/UC-{nn}-{slug}.md` — um arquivo por use case, com pós-condições testáveis
 - `.morph/features/{feature}/2-plan/spec.md` — especificação técnica completa
 - `.morph/features/{feature}/2-plan/mandate.md` — contrato de implementação
+- `.morph/features/{feature}/2-plan/reuse-map.md` — veredito REUSAR/ESTENDER/CRIAR por conceito, com justificativa de uma linha em cada CRIAR (passo 1c)
 - `.morph/features/{feature}/2-plan/tasks.json` — task list estruturada válida contra schema, com o `doneCriteria` carregando a pós-condição literal e, por task, `agent`/`standards` carimbados a partir de `agents.json` (passo 5a)
 - Gate 2 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo)
 
@@ -237,6 +277,8 @@ Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de
 - `morph-spec standards --find "<query>"` — para identificar standards relevantes ao mandate (o índice inteiro só como navegação exploratória; ver `morph-standards`)
 - `.morph/framework/agents.json` — personas por domínio; lido UMA VEZ no passo 5a para carimbar `agent`/`standards` por task
 - `.morph/framework/schemas/tasks.schema.json` — schema obrigatório de tasks.json
+- `morph-spec graph explain|affected --uses-only` — "isto já existe?" e "quem usa de verdade" (passo 1c); **sem grafo, o fallback é `grep -rn`**
+- `.morph/context/README.md` — inventário do projeto (entidades, endpoints, componentes com path); insumo declarado do passo 1c, atualizado por `morph-spec context refresh`
 - `.morph/specs/usecases/` — acervo permanente de use cases do projeto (`usecase reserve` já lê antes de numerar; em `bug`, é onde mora o UC a corrigir)
 - `.morph/features/{feature}/0-proposal/proposal.md` — escopo da feature
 - `.morph/features/{feature}/0-proposal/stack-scan.md` — contexto técnico detectado

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-proposal

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

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-review
@@ -72,12 +72,19 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    - **Confira também `traceability.warnings`** (advisory, nunca faz `verify` falhar): cada entrada é
      um arquivo citado no `recap.md` sem task dona em `outputs` — repasse ao avaliador como sinal de
      rastreabilidade para a dimensão de qualidade, não como bloqueio automático do gate.
+   - **Anexe o `reuse-map.md`** (`.morph/features/{feature}/2-plan/reuse-map.md`), quando existir: é o
+     que o plano decidiu por conceito (REUSAR/ESTENDER/CRIAR) e o único insumo que permite ao
+     avaliador julgar a dimensão `code-quality` **contra o codebase**, não só contra o diff — símbolo
+     recriado não aparece no diff como problema. Junto dele, repasse os achados do validador `reuse`
+     do nó `validators` do verify. Sem `reuse-map.md` (plano anterior a este passo), diga isso ao
+     avaliador em vez de deixá-lo supor que não havia conceito a reusar.
    - Gere o **diff da implementação** (`git diff` do range da feature, ou a lista de arquivos do recap.md com seus conteúdos atuais).
+   - **Blast radius dos símbolos do diff (se houver grafo).** Para cada símbolo público que o diff tocou, rode `morph-spec graph affected <símbolo> --prod --json` e inclua o resultado no contexto do avaliador. É o que permite perguntar *"o que esta mudança pode ter quebrado FORA do diff"* sem que o avaliador leia o repositório inteiro. **Fallback:** `no-graph`, `not-found` ou `ambiguous` — siga sem o blast radius e **registre a ausência na seção de método do review-report**; o gate não depende disso. **Trate o resultado como possivelmente stale:** o rebuild do hook é assíncrono, então logo depois de um commit o grafo ainda é o anterior. E lembre que em frontend ele responde "quem importa", não "quem chama".
    - Despache o subagent registrado `morph-evaluator` (gerado de `agents.json` — a persona do avaliador é o system prompt dele, com Read/Glob/Grep + Bash somente para verificação + Playwright para navegar, sem Write/Edit), com contexto fresco:
      ```
      dispatch Agent (subagent_type: "morph-evaluator") with prompt:
-       contexto: mandate.md + spec.md + diff da implementação + saída real dos testes
-                 + nó e2e do verify (stack no ar? em qual URL?)
+       contexto: mandate.md + spec.md + reuse-map.md + diff da implementação
+                 + saída real dos testes + nó e2e do verify (stack no ar? em qual URL?)
        instrução: |
          Você NÃO participou da implementação — avalie o que está no diff,
          contra o mandate. NÃO leia `4-review/evaluator-report.md` neste
@@ -207,6 +214,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
 ## Referências
 - `morph-spec verify {feature} [task] --json` — cadeia determinística build+testes+validadores+e2e anexada ao prompt do avaliador (passo 4)
+- `.morph/features/{feature}/2-plan/reuse-map.md` — veredito de reuso por conceito; insumo do avaliador para julgar `code-quality` contra o codebase
 - `.morph/framework/MORPH.md` — seção 5 (Gate 3 + regras de pausa), seção 1 (papel Evaluator), Trust Mode
 - `.claude/agents/morph-evaluator.md` — subagent do avaliador (gerado de `.morph/framework/agents.json`), despachado no passo 4
 - `.claude/skills/morph-eval/SKILL.md` — rubricas e bandas que o avaliador aplica

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

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-stack-scan
@@ -60,6 +60,18 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
 
 ## 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:
 
    ```

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

@@ -4,7 +4,7 @@ description: Localiza um standard específico via busca server-side (morph-spec
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-standards

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

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.28.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-uiux

package/framework/standards/PROVENANCE.json

@@ -0,0 +1,41 @@
+{
+  "version": "1.0.0",
+  "_note": "Standards distilled from an external source. The source is not a dependency at runtime: it lives in another repository and is not needed to use the framework. This file exists so drift is detectable instead of silent. Pin `sourceTree` when distilling, and re-pin deliberately after reviewing what changed. See test/framework/standards-provenance.test.js.",
+  "sources": [
+    {
+      "id": "morph-lp-cinematic",
+      "repo": "morph-HUB",
+      "path": "skills/morph-lp-cinematic",
+      "envVar": "MORPH_HUB",
+      "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
+      "sourceTree": "e43114d4b28ff55680a5355cce27d31ffa74f22f",
+      "sourceCommit": "465c9b0",
+      "distilledOn": "2026-08-21",
+      "distilledFrom": [
+        "references/build-stack.md",
+        "references/component-recipes.md",
+        "references/premium-finish.md",
+        "references/seo-and-qa.md",
+        "references/gemini-image-prompt.md",
+        "references/seedance-scrub-prompt.md",
+        "references/seedance-loop-prompt.md"
+      ],
+      "notDistilled": [
+        "references/gates.md",
+        "references/last-mile.md",
+        "references/copy-and-messaging.md",
+        "references/section-blueprint.md"
+      ],
+      "notDistilledReason": "Deliberate split: a standard carries knowledge, a skill carries process. HITL gates, deploy and copy strategy stay with the skill.",
+      "standards": [
+        "frontend-scroll-driven-frame-scrub",
+        "frontend-scroll-driven-smooth-scroll",
+        "frontend-scroll-driven-scroll-components",
+        "frontend-design-system-premium-finish",
+        "frontend-design-system-ai-image-generation",
+        "frontend-design-system-ai-video-generation",
+        "frontend-seo-meta-schema-audit"
+      ]
+    }
+  ]
+}