@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

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.29.0"
+cliVersion: "8.32.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.29.0"
+cliVersion: "8.32.0"
 ---
 
 # morph-hotfix
@@ -109,7 +109,7 @@ morph-spec approve {feature} review --approver "<nome de quem aprovou>"
 ### 8. Pós-gate (o "test loop → ship" de `MORPH.md` §2.1)
 
 - Rode a suíte completa uma vez: `morph-spec verify {feature}` (sem escopo de task — cobertura da feature inteira, agora que o Gate 3 está aprovado).
-- Feche com `morph-spec finish {feature} --pr|--merge` — o mesmo encerramento único das demais features (arquiva commitando dentro de `morph/{f}`, integra, desmonta). Num hotfix urgente o `--merge` (local, direto na default) costuma ser o caminho; use `--pr` quando o fix precisa passar por CI/review antes do merge. Ver `MORPH.md` §2.2.
+- Feche com `morph-spec finish {feature} --pr|--merge` — o mesmo encerramento único das demais features (arquiva commitando dentro de `morph/{f}`, desmonta). Num hotfix urgente o `--merge` (local, direto na default, integra na hora) costuma ser o caminho; use `--pr` quando o fix precisa passar por CI/review antes do merge — mas `--pr` **não integra**: sai com `finished: true` e `integrated: false`, `awaiting: "merge"`. Um hotfix "fechado" por `--pr` ainda não chegou na produção — não relate o incidente como resolvido até o merge. Ver `MORPH.md` §2.2.
 - Não integre automaticamente — o usuário decide quando e por qual modo (`finish` toca a default ou o remoto). Feature legada sem `morph/{f}`: `finish` roteia para `morph-spec archive {feature}`.
 
 ## Anti-padrões

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.29.0"
+cliVersion: "8.32.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.29.0"
+cliVersion: "8.32.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.29.0"
+cliVersion: "8.32.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.29.0"
+cliVersion: "8.32.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
@@ -195,7 +202,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
    No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature — **a atribuição vem do nome da feature na pergunta** (o template acima o carrega). Pergunta sem nome, com mais de uma feature na árvore: o hook recusa a gravar e avisa; aprove então por `morph-spec approve {feature} review`. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
-   **Próximo passo (não é desta skill):** com o Gate 3 aprovado, a feature fecha por `morph-spec finish {feature} --pr|--merge` — a `morph-apply` §6 conduz a escolha PR vs merge. Não arquive nem integre aqui.
+   **Próximo passo (não é desta skill):** com o Gate 3 aprovado, a feature fecha por `morph-spec finish {feature} --pr|--merge` — a `morph-apply` §6 conduz a escolha PR vs merge. Não arquive nem integre aqui. **`--pr` não encerra a feature** — arquiva e termina, mas só integra no merge (`integrated: false`, `awaiting: "merge"` no payload); até lá a feature fica `aguardando-merge` em `morph-spec list`/`fleet`. `finished: true` não é sinônimo de entregue.
 
 ## Output esperado
 - `.morph/features/{feature}/4-review/evaluator-report.md` — relatório bruto e autoritativo do
@@ -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.29.0"
+cliVersion: "8.32.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.29.0"
+cliVersion: "8.32.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.29.0"
+cliVersion: "8.32.0"
 ---
 
 # morph-uiux

package/framework/standards/ai-agents/agent-session.md

