@polymorphism-tech/morph-spec 8.29.0 → 8.31.0

package/src/lib/validators/reuse/index.js

@@ -0,0 +1,10 @@
+/**
+ * Reuse Validators
+ *
+ * Cobrança determinística de reuso de código: símbolo novo cujo nome já existe
+ * no grafo do codebase, na mesma linguagem. É a terceira camada do ciclo
+ * PROSA → ARTEFATO → VERIFICAÇÃO (ver reuse-validator.js).
+ */
+
+export * from './reuse-validator.js';
+export * from './symbol-scanner.js';

package/src/lib/validators/reuse/reuse-validator.js

@@ -0,0 +1,324 @@
+/**
+ * Reuse Validator — símbolo novo cujo nome já existe no codebase.
+ *
+ * A terceira camada do ciclo de reuso, no molde do `design-system-validator`:
+ *
+ *   PROSA (morph-plan §1c, personas)  ──►  ARTEFATO (2-plan/reuse-map.md,
+ *   `reuse` em tasks.json)  ──►  COBRANÇA (este arquivo)
+ *
+ * Prosa sozinha não segura — `morph-brainstorming/SKILL.md:39` já manda olhar
+ * o que existe, e o ProspectPRO redefiniu `SimpleBuilding` em cinco arquivos da
+ * MESMA pasta assim mesmo. O único ciclo que funciona no framework (design
+ * tokens) tem verificação em código; este é o equivalente para código.
+ *
+ * Regras, na ordem em que reduzem ruído:
+ *
+ *   1. Só tipo (class/record/interface/enum/struct/type) — não função nem
+ *      variável. É a categoria que o grafo casa com confiança.
+ *   2. Só MESMA LINGUAGEM. Contrato espelhado entre C# e TS (110 casos no
+ *      ProspectPRO) é o escopo F da proposta: exige gerar tipos do contrato,
+ *      não se resolve por aviso, e fica FORA daqui de propósito.
+ *   3. Mesma feature = achado (`error`); feature diferente = aviso
+ *      (`warning`), porque VSA prescreve DTO homônimo entre slices.
+ *   4. Veredito `CRIAR` declarado no plano (tasks.json `reuse`) rebaixa o
+ *      achado a aviso: a decisão foi tomada no Gate 2, com justificativa no
+ *      reuse-map. O validador cobra a decisão AUSENTE, não a decisão tomada.
+ *
+ * Sem grafo o validador não roda (ADR-002: ausência de grafo nunca bloqueia).
+ *
+ * @module reuse-validator
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { join, isAbsolute } from 'path';
+
+import { loadGraph } from '../../graph/graph-loader.js';
+import { languageOf } from '../../graph/sanitize.js';
+import { getAbsoluteOutputPath } from '../../../core/paths/output-schema.js';
+import {
+  featureOf,
+  isIdiomaticLocalName,
+  isScannableFile,
+  scanDeclarations,
+} from './symbol-scanner.js';
+
+/** Quantos locais citar por achado antes de resumir com "(+N)". */
+const MAX_CITED = 4;
+
+/**
+ * Índice "o que já existe": nome em minúsculas -> ocorrências reais do grafo.
+ *
+ * Só nós com `source_file` preenchido entram — nó com `source_file: ""` é stub
+ * não resolvido (BCL, NuGet, pacote externo), e apontar `Task` do .NET como
+ * duplicação seria ruído garantido. É o mesmo critério do `buildIndex`.
+ *
+ * @param {{nodes: object[]}} graph
+ * @returns {Map<string, Array<{name: string, file: string, language: string, feature: string}>>}
+ */
+export function buildExistingIndex(graph) {
+  const index = new Map();
+
+  for (const node of graph?.nodes ?? []) {
+    if (!node.source_file) continue;
+    // `_callable_class` é a marca de tipo do graphify; nós de ARQUIVO também a
+    // carregam, e se distinguem pelo label com extensão.
+    if (node._callable_class !== true) continue;
+    if (/\.[a-z0-9]+$/i.test(node.label)) continue;
+    if (!isScannableFile(node.source_file)) continue;
+
+    const key = String(node.label).toLowerCase();
+    const entry = {
+      name: node.label,
+      file: node.source_file.replace(/\\/g, '/'),
+      language: languageOf(node.source_file),
+      feature: featureOf(node.source_file),
+    };
+    const bucket = index.get(key);
+    if (bucket) bucket.push(entry);
+    else index.set(key, [entry]);
+  }
+
+  return index;
+}
+
+/**
+ * Casa as declarações desta feature contra o que já existe.
+ *
+ * Puro e sem I/O — é aqui que a regra mora, e é isto que o teste roda contra o
+ * grafo real do ProspectPRO.
+ *
+ * @param {Array<{name: string, kind: string, line: number, file: string}>} declarations
+ * @param {Map<string, Array<{name: string, file: string, language: string, feature: string}>>} existing
+ * @param {{verdicts?: Map<string, {verdict: string, target?: string}>}} [opts]
+ * @returns {Array<object>} issues, uma por símbolo duplicado
+ */
+export function findDuplicateSymbols(declarations, existing, opts = {}) {
+  const verdicts = opts.verdicts ?? new Map();
+  const issues = [];
+
+  // Uma declaração por (nome, arquivo); o mesmo nome em N arquivos da feature
+  // vira UM achado com N locais, não N achados.
+  const byName = new Map();
+  for (const decl of declarations) {
+    const key = decl.name.toLowerCase();
+    const bucket = byName.get(key);
+    if (bucket) bucket.push(decl);
+    else byName.set(key, [decl]);
+  }
+
+  for (const [key, decls] of byName) {
+    if (isIdiomaticLocalName(decls[0].name)) continue;
+
+    const declaredFiles = new Set(decls.map((d) => d.file));
+    const language = languageOf(decls[0].file);
+
+    // Onde mais esse nome vive: no grafo (código que já existia) e nos OUTROS
+    // arquivos desta mesma leva (código novo que o grafo ainda não viu — o
+    // rebuild é assíncrono, e é exatamente o caso SimpleBuilding).
+    const fromGraph = (existing.get(key) ?? []).filter(
+      (e) => e.language === language && !declaredFiles.has(e.file),
+    );
+    // O filtro de linguagem vale AQUI TAMBÉM, não só contra o grafo: uma leva
+    // que toca `CatalogContracts.cs` e `catalog.types.ts` declara `CatalogItem`
+    // nos dois, na mesma feature `Catalog/` — e sem este filtro isso vira erro,
+    // que é precisamente o contrato espelhado C#↔TS que a proposta separa no
+    // escopo F por não se resolver com aviso. Medido no MORPH_GHLBrain.
+    const fromBatch = decls
+      .slice(1)
+      .filter((d) => languageOf(d.file) === language)
+      .map((d) => ({ name: d.name, file: d.file, language, feature: featureOf(d.file) }));
+
+    const elsewhere = [...fromGraph, ...fromBatch];
+    if (elsewhere.length === 0) continue;
+
+    const homeFeature = featureOf(decls[0].file);
+    const intra = elsewhere.some((e) => e.feature === homeFeature);
+    const verdict = verdicts.get(key);
+    const planned = verdict?.verdict === 'CRIAR';
+
+    const locations = elsewhere.slice(0, MAX_CITED).map((e) => e.file);
+    const more = elsewhere.length - locations.length;
+
+    issues.push({
+      level: intra && !planned ? 'error' : 'warning',
+      scope: intra ? 'intra-feature' : 'cross-feature',
+      symbol: decls[0].name,
+      file: decls[0].file,
+      line: decls[0].line,
+      planned,
+      message:
+        `${decls[0].kind} "${decls[0].name}" já existe ${intra ? 'na MESMA feature' : 'no projeto'} ` +
+        `(${elsewhere.length}× em ${locations.join(', ')}${more > 0 ? ` (+${more})` : ''})` +
+        (planned ? ' — o plano declarou CRIAR, mas confira se a justificativa ainda vale' : ''),
+      solution: intra
+        ? `Reuse ou estenda o tipo existente em vez de redeclarar. Confirme com ` +
+          `\`morph-spec graph explain ${decls[0].name}\` (sem grafo: ` +
+          `\`grep -rn "${decls[0].name}"\`) e, se a criação for mesmo necessária, ` +
+          `registre o veredito CRIAR com justificativa no reuse-map da feature.`
+        : `VSA tolera DTO homônimo entre slices — confirme que são conceitos ` +
+          `diferentes e não a mesma coisa escrita duas vezes.`,
+    });
+  }
+
+  return issues.sort((a, b) => {
+    if (a.level !== b.level) return a.level === 'error' ? -1 : 1;
+    return a.symbol.localeCompare(b.symbol);
+  });
+}
+
+/**
+ * Vereditos de reuso carimbados no plano: `tasks[].reuse[]`.
+ *
+ * Ler do `tasks.json` — e não do `reuse-map.md` — é deliberado: o veredito é
+ * um dado estruturado, e o markdown existe para o humano ler no Gate 2. Duas
+ * leituras do mesmo fato, cada uma na forma certa para o seu consumidor.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @returns {Map<string, {verdict: string, target?: string}>}
+ */
+export function readReuseVerdicts(projectPath, featureName) {
+  const verdicts = new Map();
+  if (!featureName) return verdicts;
+
+  try {
+    const tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
+    if (!existsSync(tasksPath)) return verdicts;
+    const doc = JSON.parse(readFileSync(tasksPath, 'utf8').replace(/^/, ''));
+    for (const task of doc.tasks ?? []) {
+      for (const entry of task.reuse ?? []) {
+        if (!entry?.concept) continue;
+        verdicts.set(String(entry.concept).toLowerCase(), {
+          verdict: String(entry.verdict || '').toUpperCase(),
+          target: entry.target,
+        });
+      }
+    }
+  } catch {
+    // Plano ilegível não é problema deste validador — o tasks-json-guard já
+    // cobra o schema, e aqui a ausência de veredito só torna a cobrança mais
+    // rígida, nunca mais frouxa.
+  }
+  return verdicts;
+}
+
+/**
+ * Arquivos que esta feature criou ou alterou.
+ *
+ * Duas fontes, unidas, porque cada uma é cega no momento em que a outra
+ * enxerga: `outputs` do `tasks.json` é o contrato do framework (morph-implement
+ * §8 exige listar TODO arquivo produzido) e sobrevive ao commit; `git status`
+ * pega o que ainda não foi registrado numa task. Sem git, sem drama.
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @returns {string[]} paths relativos ao projeto, com barra normal
+ */
+export function collectChangedFiles(projectPath, featureName) {
+  const files = new Set();
+
+  try {
+    const tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
+    if (existsSync(tasksPath)) {
+      const doc = JSON.parse(readFileSync(tasksPath, 'utf8').replace(/^/, ''));
+      for (const task of doc.tasks ?? []) {
+        for (const out of task.outputs ?? []) {
+          if (typeof out === 'string') files.add(out.replace(/\\/g, '/'));
+        }
+      }
+    }
+  } catch {
+    // tasks.json ausente/ilegível: sobra o git.
+  }
+
+  try {
+    const out = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    for (const line of out.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      // "XY path" e, em rename, "XY antigo -> novo": só o destino interessa.
+      // Os paths vêm relativos à RAIZ do repositório — que no morph-spec é a
+      // própria árvore da feature (cada worktree é a sua raiz). Se algum dia
+      // não coincidir com `projectPath`, o `existsSync` adiante descarta o
+      // path: perde-se cobertura, nunca se acusa um arquivo que não existe.
+      const path = line.slice(3).split(' -> ').pop().replace(/^"|"$/g, '');
+      if (path) files.add(path.replace(/\\/g, '/'));
+    }
+  } catch {
+    // Fora de um repo git, ou git indisponível: o tasks.json já respondeu.
+  }
+
+  return [...files];
+}
+
+/**
+ * Validador plugado no `validation-runner` (e por ele no nó `validators` do
+ * `morph-spec verify`).
+ *
+ * @param {string} projectPath
+ * @param {string} featureName
+ * @param {object} [options]
+ * @param {string[]} [options.changedFiles] - override da coleta (testes)
+ * @param {object} [options._graph] - grafo já carregado (testes)
+ * @returns {Promise<{errors: number, warnings: number, issues: object[]}>}
+ */
+export async function validateReuse(projectPath, featureName = null, options = {}) {
+  const result = { errors: 0, warnings: 0, issues: [] };
+
+  const graph = options._graph ?? (() => {
+    const loaded = loadGraph(projectPath);
+    return loaded.ok ? loaded.graph : null;
+  })();
+
+  if (!graph) {
+    // ADR-002: projeto sem grafo (sem Python, ou grafo ainda não construído)
+    // segue em frente. Um validador que reprovasse aqui transformaria uma
+    // dependência opcional em pré-requisito.
+    result._skipReason = 'sem grafo de codebase — `morph-spec graph build` habilita esta verificação';
+    return result;
+  }
+
+  const changed = options.changedFiles ?? collectChangedFiles(projectPath, featureName);
+  const declarations = [];
+
+  for (const rel of changed) {
+    if (!isScannableFile(rel)) continue;
+    const abs = isAbsolute(rel) ? rel : join(projectPath, rel);
+    if (!existsSync(abs)) continue;
+    let content;
+    try {
+      content = readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const decl of scanDeclarations(content, rel)) {
+      declarations.push({ ...decl, file: rel.replace(/\\/g, '/') });
+    }
+  }
+
+  if (declarations.length === 0) {
+    result._skipReason = 'nenhum tipo novo declarado nos arquivos desta feature';
+    return result;
+  }
+
+  const existing = buildExistingIndex(graph);
+  const verdicts = readReuseVerdicts(projectPath, featureName);
+  const issues = findDuplicateSymbols(declarations, existing, { verdicts });
+
+  result.issues = issues.map((i) => ({
+    level: i.level,
+    message: i.message,
+    file: i.file,
+    line: i.line,
+    solution: i.solution,
+  }));
+  result.errors = issues.filter((i) => i.level === 'error').length;
+  result.warnings = issues.filter((i) => i.level === 'warning').length;
+
+  return result;
+}

