@polymorphism-tech/morph-spec 8.29.0 → 8.31.0

package/framework/hooks/git/pre-push/run-tests.sh

@@ -1,44 +1,44 @@
-#!/usr/bin/env bash
-# Scope: universal | Runs test suite before push
-# MORPH-SPEC Pre-Push Hook
-# Ensures all tests pass before pushing to remote
-
-echo "🧪 Running test suite before push..."
-echo ""
-
-# Detect project type and run appropriate tests
-if [[ -f *.csproj ]] || find . -maxdepth 2 -name "*.csproj" 2>/dev/null | grep -q .; then
-  # .NET project detected
-  echo "📦 Detected .NET project"
-
-  if ! dotnet test --verbosity minimal --no-build --no-restore 2>/dev/null; then
-    echo ""
-    echo "❌ .NET tests failed!"
-    echo ""
-    echo "Fix failing tests before pushing."
-    echo "Override with: git push --no-verify"
-    exit 1
-  fi
-
-elif [[ -f package.json ]]; then
-  # Node.js project detected
-  echo "📦 Detected Node.js project"
-
-  if ! npm test 2>/dev/null; then
-    echo ""
-    echo "❌ Node.js tests failed!"
-    echo ""
-    echo "Fix failing tests before pushing."
-    echo "Override with: git push --no-verify"
-    exit 1
-  fi
-
-else
-  echo "⚠️  No recognized test framework found"
-  echo "   Skipping test execution"
-  exit 0
-fi
-
-echo ""
-echo "✅ All tests passed - safe to push"
-exit 0
+#!/usr/bin/env bash
+# Scope: universal | Runs test suite before push
+# MORPH-SPEC Pre-Push Hook
+# Ensures all tests pass before pushing to remote
+
+echo "🧪 Running test suite before push..."
+echo ""
+
+# Detect project type and run appropriate tests
+if [[ -f *.csproj ]] || find . -maxdepth 2 -name "*.csproj" 2>/dev/null | grep -q .; then
+  # .NET project detected
+  echo "📦 Detected .NET project"
+
+  if ! dotnet test --verbosity minimal --no-build --no-restore 2>/dev/null; then
+    echo ""
+    echo "❌ .NET tests failed!"
+    echo ""
+    echo "Fix failing tests before pushing."
+    echo "Override with: git push --no-verify"
+    exit 1
+  fi
+
+elif [[ -f package.json ]]; then
+  # Node.js project detected
+  echo "📦 Detected Node.js project"
+
+  if ! npm test 2>/dev/null; then
+    echo ""
+    echo "❌ Node.js tests failed!"
+    echo ""
+    echo "Fix failing tests before pushing."
+    echo "Override with: git push --no-verify"
+    exit 1
+  fi
+
+else
+  echo "⚠️  No recognized test framework found"
+  echo "   Skipping test execution"
+  exit 0
+fi
+
+echo ""
+echo "✅ All tests passed - safe to push"
+exit 0

package/framework/hooks/shared/phase-utils.js

