@spec-wave/cli 0.27.0 → 0.29.0

package/src/lib/spec-audit.mjs

@@ -0,0 +1,372 @@
+// Auditoria de dependências de uma milestone (módulo puro — sem I/O).
+//
+// A crítica adversarial olha cada documento contra os insumos da MESMA Feature.
+// O que ela estruturalmente não enxerga é o PAR: duas specs declarando depender
+// uma da outra, bloqueante vivendo em milestone posterior à de quem depende
+// dela, dependência que nenhuma Feature do repositório cria. Cada spec, sozinha,
+// está certa — o defeito só existe no conjunto, e `reference/revisao.md` da
+// preparar-specs pedia que um humano lesse as dez specs juntas para achá-lo.
+//
+// Este módulo automatiza a parte DETERMINÍSTICA dessa leitura. O que exige
+// julgamento (a mesma regra contada de dois jeitos) continua fora — é a crítica
+// de conjunto, uma chamada de modelo, não um grep.
+//
+// A seção `# Dependências` da spec é prosa (o template pede só "Internas e
+// Externas"), então a extração é best-effort por três vias: referência `#N`,
+// slug da Feature e título normalizado. O destino é um RELATÓRIO lido por gente
+// (ou por agente) na Fase 3.5 — falso positivo custa uma conferência; falso
+// negativo custa descobrir na implementação.
+
+import { slugify } from './slugify.mjs';
+import { orderStories } from './dependencies.mjs';
+
+// Minúsculas e sem acento: "Gestão de Crédito" casa com "gestao de credito".
+const norm = (s) => String(s || '')
+  .toLowerCase()
+  .normalize('NFD')
+  .replace(/[̀-ͯ]/g, '');
+
+// Título sem o prefixo [FEATURE]/[BUG]/etc., para casar com a prosa.
+const bareTitle = (title) => String(title || '').replace(/^\s*\[.*?\]\s*/, '').trim();
+
+/**
+ * O texto da seção `# Dependências` de uma spec (PURA).
+ *
+ * Do H1 `# Dependências` até o próximo H1 — os `## Internas`/`## Externas`
+ * ficam dentro. `null` quando a seção não existe (spec fora do template).
+ *
+ * @param {string} markdown
+ * @returns {string|null}
+ */
+export function dependencySection(markdown = '') {
+  const lines = String(markdown).split('\n');
+  const start = lines.findIndex(l => /^#\s+depend[êe]ncias\s*$/i.test(norm(l.trim())));
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#\s+\S/.test(lines[i])) { end = i; break; }
+  }
+  return lines.slice(start + 1, end).join('\n');
+}
+
+/**
+ * Todas as referências `#N` de um texto (PURA).
+ *
+ * @param {string} text
+ * @returns {number[]} sem duplicatas, na ordem de aparição
+ */
+export function issueRefs(text = '') {
+  const out = [];
+  for (const m of String(text).matchAll(/#(\d+)\b/g)) {
+    const n = parseInt(m[1], 10);
+    if (Number.isInteger(n) && n > 0 && !out.includes(n)) out.push(n);
+  }
+  return out;
+}
+
+/**
+ * Quais issues do catálogo um texto menciona (PURA).
+ *
+ * Três vias, da mais precisa à mais frouxa: `#N`, slug, título normalizado.
+ * A frouxa existe porque a prosa da spec raramente cita o número — ela diz
+ * "depende do wizard de Cadastro de Pedidos".
+ *
+ * @param {string} text
+ * @param {Array<{number:number, title:string, slug?:string}>} catalog
+ * @param {number} [selfNumber] a própria Feature nunca é dependência dela mesma
+ * @returns {number[]} números do catálogo mencionados
+ */
+export function mentionedIssues(text = '', catalog = [], selfNumber = null) {
+  const refs = issueRefs(text);
+  const corpo = norm(text);
+  const out = [];
+  for (const f of catalog) {
+    if (!f || f.number === selfNumber) continue;
+    const slug = f.slug || slugify(f.title || '');
+    const titulo = norm(bareTitle(f.title));
+    // As vias frouxas (substring) exigem comprimento: "PIX" ou "x" como título
+    // casaria com meia prosa e transformaria tudo em dependência.
+    const citada = refs.includes(f.number)
+      || (slug.length >= 4 && corpo.includes(slug))
+      || (titulo.length >= 4 && corpo.includes(titulo));
+    if (citada && !out.includes(f.number)) out.push(f.number);
+  }
+  return out;
+}
+
+/**
+ * Bullets de dependência que não casam com NADA conhecido (PURA).
+ *
+ * É o sinal barato do recurso órfão: quatro specs declarando depender de
+ * "edição de custo_canal" enquanto nenhuma Feature cria essa edição — cada
+ * bullet está certo, e o conjunto não fecha. Sem um registro de recursos
+ * (o `criada_por:` do tech_context) não dá para PROVAR a órfã; dá para listar
+ * o que não rastreia a Feature nenhuma e deixar a conferência barata.
+ *
+ * Só a subseção **Internas** entra: dependência Externa (gateway, API de
+ * terceiro) não rastreia a Feature nenhuma POR DEFINIÇÃO — flagá-la seria
+ * ensinar a ignorar o aviso. Sem subseções, a seção inteira é o fallback.
+ *
+ * @param {string} section texto da seção Dependências
+ * @param {Array<{number:number, title:string, slug?:string}>} catalog
+ * @returns {string[]} texto dos bullets sem alvo, aparados
+ */
+export function untraceableBullets(section = '', catalog = []) {
+  const lines = String(section).split('\n');
+  const começo = lines.findIndex(l => /^#{2,}\s+.*internas/i.test(norm(l)));
+  let alvo = lines;
+  if (começo !== -1) {
+    let fim = lines.length;
+    for (let i = começo + 1; i < lines.length; i++) {
+      if (/^#{2,}\s+\S/.test(lines[i])) { fim = i; break; }
+    }
+    alvo = lines.slice(começo + 1, fim);
+  }
+  const out = [];
+  for (const line of alvo) {
+    const m = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+    if (!m) continue;
+    const bullet = m[1];
+    // "Nenhuma"/"N/A" é resposta válida do gerador, não dependência sem alvo.
+    if (/^(nenhuma|n\/a|—|-)\.?$/i.test(norm(bullet).trim())) continue;
+    if (issueRefs(bullet).length > 0) continue;
+    if (mentionedIssues(bullet, catalog).length > 0) continue;
+    out.push(bullet.length > 120 ? `${bullet.slice(0, 119)}…` : bullet);
+  }
+  return out;
+}
+
+/**
+ * `a` vence DEPOIS de `b`? (PURA)
+ *
+ * Por data de vencimento quando as duas têm; senão pelo número — milestones
+ * nascem na ordem do planejamento, e é o único critério que sobra quando
+ * ninguém preencheu as datas.
+ *
+ * @param {{number?:number, due_on?:string|null}|null} a
+ * @param {{number?:number, due_on?:string|null}|null} b
+ */
+export function milestoneAfter(a, b) {
+  if (a?.due_on && b?.due_on) return new Date(a.due_on) > new Date(b.due_on);
+  return (a?.number ?? 0) > (b?.number ?? 0);
+}
+
+// Palavras do slug que não dizem nada sozinhas.
+const STOPWORDS = new Set([
+  'de', 'da', 'do', 'das', 'dos', 'com', 'para', 'por', 'em', 'no', 'na',
+  'nos', 'nas', 'e', 'o', 'a', 'os', 'as', 'um', 'uma', 'ao', 'sem', 'sobre',
+]);
+
+/**
+ * Palavras significativas de um slug (PURA). Curtas e vazias ficam de fora.
+ */
+export function slugKeywords(slug = '') {
+  return String(slug).split('-').filter(w => w.length >= 4 && !STOPWORDS.has(w));
+}
+
+/**
+ * Arquivos de código cujo caminho casa com o slug da Feature (PURA).
+ *
+ * A heurística do "isso já não existe?": spec descrevendo o que outra Feature
+ * já implementou é retrabalho ou comportamento duplicado em produção. Exige
+ * DUAS palavras do slug no mesmo caminho (uma só casa com meio repositório);
+ * com o slug de uma palavra útil, uma basta.
+ *
+ * @param {string} slug
+ * @param {string[]} files caminhos relativos do repositório
+ * @returns {Array<{path:string, palavras:string[]}>} os 5 mais específicos
+ */
+export function codeOverlap(slug, files = []) {
+  const kws = slugKeywords(slug);
+  if (kws.length === 0) return [];
+  const minimo = Math.min(2, kws.length);
+  const hits = [];
+  for (const f of files) {
+    const nf = norm(f);
+    const palavras = kws.filter(k => nf.includes(k));
+    if (palavras.length >= minimo) hits.push({ path: f, palavras });
+  }
+  return hits.sort((x, y) => y.palavras.length - x.palavras.length).slice(0, 5);
+}
+
+/**
+ * Decisões de modelagem sem dono no tech_context (PURA).
+ *
+ * O tech_context registrava "não existe feature para editar esses valores" e a
+ * frase ficou meses lá sem ninguém agir — constatação não vira pendência sem um
+ * campo que cobre resposta. O contrato: cada entrada de `decisoes_de_modelagem`
+ * declara `criada_por:` com a Feature que cria o recurso, ou `SEM DONO`
+ * enquanto ninguém o criar. Este check lista o que está sem resposta; a seção
+ * ausente não é achado — a adoção é opcional por repositório.
+ *
+ * Tolerante ao formato (o YAML é livre): aceita lista de objetos ou mapa
+ * recurso→objeto; o rótulo sai de `recurso`/`nome`/`tabela`, da chave do mapa
+ * ou da posição.
+ *
+ * @param {object} staticContext o YAML do tech_context, parseado
+ * @returns {Array<{recurso:string, motivo:'sem-campo'|'sem-dono'}>}
+ */
+export function unownedDecisions(staticContext = {}) {
+  const secao = staticContext?.decisoes_de_modelagem;
+  if (!secao || typeof secao !== 'object') return [];
+  const entradas = Array.isArray(secao)
+    ? secao.map((v, i) => [null, v, i])
+    : Object.entries(secao).map(([k, v], i) => [k, v, i]);
+
+  const out = [];
+  for (const [chave, entrada, i] of entradas) {
+    if (!entrada || typeof entrada !== 'object') continue;
+    const recurso = entrada.recurso || entrada.nome || entrada.tabela || chave || `item ${i + 1}`;
+    const dono = String(entrada.criada_por ?? '').trim();
+    if (!dono) out.push({ recurso, motivo: 'sem-campo' });
+    else if (norm(dono) === 'sem dono') out.push({ recurso, motivo: 'sem-dono' });
+  }
+  return out;
+}
+
+/**
+ * A auditoria inteira (PURA — todo o I/O fica no comando).
+ *
+ * @param {object} params
+ * @param {Array<{number:number, title:string, slug?:string, spec?:string|null,
+ *         milestone?:{number?:number, title?:string, due_on?:string|null}|null}>}
+ *        params.features Features ABERTAS da milestone-alvo, com o conteúdo da spec
+ * @param {Array<{number:number, title:string, slug?:string, closed?:boolean,
+ *         milestone?:object|null}>} params.catalog
+ *        tudo que uma spec pode citar: as Features de TODAS as milestones (e as
+ *        issues avulsas que o comando resolveu via API)
+ * @param {number[]} [params.missingRefs] referências `#N` que a API disse não existir
+ * @param {string[]} [params.files] caminhos do repositório para a heurística de código
+ * @param {object|null} [params.techContext] o tech_context estático, para as decisões sem dono
+ * @returns {{
+ *   semSpec: number[], semSecao: number[],
+ *   grafo: Array<{number:number, dependsOn:number[]}>,
+ *   ciclos: number[],
+ *   inversoes: Array<{feature:number, dep:number, featureMilestone:string, depMilestone:string}>,
+ *   bloqueantesSemMilestone: Array<{feature:number, dep:number}>,
+ *   inexistentes: Array<{feature:number, refs:number[]}>,
+ *   naoRastreaveis: Array<{feature:number, bullets:string[]}>,
+ *   sobreposicoes: Array<{feature:number, slug:string, hits:Array<{path:string, palavras:string[]}>}>,
+ * }}
+ */
+export function auditMilestone({
+  features = [], catalog = [], missingRefs = [], files = [], techContext = null,
+} = {}) {
+  const byNumber = new Map(catalog.map(f => [f.number, f]));
+  const semSpec = [];
+  const semSecao = [];
+  const grafo = [];
+  const inversoes = [];
+  const bloqueantesSemMilestone = [];
+  const inexistentes = [];
+  const naoRastreaveis = [];
+  const sobreposicoes = [];
+
+  for (const f of features) {
+    const slug = f.slug || slugify(f.title || '');
+
+    const hits = codeOverlap(slug, files);
+    if (hits.length > 0) sobreposicoes.push({ feature: f.number, slug, hits });
+
+    if (!f.spec) { semSpec.push(f.number); continue; }
+    const section = dependencySection(f.spec);
+    if (section == null) { semSecao.push(f.number); continue; }
+
+    const deps = mentionedIssues(section, catalog, f.number);
+    grafo.push({ number: f.number, dependsOn: deps });
+
+    const mortas = issueRefs(section).filter(n => missingRefs.includes(n));
+    if (mortas.length > 0) inexistentes.push({ feature: f.number, refs: mortas });
+
+    const bullets = untraceableBullets(section, catalog);
+    if (bullets.length > 0) naoRastreaveis.push({ feature: f.number, bullets });
+
+    for (const d of deps) {
+      const dep = byNumber.get(d);
+      if (!dep || dep.closed) continue; // entregue: a dependência está satisfeita
+      if (!dep.milestone) {
+        bloqueantesSemMilestone.push({ feature: f.number, dep: d });
+      } else if (milestoneAfter(dep.milestone, f.milestone)) {
+        inversoes.push({
+          feature: f.number,
+          dep: d,
+          featureMilestone: f.milestone?.title || `#${f.milestone?.number ?? '?'}`,
+          depMilestone: dep.milestone.title || `#${dep.milestone.number}`,
+        });
+      }
+    }
+  }
+
+  // Ciclo A↔B entre Features: mesmo Kahn das Stories — dependência para fora do
+  // conjunto (outra milestone) vira `external` lá e não entra no ciclo.
+  const { cycle } = orderStories(grafo);
+
+  return {
+    semSpec, semSecao, grafo, ciclos: cycle, inversoes,
+    bloqueantesSemMilestone, inexistentes, naoRastreaveis, sobreposicoes,
+    semDono: unownedDecisions(techContext || {}),
+  };
+}
+
+/**
+ * O veredito da auditoria (PURA) — o que bloqueia e o que só avisa.
+ *
+ * Material é o que muda o desenho ou o sequenciamento se ninguém decidir:
+ * ciclo, inversão de milestone, referência a issue que não existe. O resto é
+ * conferência barata — a heurística de código e os bullets sem alvo têm falso
+ * positivo por construção, e bloquear por eles ensinaria a ignorar o comando.
+ *
+ * @returns {{ status: 'ok'|'aviso'|'problema', materiais: string[], avisos: string[] }}
+ */
+export function auditVerdict(audit) {
+  const materiais = [];
+  const avisos = [];
+  const lista = (arr) => arr.map(n => `#${n}`).join(', ');
+
+  if (audit.ciclos.length > 0) {
+    materiais.push(`Ciclo de dependência entre Features: ${lista(audit.ciclos)} — nenhuma pode começar primeiro.`);
+  }
+  for (const i of audit.inversoes) {
+    materiais.push(
+      `#${i.feature} (${i.featureMilestone}) depende de #${i.dep}, que está em "${i.depMilestone}" — ` +
+      'a bloqueante vence DEPOIS de quem depende dela.'
+    );
+  }
+  for (const i of audit.inexistentes) {
+    materiais.push(`#${i.feature} referencia issue(s) inexistente(s): ${lista(i.refs)}.`);
+  }
+
+  if (audit.semSpec.length > 0) {
+    avisos.push(`Sem spec para auditar: ${lista(audit.semSpec)}.`);
+  }
+  if (audit.semSecao.length > 0) {
+    avisos.push(`Spec sem seção "# Dependências" (fora do template): ${lista(audit.semSecao)}.`);
+  }
+  for (const b of audit.bloqueantesSemMilestone) {
+    avisos.push(`#${b.feature} depende de #${b.dep}, que não está em milestone nenhuma — sem data, não há como sequenciar.`);
+  }
+  for (const n of audit.naoRastreaveis) {
+    avisos.push(
+      `#${n.feature} declara ${n.bullets.length} dependência(s) que não rastreiam a nenhuma Feature — ` +
+      'possível recurso sem dono (quem cria?).'
+    );
+  }
+  for (const s of audit.sobreposicoes) {
+    avisos.push(
+      `#${s.feature} ("${s.slug}") tem caminho correspondente no código — confira se já não existe: ` +
+      s.hits.map(h => h.path).join(', ')
+    );
+  }
+  for (const d of audit.semDono || []) {
+    avisos.push(
+      `tech_context: decisão de modelagem "${d.recurso}" ` +
+      (d.motivo === 'sem-dono'
+        ? 'declarada SEM DONO — decida quem cria antes de planejar a milestone.'
+        : 'sem o campo `criada_por:` — declare a Feature que cria o recurso, ou `SEM DONO`.')
+    );
+  }
+
+  if (materiais.length) return { status: 'problema', materiais, avisos };
+  if (avisos.length) return { status: 'aviso', materiais, avisos };
+  return { status: 'ok', materiais, avisos };
+}

package/src/lib/tech-context.mjs

@@ -8,7 +8,7 @@ import yaml from 'js-yaml';
 // formato do payload RFC §5.2: { static, dynamic, overrides }. Roda no checkout
 // do GitHub Action, então lê tudo do filesystem local (cwd = raiz do repo-alvo).
 
-const TECH_CONTEXT_PATH = '.github/config/tech_context.yml';
+export const TECH_CONTEXT_PATH = '.github/config/tech_context.yml';
 
 // Diretórios onde migrations costumam viver (várias stacks).
 const MIGRATION_DIRS = [
@@ -21,25 +21,31 @@ const MIGRATION_DIRS = [
 
 const MAX_MIGRATIONS = 10;
 
-// §4.1 — Fonte de verdade estática. Ausência não é erro: segue com {} e avisa.
-function readStaticContext(cwd) {
+// Leitura SILENCIOSA da fonte estática — para quem só consulta (o `audit` lê
+// as decisões de modelagem e ausência não é problema dele). `context: null`
+// distingue "não existe" de "existe vazio"; `error` só em falha de parse.
+export function loadStaticTechContext(cwd = process.cwd()) {
   const filePath = path.join(cwd, TECH_CONTEXT_PATH);
-  if (!existsSync(filePath)) {
-    console.warn(
-      `⚠️ ${TECH_CONTEXT_PATH} não encontrado. ` +
-      `O plano será gerado sem contexto técnico estático. ` +
-      `Rode \`spec-wave init\` para gerar o scaffold.`
-    );
-    return {};
-  }
+  if (!existsSync(filePath)) return { context: null, error: null };
   try {
-    return yaml.load(readFileSync(filePath, 'utf-8')) || {};
+    return { context: yaml.load(readFileSync(filePath, 'utf-8')) || {}, error: null };
   } catch (err) {
-    console.warn(`⚠️ Falha ao parsear ${TECH_CONTEXT_PATH}: ${err.message}. Ignorando.`);
-    return {};
+    return { context: null, error: err.message };
   }
 }
 
+// §4.1 — Fonte de verdade estática. Ausência não é erro: segue com {} e avisa.
+function readStaticContext(cwd) {
+  const { context, error } = loadStaticTechContext(cwd);
+  if (context) return context;
+  console.warn(error
+    ? `⚠️ Falha ao parsear ${TECH_CONTEXT_PATH}: ${error}. Ignorando.`
+    : `⚠️ ${TECH_CONTEXT_PATH} não encontrado. ` +
+      `O plano será gerado sem contexto técnico estático. ` +
+      `Rode \`spec-wave init\` para gerar o scaffold.`);
+  return {};
+}
+
 // §4.2 — Augmentação dinâmica: migrations recentes + versões exatas de pacotes.
 function readDynamicContext(cwd) {
   return {

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",

package/src/plugin/README.md

@@ -18,6 +18,11 @@ carrega só a sua instrução.
 | `plan` | Gera `plan.md` (2º documento) + `tech_context.yml` |
 | `ready` | Valida spec + plan |
 | `decompose` | Rascunho revisável → Stories/Tasks |
+| `preparar-feature` | Orquestra: da spec até ✅ Ready, com Stories e Tasks criadas |
+| `preparar-specs` | Orquestra: as specs de uma milestone inteira |
+| `run` | Executa o próximo passo localmente (`run`/`mode`) |
+| `bug` | Fluxo do Bug: `bug.md`, triagem, correção |
+| `triage` | Tria um Bug: accept / reject / duplicate |
 | `order` | Ordem topológica das Stories |
 | `implement` | Etapa 🚧 Desenvolvimento |
 | `task` | `start` / `done` de uma Task |

package/src/plugin/skills/audit/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: spec-wave-audit
+description: "Use para auditar as specs de uma milestone COMO CONJUNTO, depois de geradas: dependência que ninguém cria, bloqueante em milestone posterior, ciclo entre Features, sobreposição com código já existente — e, com --critique, contradições semânticas entre as specs. Gatilhos: 'audita as specs da v06', 'as dependências da milestone fecham?', 'tem contradição entre as specs?', 'roda a auditoria antes dos planos'. NÃO use para criticar um documento de uma Feature — isso é o passo critique do fluxo normal."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Read
+---
+
+# spec-wave audit — o olhar de conjunto da milestone
+
+Comando **local**:
+
+```bash
+npx @spec-wave/cli@latest audit --milestone <nome>              # determinístico
+npx @spec-wave/cli@latest audit --milestone <nome> --critique   # + crítica de conjunto (paga UMA chamada de modelo)
+npx @spec-wave/cli@latest audit --milestone <nome> --json       # o relatório para ramificar
+```
+
+A crítica do fluxo normal audita cada documento contra os insumos da **mesma** Feature; este comando cruza as specs da milestone **entre si** — é onde vivem os defeitos que cada spec, sozinha, não mostra.
+
+## O que a saída traz
+
+- O **grafo de dependências entre Features**, extraído das seções `# Dependências` (por `#N`, slug e título — best-effort sobre prosa)
+- **Materiais** (exit 1): ciclo entre Features, bloqueante em milestone **posterior** à de quem depende dela, referência a issue inexistente
+- **Avisos**: dependência que não rastreia a Feature nenhuma (recurso sem dono — quem cria?), sobreposição do slug com caminhos do código, decisão de modelagem do `tech_context.yml` com `criada_por: SEM DONO`, spec ausente ou fora do template
+- Com `--critique`: os **findings da crítica de conjunto** — uma chamada de modelo sobre todas as specs juntas, procurando a mesma regra contada de dois jeitos. Cada finding cita as Features envolvidas (`#412 × #415`); grave conta como material
+
+## Passos
+
+1. Rode depois que as specs da milestone existirem (geradas ou em PR — as quatro camadas entram), tipicamente como Fase 3.5 da skill **preparar-specs**.
+2. **Confira os avisos heurísticos antes de reportar** — a extração é sobre prosa livre; falso positivo custa uma leitura, não uma decisão.
+3. Achado material é decisão de PO: comente nas issues **dos dois lados**, apontando uma para a outra, e resolva antes de gerar os planos.
+4. `--critique` paga modelo — em rodadas repetidas, rode o determinístico primeiro e a crítica só quando o conjunto estabilizar.

package/src/plugin/skills/audit/model-prompt.critique.md

@@ -0,0 +1,34 @@
+---
+name: critique-conjunto
+action: critique
+description: Critério da crítica adversarial do CONJUNTO de specs de uma milestone — contradição entre documentos, não dentro de um.
+lenses:
+  - "regra compartilhada — a mesma regra (teto, prioridade, janela de tempo) contada de formas que não fecham em duas specs?"
+  - "dependência — as duas pontas concordam com a direção e o escopo do que uma declara depender da outra?"
+  - "afirmação sobre o mundo — uma spec afirma algo ('tal feature não existe', 'isso é feito por X') que outra spec do conjunto desmente?"
+---
+
+# Crítica adversarial do conjunto de specs
+
+Você audita TODAS as specs de uma milestone, **umas contra as outras**. Cada documento já passou por crítica individual — não repita esse trabalho. Seu papel é achar o que só existe **no par**: cada spec, sozinha, parece certa, e o erro vira dois comportamentos incompatíveis em produção, descobertos na integração.
+
+Os checks determinísticos (ciclo de dependência, inversão de milestone, referência inexistente) já rodaram ANTES de você. Não os repita: seu valor é o julgamento semântico que um grep não faz.
+
+## O que caracteriza um achado
+
+- **Regra compartilhada que não fecha** — um limite, uma ordem de prioridade ou uma janela de tempo que aparece em mais de uma spec com valores, contagens ou marcos de início diferentes.
+- **Dependência em que as pontas discordam** — a spec A declara que seu componente vive na feature B, e a spec de B não menciona esse componente; ou A e B declaram depender uma da outra com escopos que não se encaixam.
+- **Afirmação desmentida pelo conjunto** — uma spec afirma "tal recurso ainda não existe" ou "isso é responsabilidade de X" e outra spec do conjunto mostra o contrário.
+- **Comportamento duplicado** — duas specs descrevendo, com palavras diferentes, a mesma funcionalidade; implementadas as duas, o sistema terá dois caminhos para a mesma coisa.
+
+## O que NÃO é achado
+
+- Problema interno de uma spec só (regra ambígua, seção fraca, TODO) — isso é da crítica individual, que já rodou.
+- Estilo, redação, nível de detalhe diferente entre specs.
+- Lacuna paramétrica (falta um número, um prazo) — a menos que duas specs declarem **valores conflitantes** para o mesmo parâmetro.
+
+## Barra de rigor
+
+NÃO invente problemas. Um conjunto consistente é um resultado legítimo e frequente — specs geradas da mesma fonte normativa costumam concordar.
+
+Antes de registrar um achado entre duas specs, releia AS DUAS passagens: se elas são compatíveis lidas com atenção (uma detalha, a outra resume), não há achado. Só é "grave" o que, implementado como está escrito, produz comportamentos incompatíveis ou trabalho duplicado.

package/src/plugin/skills/merge/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: spec-wave-merge
+description: "Use para mergear os PRs empilhados das Stories de uma Feature do spec-wave, na ordem das dependências, movendo o board até 🧪 QA. Gatilhos: 'mergeia os PRs da feature 12', 'integra as stories', 'os PRs estão revisados, pode mergear', 'qual a ordem de merge?'. Use DEPOIS da revisão humana (PRs marcados como prontos). NÃO mergeie PRs de pilha à mão com --delete-branch — é o que fecha o PR dependente."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh pr *)
+  - Read
+---
+
+# spec-wave merge — o passo final, na ordem certa
+
+Comando **local** (dentro do Actions o merge é decisão humana):
+
+```bash
+npx @spec-wave/cli@latest merge <feature>              # mostra o plano e para
+npx @spec-wave/cli@latest merge <feature> --yes        # executa
+npx @spec-wave/cli@latest merge <feature> --keep-branches
+```
+
+O `implement` empilha os PRs de propósito (cada Story revisável sozinha, diff limpo), mas a pilha torna o merge **ordem-dependente e frágil**: `--delete-branch` no primeiro PR fecha o segundo sem volta. Este comando encapsula a sequência segura — para cada PR na ordem topológica: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (`code-review` + `qa` — merge move até 🧪 QA) e **só no fim** apaga as branches.
+
+## O que saber antes de rodar
+
+- **Sem `--yes` nada é mergeado** — a saída é o plano: a fila na ordem, qual base será reapontada, o que já está mergeado.
+- **PR em rascunho bloqueia o plano inteiro.** Marcar pronto é a revisão humana (e o que dispara o CI) — revise e marque cada PR como pronto antes. O comando não faz isso por você, de propósito.
+- **Rodar de novo retoma.** PR mergeado sai do plano sozinho; uma falha no meio (check pendente, conflito) para a fila com as branches dos dependentes intactas.
+- Story **sem PR** vira aviso, não bloqueio — mas se um PR da fila depende do código dela, o merge leva esse código junto; confira antes de confirmar.
+
+## Passos
+
+1. Confirme que os PRs da Feature foram revisados e marcados como prontos (`gh pr ready <n>` se preciso).
+2. Rode sem `--yes` e apresente o plano ao usuário — ordem, retargets, avisos.
+3. Com o ok, rode com `--yes`.
+4. Confira o desfecho na saída: N PRs mergeados, board em 🧪 QA (o próprio comando confirma as escritas do board; se algum falhar, ele indica o `run --pr` de reparo).

package/src/plugin/skills/order/SKILL.md

@@ -29,6 +29,7 @@ npx @spec-wave/cli@latest order             # o mapa de todas as Features com tr
 - A **Etapa atual** de cada Story no board
 - Avisos de **ciclo de dependência** — essas Stories ficam **fora da ordem**; corrija as linhas `Depende de:`
 - Avisos de **dependência fora de ordem** — Story já em 🚧 Desenvolvimento ou além dependendo de outra que não está em 🎉 Done (no modo de uma Feature, também quando a bloqueadora é de **outra** Feature e continua aberta)
+- Avisos de **milestone divergente** (modo de uma Feature) — Story sem milestone, ou em milestone diferente do da Feature. É a outra órfã do pós-apply, além de `Etapa: —`: a Story some de toda visão de release e ninguém percebe. Sem milestone na Feature, nada é comparado
 - **Bloqueadas por fora desta Feature** (modo de uma Feature) — dependências `#N` que não entram na ordenação porque a Story bloqueadora não está no conjunto, com o estado de cada uma. No modo sem argumento essa seção lista só o que ficou fora do board (Story concluída, Feature em Done, outro board)
 
 ## Passos

package/src/plugin/skills/plan/model-prompt.md

@@ -54,6 +54,7 @@ O plano deve conter EXATAMENTE estas seções em português, nesta ordem:
 
 - TODA mudança de banco, endpoint de API ou componente de UI DEVE referenciar um Critério de Aceite específico do spec.md (rastreabilidade).
 - Use APENAS as tecnologias e serviços listados no tech_context fornecido. Não invente APIs ou serviços inexistentes.
+- Se o plano depender de um recurso que `decisoes_de_modelagem` declara com `criada_por: SEM DONO`, registre `[TODO: requer esclarecimento do PO]` apontando que o recurso não tem Feature criadora — não presuma que ele existirá.
 - Forneça detalhes acionáveis: caminhos exatos de endpoints, nomes de DTOs, constraints de banco.
 - Escreva em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
 - O arquivo deve conter APENAS o conteúdo do plan.md — nada de preâmbulo, comentário sobre o processo ou resumo do que você fez.

package/src/plugin/skills/plan/reference/tech-context.md

@@ -43,8 +43,14 @@ O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve se
        auth: "<ex.: JWT, mTLS>"
    internal_libraries:
      - "<lib interna>"
+   decisoes_de_modelagem:        # opcional — recursos COMPARTILHADOS entre features
+     - recurso: "<nome>"
+       decisao: "<a modelagem decidida>"
+       criada_por: "<FT-xx.y | #N | SEM DONO>"
    ```
 
+   Em `decisoes_de_modelagem`, o campo `criada_por:` é **obrigatório por entrada**: é ele que transforma "não existe feature que crie isso" de nota perdida em pendência — `SEM DONO` aparece no `spec-wave audit` como item de checklist antes de planejar a milestone.
+
 4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar — ele conhece serviços internos e roles que o código pode não revelar.
 
 5. **Grave** com Write em `.github/config/tech_context.yml`.