@@ -1,160 +1,160 @@
-# Agent Session — Conversation state and chat reducers
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, AgentThread
-> **Read by Claude in:** implement
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Quando usar AgentSession
-
-Use `AgentSession` quando o agente é **conversacional** — há uma UI de chat que mantém histórico entre turnos do usuário.
-
-**Use AgentSession quando:**
-- Existe uma interface de chat (web, mobile, CLI interativo)
-- O agente precisa lembrar o que foi dito nos turnos anteriores da mesma conversa
-- Há perguntas de follow-up ("e agora?", "altere o segundo ponto", "lembra do que disse sobre X?")
-
-**NÃO use AgentSession quando:**
-- O agente é one-shot (gerador, executor, classificador) — recebe uma entrada, devolve uma saída, fim
-- Agentes stateless em pipeline multi-agent — cada chamada é independente
-- Jobs de batch/background — não há conversa; histórico não faz sentido
-
-> "Add Memory/Session because agents need state" é um anti-pattern de `sweet-spot.md`.
-> Só adicione quando uma UI de chat real existe.
-
----
-
-## A API
-
-**Pacote:** `Microsoft.Agents.AI` (base; já requerido por `ai-agents-setup`).
-
-**Tipos confirmados via context7:**
-- `AgentSession` — container leve de estado de conversa; obtido via `agent.CreateSessionAsync()`
-- `AgentThread` — equivalente para agentes persistentes (PersistentAgentsClient); use `agent.GetNewThread()`
-- `ChatClientAgentOptions` — aceita `ChatHistoryProvider` e `AIContextProviders`
-- `InMemoryChatHistoryProvider` — implementação embutida de histórico em memória
-- `AgentResponse` — tipo retornado por `AIAgent.RunAsync` (non-generic); acesse o texto via `.Text`
-
-```csharp
-// Construção do agente com histórico em memória
-AIAgent agent = _modelRegistry.GetChatClient("text-default")
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        ChatOptions = new() { Instructions = "You are a helpful assistant." },
-        ChatHistoryProvider = new InMemoryChatHistoryProvider(),
-    });
-```
-
----
-
-## Exemplo C# — agente conversacional com session persistente entre turnos
-
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-// ── 1. Registrar o agente conversacional no DI ──
-// Program.cs
-builder.Services.AddSingleton<AIAgent>(sp =>
-{
-    var registry = sp.GetRequiredService<ModelRegistry>();
-    return registry.GetChatClient("text-default")
-        .AsAIAgent(new ChatClientAgentOptions
-        {
-            ChatOptions = new() { Instructions = "You are a helpful customer support assistant." },
-            // InMemoryChatHistoryProvider: histórico vive em memória, por session.
-            // Seguro registrar como parte do singleton AIAgent: cada AgentSession criada via
-            // agent.CreateSessionAsync() isola o histórico de sua conversa — conversas distintas
-            // não compartilham estado. O provider em si é stateless; o estado fica na session.
-            // Para persistência entre restarts, substitua por um provider customizado (ex: DB).
-            ChatHistoryProvider = new InMemoryChatHistoryProvider(),
-        });
-});
-
-// ── 2. Criar uma session por conversa (ex: por conexão SignalR / por request de "start chat") ──
-// ChatController.cs ou ChatHub.cs
-public class ChatService(AIAgent _agent)
-{
-    // Uma session por conversa ativa — armazene no escopo do usuário (cache, memória da conexão)
-    public async Task<AgentSession> StartConversationAsync()
-        => await _agent.CreateSessionAsync();
-
-    // Cada mensagem do usuário passa a mesma session
-    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
-    {
-        AgentResponse response = await _agent.RunAsync(userMessage, session);
-        return response.Text;
-    }
-}
-
-// ── 3. Uso no controller/hub ──
-// Primeiro turno
-AgentSession session = await chatService.StartConversationAsync();
-string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
-// reply1: "Vou verificar o pedido #1234 para você..."
-
-// Segundo turno — o agente lembra do contexto anterior
-string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
-// reply2: "O pedido #1234 foi despachado em..."  ← contexto mantido pela session
-```
-
----
-
-## History management
-
-O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
-
-### Estratégias
-
-| Estratégia | Quando usar | Como implementar |
-|------------|-------------|------------------|
-| **Sliding window** | Conversas longas com contexto recente suficiente | Limitar `InMemoryChatHistoryProvider` a N mensagens mais recentes |
-| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados; truncar quando ultrapassa threshold |
-| **Summarization** | Histórico precisa de contexto antigo comprimido | Agente periódico que resume N turnos anteriores em uma mensagem única |
-
-> **Custom history management:** Para o caso comum, `InMemoryChatHistoryProvider` cobre a
-> necessidade de histórico em memória por sessão. Se o projeto exigir truncation customizada
-> (ex: sliding window limitando a N mensagens mais recentes ou por token budget), o mecanismo
-> de extensão correto — seja subclasse de `ChatHistoryProvider`, um `IChatReducer`, ou outro
-> ponto de override — deve ser verificado contra a versão instalada de `Microsoft.Agents.AI`.
-> Consulte a documentação MAF atual antes de implementar um provider customizado, pois a API
-> exata de extensão não foi confirmada na versão GA e pode variar entre releases.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Problema |
-|-------------|----------|
-| Adicionar session em agente one-shot (gerador, executor) | Complexidade desnecessária; estado nunca é usado |
-| Histórico ilimitado sem truncation | Context window estoura; custo aumenta linearmente com a conversa |
-| Compartilhar uma `AgentSession` entre múltiplos usuários | Histórico de um usuário vaza para outro |
-| Usar `InMemoryChatHistoryProvider` sem criar uma `AgentSession` por conversa | Sem `AgentSession` por conversa, o histórico é compartilhado entre todos os usuários; a isolation depende de `AgentSession` — sempre crie uma session por conversa via `agent.CreateSessionAsync()` |
-| Usar `AgentThread` (PersistentAgentsClient) sem necessidade | `AgentThread` requer hosted agent service; prefira `AgentSession` com direct model |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `AgentSession` usada somente em agentes conversacionais com UI de chat real
-- [ ] `InMemoryChatHistoryProvider` (ou equivalente) registrado em `ChatClientAgentOptions`
-- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
-- [ ] Estratégia de truncation definida (sliding window, token budget ou summarization)
-- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem session
-
----
-
-## References
-
-- `ai-agents-setup` — packages e DI base
-- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
-- `ai-agents-middleware-patterns` (Onda 2) — pipeline de contexto e middleware
-- MAF Conversations docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v1.0 (2026-05-19)*
+# Agent Session — Conversation state and chat reducers
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, AgentThread
+> **Read by Claude in:** implement
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar AgentSession
+
+Use `AgentSession` quando o agente é **conversacional** — há uma UI de chat que mantém histórico entre turnos do usuário.
+
+**Use AgentSession quando:**
+- Existe uma interface de chat (web, mobile, CLI interativo)
+- O agente precisa lembrar o que foi dito nos turnos anteriores da mesma conversa
+- Há perguntas de follow-up ("e agora?", "altere o segundo ponto", "lembra do que disse sobre X?")
+
+**NÃO use AgentSession quando:**
+- O agente é one-shot (gerador, executor, classificador) — recebe uma entrada, devolve uma saída, fim
+- Agentes stateless em pipeline multi-agent — cada chamada é independente
+- Jobs de batch/background — não há conversa; histórico não faz sentido
+
+> "Add Memory/Session because agents need state" é um anti-pattern de `sweet-spot.md`.
+> Só adicione quando uma UI de chat real existe.
+
+---
+
+## A API
+
+**Pacote:** `Microsoft.Agents.AI` (base; já requerido por `ai-agents-setup`).
+
+**Tipos confirmados via context7:**
+- `AgentSession` — container leve de estado de conversa; obtido via `agent.CreateSessionAsync()`
+- `AgentThread` — equivalente para agentes persistentes (PersistentAgentsClient); use `agent.GetNewThread()`
+- `ChatClientAgentOptions` — aceita `ChatHistoryProvider` e `AIContextProviders`
+- `InMemoryChatHistoryProvider` — implementação embutida de histórico em memória
+- `AgentResponse` — tipo retornado por `AIAgent.RunAsync` (non-generic); acesse o texto via `.Text`
+
+```csharp
+// Construção do agente com histórico em memória
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant." },
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+    });
+```
+
+---
+
+## Exemplo C# — agente conversacional com session persistente entre turnos
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// ── 1. Registrar o agente conversacional no DI ──
+// Program.cs
+builder.Services.AddSingleton<AIAgent>(sp =>
+{
+    var registry = sp.GetRequiredService<ModelRegistry>();
+    return registry.GetChatClient("text-default")
+        .AsAIAgent(new ChatClientAgentOptions
+        {
+            ChatOptions = new() { Instructions = "You are a helpful customer support assistant." },
+            // InMemoryChatHistoryProvider: histórico vive em memória, por session.
+            // Seguro registrar como parte do singleton AIAgent: cada AgentSession criada via
+            // agent.CreateSessionAsync() isola o histórico de sua conversa — conversas distintas
+            // não compartilham estado. O provider em si é stateless; o estado fica na session.
+            // Para persistência entre restarts, substitua por um provider customizado (ex: DB).
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+        });
+});
+
+// ── 2. Criar uma session por conversa (ex: por conexão SignalR / por request de "start chat") ──
+// ChatController.cs ou ChatHub.cs
+public class ChatService(AIAgent _agent)
+{
+    // Uma session por conversa ativa — armazene no escopo do usuário (cache, memória da conexão)
+    public async Task<AgentSession> StartConversationAsync()
+        => await _agent.CreateSessionAsync();
+
+    // Cada mensagem do usuário passa a mesma session
+    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
+    {
+        AgentResponse response = await _agent.RunAsync(userMessage, session);
+        return response.Text;
+    }
+}
+
+// ── 3. Uso no controller/hub ──
+// Primeiro turno
+AgentSession session = await chatService.StartConversationAsync();
+string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
+// reply1: "Vou verificar o pedido #1234 para você..."
+
+// Segundo turno — o agente lembra do contexto anterior
+string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
+// reply2: "O pedido #1234 foi despachado em..."  ← contexto mantido pela session
+```
+
+---
+
+## History management
+
+O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
+
+### Estratégias
+
+| Estratégia | Quando usar | Como implementar |
+|------------|-------------|------------------|
+| **Sliding window** | Conversas longas com contexto recente suficiente | Limitar `InMemoryChatHistoryProvider` a N mensagens mais recentes |
+| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados; truncar quando ultrapassa threshold |
+| **Summarization** | Histórico precisa de contexto antigo comprimido | Agente periódico que resume N turnos anteriores em uma mensagem única |
+
+> **Custom history management:** Para o caso comum, `InMemoryChatHistoryProvider` cobre a
+> necessidade de histórico em memória por sessão. Se o projeto exigir truncation customizada
+> (ex: sliding window limitando a N mensagens mais recentes ou por token budget), o mecanismo
+> de extensão correto — seja subclasse de `ChatHistoryProvider`, um `IChatReducer`, ou outro
+> ponto de override — deve ser verificado contra a versão instalada de `Microsoft.Agents.AI`.
+> Consulte a documentação MAF atual antes de implementar um provider customizado, pois a API
+> exata de extensão não foi confirmada na versão GA e pode variar entre releases.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Adicionar session em agente one-shot (gerador, executor) | Complexidade desnecessária; estado nunca é usado |
+| Histórico ilimitado sem truncation | Context window estoura; custo aumenta linearmente com a conversa |
+| Compartilhar uma `AgentSession` entre múltiplos usuários | Histórico de um usuário vaza para outro |
+| Usar `InMemoryChatHistoryProvider` sem criar uma `AgentSession` por conversa | Sem `AgentSession` por conversa, o histórico é compartilhado entre todos os usuários; a isolation depende de `AgentSession` — sempre crie uma session por conversa via `agent.CreateSessionAsync()` |
+| Usar `AgentThread` (PersistentAgentsClient) sem necessidade | `AgentThread` requer hosted agent service; prefira `AgentSession` com direct model |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AgentSession` usada somente em agentes conversacionais com UI de chat real
+- [ ] `InMemoryChatHistoryProvider` (ou equivalente) registrado em `ChatClientAgentOptions`
+- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
+- [ ] Estratégia de truncation definida (sliding window, token budget ou summarization)
+- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem session
+
+---
+
+## References
+
+- `ai-agents-setup` — packages e DI base
+- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
+- `ai-agents-middleware-patterns` (Onda 2) — pipeline de contexto e middleware
+- MAF Conversations docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v1.0 (2026-05-19)*