package/src/lib/validators/reuse/symbol-scanner.js

@@ -0,0 +1,144 @@
+/**
+ * Extração determinística de declarações de tipo a partir do TEXTO do arquivo.
+ *
+ * Por que não ler as declarações do grafo: o grafo é reconstruído em background
+ * pelo hook post-commit do graphify, então o código que acabou de ser escrito
+ * (o caso que este validador existe para pegar) ainda NÃO está nele. O grafo
+ * responde "o que já existia"; o disco responde "o que esta feature acabou de
+ * declarar". Inverter os dois papéis produziria um validador cego justamente na
+ * janela em que ele precisa morder — ver graph-loader.js `getFreshness`.
+ *
+ * A varredura é por linha, com regex ancorada no início da declaração. Mesma
+ * limitação (e mesmo grau de tolerância) do design-system-validator: uma
+ * declaração citada dentro de uma string ou de um comentário de bloco pode
+ * passar. O custo de errar é um aviso a mais, nunca um bloqueio silencioso.
+ *
+ * @module reuse-symbol-scanner
+ */
+
+import { languageOf } from '../../graph/sanitize.js';
+
+/** Extensões que este scanner sabe ler. Fora daqui, o arquivo é ignorado. */
+const SCANNABLE = /\.(cs|ts|tsx|js|jsx|mjs|cjs)$/i;
+
+/**
+ * Arquivo de teste, em qualquer das convenções que os dois stacks usam.
+ * Duplicar um stub entre três arquivos de teste (`ResizeObserverStub` no
+ * ProspectPRO) é ruído conhecido: teste é código descartável por natureza e a
+ * regra de reuso não se aplica a ele. Cobre `__tests__/`, `.test.`, `.spec.`,
+ * e os projetos `*.Tests/` do .NET.
+ */
+const TEST_FILE = /(^|\/)__tests__\/|\.(test|spec)\.[jt]sx?$|(^|\/)(?:[Tt]ests?|[^/]*\.[Tt]ests?|[^/]*[a-z0-9_]Tests?)\//;
+
+/**
+ * Diretórios que contêm arquivos com extensão de código mas que não são o
+ * código-fonte do projeto. `.morph/` é o caso que apareceu de verdade: o
+ * `archive/{feature}/1-design/contracts.cs` de uma feature arquivada entra no
+ * grafo do ProspectPRO como um tipo `RoulettePriority` a mais, e acusaria a
+ * entidade real de duplicar o próprio artefato de planejamento.
+ */
+const NOT_SOURCE = /(^|\/)(?:\.morph|node_modules|dist|build|out|\.next|bin|obj|coverage)\//;
+
+/**
+ * Declaration file do TypeScript. `auth-debug.d.ts` + `auth-debug.ts`
+ * declarando o mesmo tipo é o mecanismo da linguagem, não duplicação.
+ */
+const DECLARATION_FILE = /\.d\.ts$/i;
+
+/**
+ * Nomes que a convenção usa como tipo LOCAL de arquivo, não como conceito do
+ * domínio. Todo componente React declara o seu `Props`; dois arquivos com
+ * `interface Props` não são o mesmo conceito escrito duas vezes — são dois
+ * conceitos diferentes com o nome que a convenção manda usar.
+ *
+ * A lista é curta de propósito e só admite nome genérico de UMA palavra: assim
+ * que há qualificador de domínio (`BuildingFiltersProps`, `FilterOption`) o
+ * nome volta a ser um conceito e a regra vale. Mesmo papel da allowlist de
+ * cores de sistema no design-system-validator.
+ */
+const IDIOMATIC_LOCAL_NAMES = new Set([
+  'props', 'state', 'row', 'item', 'column', 'context', 'params', 'options',
+]);
+
+/** Declaração de tipo em C#. `partial` é capturado para ser excluído depois. */
+const CSHARP_DECL =
+  /^\s*(?:\[[^\]]*\]\s*)*(?:(?:public|internal|private|protected|sealed|abstract|static|readonly|new|file|partial)\s+)*(class|record|interface|enum|struct)\s+([A-Za-z_]\w*)/;
+
+/** Declaração de tipo em TS/JS. */
+const WEB_DECL =
+  /^\s*(?:export\s+(?:default\s+)?)?(?:declare\s+)?(?:abstract\s+)?(interface|type|class|enum)\s+([A-Za-z_$][\w$]*)/;
+
+/** Linha que é claramente comentário — não vale a pena parsear. */
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*|<!--)/;
+
+/**
+ * @param {string} sourceFile
+ * @returns {boolean} o arquivo entra na varredura de reuso
+ */
+export function isScannableFile(sourceFile) {
+  const f = String(sourceFile || '').replace(/\\/g, '/');
+  if (!SCANNABLE.test(f)) return false;
+  if (DECLARATION_FILE.test(f)) return false;
+  if (TEST_FILE.test(f)) return false;
+  if (NOT_SOURCE.test(f)) return false;
+  return true;
+}
+
+/**
+ * "Feature" de um path, com a mesma heurística do baseline
+ * (docs/specs/code-reuse-gap/measure-duplication.mjs): o segmento após
+ * `features/`/`Features/` quando existe, senão a pasta do arquivo. É o que
+ * separa o achado indefensável (mesma feature) do aviso tolerado por VSA.
+ *
+ * @param {string} sourceFile
+ * @returns {string}
+ */
+export function featureOf(sourceFile) {
+  const f = String(sourceFile || '').replace(/\\/g, '/');
+  const m = /(?:^|\/)(?:features|Features)\/([^/]+)/.exec(f);
+  if (m) return m[1].toLowerCase();
+  return f.split('/').slice(0, -1).join('/').toLowerCase();
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean} nome genérico que a convenção usa como tipo local
+ */
+export function isIdiomaticLocalName(name) {
+  return IDIOMATIC_LOCAL_NAMES.has(String(name).toLowerCase());
+}
+
+/**
+ * Declarações de tipo de um arquivo.
+ *
+ * `partial` (C#) é reconhecido e DESCARTADO: declarar a mesma classe em dois
+ * arquivos é o propósito da palavra-chave, e sinalizá-la seria um falso
+ * positivo garantido em qualquer projeto .NET com código gerado.
+ *
+ * @param {string} content - conteúdo do arquivo
+ * @param {string} sourceFile - path, usado só para decidir a linguagem
+ * @returns {Array<{name: string, kind: string, line: number}>}
+ */
+export function scanDeclarations(content, sourceFile) {
+  const language = languageOf(sourceFile);
+  const re = language === 'dotnet' ? CSHARP_DECL : WEB_DECL;
+  const out = [];
+  const seen = new Set();
+
+  const lines = String(content || '').split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (COMMENT_LINE.test(line)) continue;
+    if (language === 'dotnet' && /\bpartial\s+(class|record|interface|struct)\b/.test(line)) continue;
+
+    const m = re.exec(line);
+    if (!m) continue;
+
+    const [, kind, name] = m;
+    if (seen.has(name)) continue;
+    seen.add(name);
+    out.push({ name, kind, line: i + 1 });
+  }
+
+  return out;
+}