@@ -32,6 +32,7 @@ export const OUTPUT_PHASE_MAP = {
   mandate: 'plan',
   tasks: 'plan',
   decisions: 'plan',
+  reuseMap: 'plan',
   usecases: 'plan',
   recap: 'implement',
   reviewReport: 'review',
@@ -50,6 +51,7 @@ export const FILENAME_TO_OUTPUT = {
   'mandate.md': 'mandate',
   'tasks.json': 'tasks',
   'decisions.md': 'decisions',
+  'reuse-map.md': 'reuseMap',
   'recap.md': 'recap',
   'review-report.md': 'reviewReport',
   'evaluator-report.md': 'evaluatorReport',

package/framework/hooks/shared/stdin-reader.js

@@ -1,26 +1,26 @@
-/**
- * Shared stdin reader for Claude Code hooks.
- *
- * Reads JSON payload from stdin (provided by Claude Code to hooks).
- * Returns parsed object or null on failure.
- */
-
-/**
- * Read and parse JSON from stdin
- * @returns {Promise<Object|null>} Parsed JSON or null
- */
-export function readStdin() {
-  return new Promise((resolve) => {
-    let input = '';
-    process.stdin.setEncoding('utf-8');
-    process.stdin.on('data', (chunk) => { input += chunk; });
-    process.stdin.on('end', () => {
-      try {
-        resolve(JSON.parse(input || '{}'));
-      } catch {
-        resolve(null);
-      }
-    });
-    process.stdin.on('error', () => resolve(null));
-  });
-}
+/**
+ * Shared stdin reader for Claude Code hooks.
+ *
+ * Reads JSON payload from stdin (provided by Claude Code to hooks).
+ * Returns parsed object or null on failure.
+ */
+
+/**
+ * Read and parse JSON from stdin
+ * @returns {Promise<Object|null>} Parsed JSON or null
+ */
+export function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input || '{}'));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on('error', () => resolve(null));
+  });
+}

package/framework/mcp/registry.json

@@ -250,14 +250,49 @@
         ],
         "setupGuide": "1. Get a token at https://replicate.com/account/api-tokens\n2. Build the MCP: cd $MORPH_HUB/mcps/seedance && npm install && npm run build\n3. Run: claude mcp add seedance -e REPLICATE_API_TOKEN=<token> -- node $MORPH_HUB/mcps/seedance/dist/index.js\n4. Verify with list_videos (reads local history, spends no credits)"
       }
+    },
+    "graphify": {
+      "phases": ["proposal", "plan", "implement", "review"],
+      "tools": ["query_graph", "get_node", "get_neighbors", "get_community", "god_nodes", "graph_stats", "shortest_path", "list_prs", "get_pr_impact", "triage_prs"],
+      "detection": "graphify-out/graph.json exists in the project root (written by morph-spec graph build, or by the graphify post-commit hook)",
+      "fallback": "Comportamento atual: Grep/Glob/Read. O grafo é um subconjunto estrito do grep — no eval não encontrou um único arquivo que o grep perderia — então cair para grep não perde recall, só devolve mais ruído",
+      "usage": "Blast radius, vizinhança de símbolo e god nodes sem gastar token de leitura. PREFIRA `morph-spec graph explain|affected`, que aplica o saneamento da ADR-003 (coalesce de stub, classificação de órfão) que este servidor NÃO aplica — em C# o grafo cru produz falso negativo silencioso. O MCP serve para exploração interativa e para consulta cross-repo: as 10 tools aceitam project_path, então uma instância serve vários repositórios",
+      "healthCheck": {
+        "toolPattern": "graphify",
+        "testCall": "Call graph_stats with no arguments (uses the current project)",
+        "testParams": {},
+        "successIndicator": "Returns node and edge counts for the project graph",
+        "failureHint": "graphify-mcp não respondeu. Confirme com `graphify --version` (pinado: 0.9.50) e com `morph-spec graph status`. Se o graph.json não existir, rode `morph-spec graph build` — sem grafo o servidor não tem o que servir."
+      },
+      "install": {
+        "autoInstall": false,
+        "transport": "stdio",
+        "config": {
+          "type": "stdio",
+          "command": "graphify-mcp",
+          "args": []
+        },
+        "credentials": [],
+        "prerequisites": [
+          "graphify 0.9.50 instalado (o step 18b do setup-infra faz isso via uv/pipx/pip)",
+          "graphify-out/graph.json gerado — morph-spec graph build"
+        ],
+        "stackRelevance": ["*"],
+        "warnings": [
+          "O binário é `graphify-mcp`. `python -m graphify.serve`, que é o comando do README oficial, FALHA com `uv tool install`: o pacote vive num venv isolado e o Python do sistema não o enxerga.",
+          "Quem instala e pina o graphify é o step 18b do setup-infra, não este registro — por isso autoInstall é false.",
+          "As respostas deste servidor são o grafo CRU, sem o saneamento do `morph-spec graph`. Em C#, blast radius cru pode devolver zero consumidores onde existem dois."
+        ],
+        "setupGuide": null
+      }
     }
   },
   "_phaseMatrixNote": "Keys must be the v5 phases from framework/phases.json. The v4 keys 'design' and 'tasks' both collapsed into 'plan'; 'review' was absent entirely, so a project in review resolved to undefined. Stack-scoped MCPs (asaas) stay out of this matrix on purpose — only universal ones are listed.",
   "phaseMatrix": {
-    "proposal": ["context7"],
+    "proposal": ["context7", "graphify"],
     "uiux": ["playwright", "context7", "stitch", "gemini-image", "seedance"],
-    "plan": ["context7"],
-    "implement": ["context7", "playwright", "vercel", "gemini-image", "seedance"],
-    "review": ["playwright", "context7"]
+    "plan": ["context7", "graphify"],
+    "implement": ["context7", "playwright", "vercel", "gemini-image", "seedance", "graphify"],
+    "review": ["playwright", "context7", "graphify"]
   }
 }