package/src/lib/validators/shared/emit-validator-dispatch.js

@@ -1,14 +1,14 @@
-/**
- * Stub: validation dispatch was driven by tier-4 agents in v4.
- * In v5, validation is handled by morph-eval skill invoked directly
- * by the Evaluator role. This function is kept for call-site compatibility.
- *
- * @module emit-validator-dispatch
- */
-
-/**
- * No-op in v5. Validation dispatch is now handled by morph-eval skill.
- */
-export async function emitValidatorDispatch(_featureName, _phase, _cwd) {
-  // v5: evaluation driven by morph-eval skill, not CLI dispatch
-}
+/**
+ * Stub: validation dispatch was driven by tier-4 agents in v4.
+ * In v5, validation is handled by morph-eval skill invoked directly
+ * by the Evaluator role. This function is kept for call-site compatibility.
+ *
+ * @module emit-validator-dispatch
+ */
+
+/**
+ * No-op in v5. Validation dispatch is now handled by morph-eval skill.
+ */
+export async function emitValidatorDispatch(_featureName, _phase, _cwd) {
+  // v5: evaluation driven by morph-eval skill, not CLI dispatch
+}

package/src/lib/validators/shared/issue-counter.js

@@ -1,14 +1,14 @@
-/**
- * Shared issue counting utility for validators
- *
- *
- * @param {Array} issues - Array of validation issues with type property
- * @returns {{errors: number, warnings: number, infos: number}} Count by type
- */
-export function countIssues(issues) {
-  return {
-    errors: issues.filter((i) => i.type === 'error').length,
-    warnings: issues.filter((i) => i.type === 'warning').length,
-    infos: issues.filter((i) => i.type === 'info').length,
-  };
-}
+/**
+ * Shared issue counting utility for validators
+ *
+ *
+ * @param {Array} issues - Array of validation issues with type property
+ * @returns {{errors: number, warnings: number, infos: number}} Count by type
+ */
+export function countIssues(issues) {
+  return {
+    errors: issues.filter((i) => i.type === 'error').length,
+    warnings: issues.filter((i) => i.type === 'warning').length,
+    infos: issues.filter((i) => i.type === 'info').length,
+  };
+}

package/src/lib/validators/validation-runner.js

@@ -24,7 +24,7 @@ import { aggregateScores, loadRubric } from './score-aggregator.js';
  */
 const HEAVY_VALIDATORS = new Set([
   'architecture', 'packages', 'contract-compliance',
-  'css', 'design-system'
+  'css', 'design-system', 'reuse'
 ]);
 
 /**
@@ -74,6 +74,22 @@ export async function runValidation(projectPath, featureName, options = {}) {
   // Merge constraint-enabled validators
   validatorIds.push(...constraints.enabledValidators);
 
+  // Reuse is stack-agnostic: "isto já existe?" é a mesma pergunta em C# e em
+  // TypeScript, e o validador se cala sozinho quando não há grafo (ADR-002).
+  // Por isso ele não entra no `defaultValidators` de stack profile nenhum —
+  // entra aqui, ANTES do early-return de "nenhum validador": num projeto de
+  // stack `empty`/`nodejs-cli` não há outro validador para carregá-lo, e é
+  // exatamente lá que ele seria a única verificação a rodar.
+  // Em `light` (checkpoint) ele fica de fora, como todo validador pesado — é
+  // uma leitura de graph.json (11-24 MB nos repos medidos) — e por isso está
+  // em HEAVY_VALIDATORS, que é onde essa política se declara. Não entra em
+  // `droppedByMode`: essa lista responde "o que o modo tirou da SUA lista", e
+  // é ela que distingue "light pulou os pesados" de "este stack não tem
+  // validador nenhum" na mensagem final.
+  if (!options.skipReuse && mode !== 'light') {
+    validatorIds.push('reuse');
+  }
+
   if (validatorIds.length === 0) {
     // Say which of the two it is. On a pure `dotnet` project every default
     // validator is heavy, so a light run legitimately runs none — but the old
@@ -115,6 +131,11 @@ export async function runValidation(projectPath, featureName, options = {}) {
   // Deduplicate
   const uniqueValidators = [...new Set(validatorIds)];
 
+  // Validadores que rodaram mas se declararam inaplicáveis (ex.: `reuse` num
+  // projeto sem grafo). Um validador assim não acha nada — e "não achou nada"
+  // é indistinguível de "verificou e está limpo" se ninguém contar.
+  const selfSkipped = [];
+
   // Run each validator
   for (const validatorId of uniqueValidators) {
     try {
@@ -127,6 +148,9 @@ export async function runValidation(projectPath, featureName, options = {}) {
       const validatorResult = await runSingleValidator(validatorId, projectPath, featureName, validatorOptions);
 
       if (validatorResult) {
+        if (validatorResult._skipReason) {
+          selfSkipped.push(`${validatorId}: ${validatorResult._skipReason}`);
+        }
         const { errors, warnings, issues } = normalizeValidatorResult(validatorId, validatorResult);
         result.errors += errors;
         result.warnings += warnings;
@@ -158,6 +182,16 @@ export async function runValidation(projectPath, featureName, options = {}) {
     }
   }
 
+  // Todos os validadores se declararam inaplicáveis: o resultado é SKIP, não um
+  // verde. Sem isto, um projeto de stack sem validadores e sem grafo receberia
+  // `validators: pass` do `morph-spec verify` tendo verificado exatamente nada
+  // — o modo de falha que este repositório já pagou caro (guardrail inerte).
+  if (selfSkipped.length > 0 && selfSkipped.length === uniqueValidators.length) {
+    result._skipReason = `No validators ran — ${selfSkipped.join('; ')}`;
+    result.summary = result._skipReason;
+    return result;
+  }
+
   result.passed = result.errors === 0;
   result.summary = result.passed
     ? `✅ All validations passed (${result.warnings} warnings)`
@@ -286,6 +320,11 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
       return await validateDesignSystem(projectPath, featureName, options);
     }
 
+    case 'reuse': {
+      const { validateReuse } = await import('./reuse/reuse-validator.js');
+      return await validateReuse(projectPath, featureName, options);
+    }
+
     case 'nextjs-component': {
       const { validateNextComponentFiles } = await import('./nextjs/next-component-validator.js');
       return await validateNextComponentFiles(projectPath, options);