package/framework/rubrics/backend.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.25,
-      "validators": ["architecture"],
-      "description": "Architecture patterns, dependency direction, and code structure"
+      "validators": ["architecture", "reuse"],
+      "description": "Architecture patterns, dependency direction, code structure, and reuse of what the codebase already has"
     },
     "design_ui": {
       "weight": 0.05,

package/framework/rubrics/default.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.25,
-      "validators": ["architecture"],
-      "description": "Architecture patterns and code structure"
+      "validators": ["architecture", "reuse"],
+      "description": "Architecture patterns, code structure, and reuse of what the codebase already has"
     },
     "design_ui": {
       "weight": 0.15,

package/framework/rubrics/frontend.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.15,
-      "validators": ["architecture"],
-      "description": "Architecture patterns and code structure"
+      "validators": ["architecture", "reuse"],
+      "description": "Architecture patterns, code structure, and reuse of what the codebase already has"
     },
     "design_ui": {
       "weight": 0.35,

package/framework/schemas/tasks.schema.json

@@ -36,6 +36,31 @@
             "minLength": 1,
             "description": "Persona id assigned by morph-plan for this task — the bare framework/agents.json id, no 'morph-' prefix (e.g. \"dotnet-senior\"). Optional. Part of the plan contract: frozen after Gate 2."
           },
+          "reuse": {
+            "type": "array",
+            "description": "Veredito de reuso por conceito que ESTA task introduz, carimbado por morph-plan a partir do 2-plan/reuse-map.md. Optional. Part of the plan contract: frozen after Gate 2. A justificativa de um CRIAR mora no reuse-map.md, nunca aqui — duas verdades do mesmo fato divergem.",
+            "items": {
+              "type": "object",
+              "required": ["concept", "verdict"],
+              "properties": {
+                "concept": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Nome do conceito/símbolo, como ele aparecerá no código (ex.: \"SimpleBuilding\")."
+                },
+                "verdict": {
+                  "type": "string",
+                  "enum": ["REUSAR", "ESTENDER", "CRIAR"],
+                  "description": "REUSAR: usar o que existe. ESTENDER: partir do que existe. CRIAR: nada cobre o caso — exige justificativa de uma linha no reuse-map.md."
+                },
+                "target": {
+                  "type": "string",
+                  "description": "Path (ou path:símbolo) do que será reusado/estendido. Vazio ou ausente em CRIAR."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
           "standards": {
             "type": "array",
             "items": { "type": "string", "minLength": 1 },

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.29.0"
+cliVersion: "8.31.0"
 stacks:
   - umbraco
 ---

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.29.0"
+cliVersion: "8.31.0"
 stacks:
   - umbraco
 ---

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.29.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.29.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.29.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.29.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.29.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.29.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.29.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.29.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.29.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.29.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.29.0"
+cliVersion: "8.31.0"
 ---
 
 # morph-uiux