@spec-wave/cli 0.32.0 → 0.34.0

package/src/lib/commit-trailers.mjs

@@ -0,0 +1,134 @@
+// Rastro verificável de Story/Task no commit — item 6 do rfc/plano-hardening-
+// agentes-2026-08.md.
+//
+// O assunto do commit é prosa: nada no CLI o formata (o `implement.mjs:405`
+// só pede "faça o commit"), e o `feature_prompt` do daemon pede um formato
+// que ninguém verifica. Um script de verificação que lê o ASSUNTO dá falso
+// negativo assim que o modelo escreve algo mais descritivo — foi o que
+// aconteceu com 7 Stories reais da #734. `git trailer` é a parte que não
+// varia: sobrevive a squash, rebase e reescrita de assunto, e
+// `git log --format='%(trailers:key=...)'` lê sem depender de convenção.
+//
+// Módulo PURO: render/parse de texto, sem git nem I/O.
+
+import { execFileSync } from 'node:child_process';
+import { TRAILER_STORY, TRAILER_TASKS, TRAILER_AGENT } from '../config.mjs';
+
+// Uma linha de trailer é "Chave: valor" — mesma forma que `git interpret-
+// trailers` reconhece. Só suportamos trailer de uma linha (nunca precisamos
+// de mais que isso aqui).
+const TRAILER_LINE_RE = /^([A-Za-z][\w-]*):\s*(.+)$/;
+
+/**
+ * Monta o bloco de trailers para colar no rodapé do commit (função PURA).
+ *
+ * @param {object} params
+ * @param {number|string} [params.story] número da Story
+ * @param {Array<number|string>} [params.tasks] números das Tasks
+ * @param {string} [params.agent] identificador do executor (ex.: 'spec-wave-agent')
+ * @returns {string} bloco pronto para colar — vazio se nada foi passado
+ */
+export function renderTrailers({ story, tasks = [], agent } = {}) {
+  const lines = [];
+  if (story !== undefined && story !== null && story !== '') {
+    lines.push(`${TRAILER_STORY}: #${String(story).replace(/^#/, '')}`);
+  }
+  if (tasks && tasks.length > 0) {
+    lines.push(`${TRAILER_TASKS}: ${tasks.map(t => `#${String(t).replace(/^#/, '')}`).join(', ')}`);
+  }
+  if (agent) {
+    lines.push(`${TRAILER_AGENT}: ${agent}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Lê os trailers do BLOCO FINAL de uma mensagem de commit (função PURA).
+ *
+ * Só o bloco final conta: caminha da última linha não-vazia para trás
+ * enquanto as linhas casarem "Chave: valor", e para no primeiro que não casa
+ * — o mesmo contrato de `git interpret-trailers`. Um trailer que apareça no
+ * meio do corpo (citado em prosa, por exemplo) não é o rastro real.
+ *
+ * @param {string} message corpo completo do commit (ex.: `git log --format=%B`)
+ * @returns {{ story: number|null, tasks: number[], agent: string|null }}
+ */
+export function parseTrailers(message = '') {
+  const lines = String(message).replace(/\r\n?/g, '\n').split('\n');
+  let end = lines.length;
+  while (end > 0 && lines[end - 1].trim() === '') end--;
+  let start = end;
+  while (start > 0 && TRAILER_LINE_RE.test(lines[start - 1])) start--;
+  const block = lines.slice(start, end);
+
+  const out = { story: null, tasks: [], agent: null };
+  for (const line of block) {
+    const m = TRAILER_LINE_RE.exec(line);
+    if (!m) continue;
+    const [, key, rawValue] = m;
+    const value = rawValue.trim();
+    if (key === TRAILER_STORY) {
+      const n = parseInt(value.replace('#', ''), 10);
+      if (Number.isInteger(n)) out.story = n;
+    } else if (key === TRAILER_TASKS) {
+      out.tasks = value
+        .split(',')
+        .map(s => parseInt(s.trim().replace('#', ''), 10))
+        .filter(Number.isInteger);
+    } else if (key === TRAILER_AGENT) {
+      out.agent = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Quais Stories/Tasks esperadas não aparecem em NENHUM commit (função PURA).
+ *
+ * A verificação que hoje é script à mão contra o ASSUNTO do commit (e falha
+ * assim que o modelo escreve algo mais descritivo, como aconteceu com 7
+ * Stories reais da #734) vira leitura de trailer: basta UM commit, entre
+ * quantos existirem no branch/PR, trazer o trailer certo.
+ *
+ * @param {string[]} messages corpos de commit (ex.: um por commit do branch/PR)
+ * @param {{ stories?: number[], tasks?: number[] }} expected o que deveria
+ *        aparecer — normalmente `[story.number]` e os números das Tasks
+ * @returns {{ missingStories: number[], missingTasks: number[] }}
+ */
+export function missingTrailers(messages = [], { stories = [], tasks = [] } = {}) {
+  const seenStories = new Set();
+  const seenTasks = new Set();
+  for (const msg of messages) {
+    const t = parseTrailers(msg);
+    if (t.story != null) seenStories.add(t.story);
+    for (const n of t.tasks) seenTasks.add(n);
+  }
+  return {
+    missingStories: stories.filter(s => !seenStories.has(s)),
+    missingTasks: tasks.filter(t => !seenTasks.has(t)),
+  };
+}
+
+/**
+ * Mensagens dos commits mais recentes do checkout local (I/O — best-effort,
+ * NUNCA lança). Usado por `implement --verify-commits`.
+ *
+ * Por CONTAGEM, não por range contra uma branch base: `implement` não cria
+ * branch (quem cria é o executor ou o daemon) e não sabe de forma confiável
+ * qual é o remoto/branch base neste checkout. Um teto generoso cobre o caso
+ * real (uma Story tem poucos commits) sem depender de configuração de git.
+ *
+ * @param {string} cwd raiz do checkout
+ * @param {number} [limit]
+ * @returns {string[]}
+ */
+export function readLocalCommitMessages(cwd, limit = 50) {
+  try {
+    const out = execFileSync('git', ['log', `-n${limit}`, '--format=%B%x1e'], {
+      cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return out.split('\x1e').map(s => s.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/lib/delivery-mode.mjs

@@ -0,0 +1,26 @@
+// Modo de entrega da implementação — quem cria branch e abre PR.
+//
+// O daemon Rust (spec-wave-agent) mantém UM branch e UM PR por issue
+// (`agent/issue-<n>`, criado em `runner.rs:59-61`) e abre o PR ele mesmo ao
+// final da execução (`open_pull_request`, `runner.rs:77`, chamada tanto para
+// Bug quanto para Feature — `main.rs:171`). O contexto que o `implement`
+// monta não pode instruir o modelo a criar branch nem abrir PR nesse modo:
+// as duas coisas já existem, e a instrução de "abra o PR da Story" — certa no
+// fluxo manual de PR empilhado — é o que produzia `agent/issue-<n>-story-<m>`,
+// um branch lateral cujo trabalho nunca entra no PR que o daemon abre.
+//
+// Função PURA: a detecção não faz I/O, recebe env e branch já resolvidos.
+
+const AGENT_BRANCH_RE = /^agent\/issue-\d+$/;
+
+/**
+ * @param {object} [params]
+ * @param {NodeJS.ProcessEnv} [params.env] variáveis de ambiente
+ * @param {string|null} [params.branch] branch git atual (HEAD), se conhecida
+ * @returns {'agent'|'pr-stack'}
+ */
+export function deliveryMode({ env = process.env, branch = null } = {}) {
+  if (env?.SPEC_WAVE_DEV_AGENT === '1') return 'agent';
+  if (branch && AGENT_BRANCH_RE.test(branch)) return 'agent';
+  return 'pr-stack';
+}

package/src/lib/rate-budget.mjs

@@ -0,0 +1,36 @@
+// Orçamento de rate limit para checks caros do `doctor` (função PURA).
+//
+// Item 5 do rfc/plano-hardening-agentes-2026-08.md: o `checkDecompositions`
+// fazia até 1 GraphQL por Story sem nenhuma noção de cota, e com a cota
+// estourada o modo degradado do doctor pintava seis checks de "!" sem dizer
+// que a causa era a mesma — o próprio doctor piorando o esgotamento que
+// estava diagnosticando. A correção é medir ANTES de gastar (getRateLimit,
+// que não custa pontos) e decidir aqui, fora de qualquer I/O.
+
+/** Reserva default: fica de fora do orçamento de um check para sobrar cota
+ *  para o resto da sessão (outro comando, o próprio executor do dev-agent). */
+export const DEFAULT_RESERVE = 200;
+
+/**
+ * Um check caro pode rodar?
+ *
+ * `remaining: null` (cota não pôde ser medida) SEMPRE roda — "não sei" não
+ * pode virar "não posso": um doctor sem acesso ao endpoint de rateLimit não
+ * deveria ficar mais cego do que já era antes desta correção existir.
+ *
+ * @param {object} params
+ * @param {number|null} params.remaining pontos restantes (getRateLimit().remaining)
+ * @param {number} params.estimated custo estimado do check, em pontos
+ * @param {number} [params.reserve] pontos que ficam de fora do orçamento
+ * @param {string|null} [params.resetAt] ISO do reset, só para a mensagem
+ * @returns {{ run: boolean, motivo: string|null }}
+ */
+export function affordCheck({ remaining, estimated, reserve = DEFAULT_RESERVE, resetAt = null } = {}) {
+  if (remaining === null || remaining === undefined) return { run: true, motivo: null };
+  if (remaining - reserve >= estimated) return { run: true, motivo: null };
+  const quando = resetAt ? ` (reset ${new Date(resetAt).toLocaleTimeString('pt-BR')})` : '';
+  return {
+    run: false,
+    motivo: `restam ${remaining} pontos de GraphQL${quando} e este check custaria ~${estimated} — pulado para não esgotar a cota.`,
+  };
+}

package/src/lib/spec-audit.mjs

@@ -29,26 +29,67 @@ const norm = (s) => String(s || '')
 // Título sem o prefixo [FEATURE]/[BUG]/etc., para casar com a prosa.
 const bareTitle = (title) => String(title || '').replace(/^\s*\[.*?\]\s*/, '').trim();
 
+// H1 a H3 com "Dependências" logo após os `#` — aceita sufixo ("Dependências e
+// Premissas", "Dependências (Internas e Externas)"), não só o título exato.
+const DEPENDENCY_HEADING_RE = /^(#{1,3})\s+depend[êe]ncias\b/i;
+
 /**
- * O texto da seção `# Dependências` de uma spec (PURA).
+ * O texto da seção de 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).
+ * Heading `#`/`##`/`###` com "Dependências" no início (sufixo livre — item 3
+ * do rfc/plano-hardening-agentes-2026-08.md: `# Dependências e Premissas` e
+ * `## Dependências` também casam agora, não só o H1 exato). Fecha no próximo
+ * heading de nível IGUAL OU MENOR (menos ou igual `#`s) — os `## Internas`/
+ * `## Externas` ficam dentro quando o heading casado é H1. `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())));
+  let start = -1;
+  let level = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = DEPENDENCY_HEADING_RE.exec(norm(lines[i]).trim());
+    if (m) { start = i; level = m[1].length; break; }
+  }
   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; }
+    const h = /^(#{1,6})\s+\S/.exec(lines[i]);
+    if (h && h[1].length <= level) { end = i; break; }
   }
   return lines.slice(start + 1, end).join('\n');
 }
 
+// Bullet/linha "Nenhuma"/"N/A"/vazia — resposta legítima do gerador, mesmo
+// texto que `untraceableBullets` já usa para não flagar como órfã.
+const EMPTY_ANSWER_RE = /^(nenhuma|n\/a|—|-)\.?$/i;
+
+/**
+ * A seção de Dependências está vazia de propósito (PURA)?
+ *
+ * "Vazia" = toda linha com conteúdo (fora headings de subseção) é uma
+ * resposta tipo "Nenhuma"/"N/A" — bullet ou prosa solta. Distingue de "sem
+ * alvo" (item 3a do plano): há prosa real, só que `mentionedIssues` não
+ * conseguiu resolvê-la a nenhuma Feature do catálogo.
+ *
+ * @param {string} section
+ * @returns {boolean}
+ */
+export function dependencySectionIsEmpty(section = '') {
+  for (const linha of String(section).split('\n')) {
+    const trimmed = linha.trim();
+    if (!trimmed) continue;
+    if (/^#{1,6}\s+/.test(trimmed)) continue; // heading de subseção (## Internas)
+    const bullet = trimmed.match(/^[-*]\s+(.*\S)\s*$/);
+    const conteudo = bullet ? bullet[1] : trimmed;
+    if (!EMPTY_ANSWER_RE.test(norm(conteudo).trim())) return false;
+  }
+  return true;
+}
+
 /**
  * Todas as referências `#N` de um texto (PURA).
  *
@@ -107,20 +148,40 @@ export function mentionedIssues(text = '', catalog = [], selfNumber = null) {
  * 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.
  *
+ * Reconhece DUAS formas de marcar a subseção (item 3d do rfc/plano-
+ * hardening-agentes-2026-08.md): o heading `## Internas` e o bullet-rótulo
+ * `- **Internas:** ...` que `templates/issue/spec-template.md` de fato gera —
+ * sem a segunda forma, o recorte falhava e a seção inteira (Internas +
+ * Externas) virava alvo, sinalizando toda dependência Externa como órfã.
+ *
  * @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) {
+
+  const headingIdx = lines.findIndex(l => /^#{2,}\s+.*internas/i.test(norm(l)));
+  if (headingIdx !== -1) {
     let fim = lines.length;
-    for (let i = começo + 1; i < lines.length; i++) {
+    for (let i = headingIdx + 1; i < lines.length; i++) {
       if (/^#{2,}\s+\S/.test(lines[i])) { fim = i; break; }
     }
-    alvo = lines.slice(começo + 1, fim);
+    alvo = lines.slice(headingIdx + 1, fim);
+  } else {
+    const bulletIdx = lines.findIndex(l => /^\s*[-*]\s+\*{0,2}internas\*{0,2}\s*:?/i.test(norm(l)));
+    if (bulletIdx !== -1) {
+      let fim = lines.length;
+      for (let i = bulletIdx + 1; i < lines.length; i++) {
+        if (/^\s*[-*]\s+\S/.test(lines[i])) { fim = i; break; } // próximo bullet de topo (Externas)
+      }
+      // Tira o rótulo "Internas:" da própria linha, preservando o marcador de
+      // lista — o que sobra entra no mesmo scanner de bullets abaixo.
+      alvo = lines.slice(bulletIdx, fim).map((l, i) => (i === 0
+        ? l.replace(/^(\s*[-*]\s+)\*{0,2}internas\*{0,2}:?\*{0,2}\s*/i, '$1')
+        : l));
+    }
   }
   const out = [];
   for (const line of alvo) {
@@ -128,7 +189,7 @@ export function untraceableBullets(section = '', catalog = []) {
     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 (EMPTY_ANSWER_RE.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);
@@ -229,8 +290,14 @@ export function unownedDecisions(staticContext = {}) {
  *
  * @param {object} params
  * @param {Array<{number:number, title:string, slug?:string, spec?:string|null,
+ *         specState?:'local'|'remote'|'pending-pr'|'branch-only'|'missing'|'unknown'|null,
  *         milestone?:{number?:number, title?:string, due_on?:string|null}|null}>}
- *        params.features Features ABERTAS da milestone-alvo, com o conteúdo da spec
+ *        params.features Features ABERTAS da milestone-alvo, com o conteúdo da spec.
+ *        `specState` (opcional) distingue "não existe" (`missing`) de "não deu
+ *        para verificar agora" (`unknown` — rede/permissão), o mesmo estado
+ *        que `loadArtifact` já produz — item 8 do rfc/plano-hardening-
+ *        agentes-2026-08.md. Sem `specState`, `spec` nulo sempre cai em
+ *        `semSpec` (comportamento de antes, retrocompatível).
  * @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
@@ -239,8 +306,8 @@ export function unownedDecisions(staticContext = {}) {
  * @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[]}>,
+ *   semSpec: number[], specIndisponivel: number[], semSecao: number[],
+ *   grafo: Array<{number:number, dependsOn:number[], secao:'ok'|'vazia'|'sem-alvo'}>,
  *   ciclos: number[],
  *   inversoes: Array<{feature:number, dep:number, featureMilestone:string, depMilestone:string}>,
  *   bloqueantesSemMilestone: Array<{feature:number, dep:number}>,
@@ -254,6 +321,7 @@ export function auditMilestone({
 } = {}) {
   const byNumber = new Map(catalog.map(f => [f.number, f]));
   const semSpec = [];
+  const specIndisponivel = [];
   const semSecao = [];
   const grafo = [];
   const inversoes = [];
@@ -268,12 +336,26 @@ export function auditMilestone({
     const hits = codeOverlap(slug, files);
     if (hits.length > 0) sobreposicoes.push({ feature: f.number, slug, hits });
 
-    if (!f.spec) { semSpec.push(f.number); continue; }
+    if (!f.spec) {
+      // 'unknown' = rede/permissão falhou ao verificar, não que a spec não
+      // exista — afirmar "sem spec" aqui é exatamente o erro que o preflight
+      // já corrigiu (PRs #65/#66) e que o audit herdou por reusar loadArtifact
+      // sem herdar a distinção (item 8 do rfc/plano-hardening-agentes-2026-08.md).
+      if (f.specState === 'unknown') specIndisponivel.push(f.number);
+      else 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 });
+    // 'ok' = achou aresta legível; 'vazia' = a seção diz "Nenhuma" de propósito
+    // (legível, só que sem dependências); 'sem-alvo' = há prosa real mas nada
+    // dela resolveu a uma Feature do catálogo — item 3a do rfc/plano-
+    // hardening-agentes-2026-08.md: sem isso, os dois casos produziam o MESMO
+    // `dependsOn: []` mudo, indistinguível de "auditada, sem dependências".
+    const secao = deps.length > 0 ? 'ok' : (dependencySectionIsEmpty(section) ? 'vazia' : 'sem-alvo');
+    grafo.push({ number: f.number, dependsOn: deps, secao });
 
     const mortas = issueRefs(section).filter(n => missingRefs.includes(n));
     if (mortas.length > 0) inexistentes.push({ feature: f.number, refs: mortas });
@@ -302,7 +384,7 @@ export function auditMilestone({
   const { cycle } = orderStories(grafo);
 
   return {
-    semSpec, semSecao, grafo, ciclos: cycle, inversoes,
+    semSpec, specIndisponivel, semSecao, grafo, ciclos: cycle, inversoes,
     bloqueantesSemMilestone, inexistentes, naoRastreaveis, sobreposicoes,
     semDono: unownedDecisions(techContext || {}),
   };
@@ -339,12 +421,26 @@ export function auditVerdict(audit) {
   if (audit.semSpec.length > 0) {
     avisos.push(`Sem spec para auditar: ${lista(audit.semSpec)}.`);
   }
+  if ((audit.specIndisponivel || []).length > 0) {
+    avisos.push(`Spec não verificável agora (rede/permissão) — não é ausência: ${lista(audit.specIndisponivel)}.`);
+  }
   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.`);
   }
+  // secao 'sem-alvo': a seção tem prosa real, mas NADA dela resolveu a uma
+  // Feature do catálogo — o `dependsOn: []` resultante era, antes deste
+  // item, indistinguível de "auditada, sem dependências" (item 3a do rfc/
+  // plano-hardening-agentes-2026-08.md).
+  const semAlvo = audit.grafo.filter(g => g.secao === 'sem-alvo');
+  for (const g of semAlvo) {
+    avisos.push(
+      `#${g.number} declara dependências em prosa que não rastreiam nenhuma Feature — ` +
+      'o grafo desta Feature está vazio (cite `#N` na seção para torná-la legível).'
+    );
+  }
   for (const n of audit.naoRastreaveis) {
     avisos.push(
       `#${n.feature} declara ${n.bullets.length} dependência(s) que não rastreiam a nenhuma Feature — ` +
@@ -366,7 +462,27 @@ export function auditVerdict(audit) {
     );
   }
 
-  if (materiais.length) return { status: 'problema', materiais, avisos };
-  if (avisos.length) return { status: 'aviso', materiais, avisos };
-  return { status: 'ok', materiais, avisos };
+  let status;
+  if (materiais.length) status = 'problema';
+  else if (avisos.length) status = 'aviso';
+  else status = 'ok';
+
+  // Cobertura do grafo (item 3b): a linha resume quanto do grafo é legível —
+  // é o que faltava para quem lê "ok" saber se isso significa "conferi e
+  // fecha" ou "não consegui ler quase nada". Não precisa de um limiar próprio
+  // para rebaixar o status: toda causa de baixa cobertura (semSpec,
+  // specIndisponivel, semSecao, 'sem-alvo') já gera o SEU PRÓPRIO aviso acima
+  // — 100% de cobertura é a única forma de `avisos` continuar vazio, então
+  // "ok" e "grafo incompleto" nunca coexistem por construção.
+  const specIndisponivel = audit.specIndisponivel || [];
+  const total = audit.grafo.length + audit.semSpec.length + specIndisponivel.length + audit.semSecao.length;
+  const legiveis = audit.grafo.filter(g => g.secao === 'ok' || g.secao === 'vazia').length;
+  if (total > 0) {
+    const partes = [`${audit.semSecao.length} sem seção`, `${semAlvo.length} sem alvo`];
+    if (audit.semSpec.length) partes.push(`${audit.semSpec.length} sem spec`);
+    if (specIndisponivel.length) partes.push(`${specIndisponivel.length} indisponível(is)`);
+    avisos.unshift(`Grafo: ${legiveis}/${total} Feature(s) com arestas legíveis (${partes.join(', ')}).`);
+  }
+
+  return { status, materiais, avisos };
 }

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

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.32.0",
+  "version": "0.34.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/skills/audit/SKILL.md

@@ -21,9 +21,9 @@ A crítica do fluxo normal audita cada documento contra os insumos da **mesma**
 
 ## 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)
+- O **grafo de dependências entre Features**, extraído da seção de Dependências (heading `#`/`##`/`###` começando com "Dependências" — aceita sufixo, ex.: "Dependências e Premissas") por `#N`, slug e título (best-effort sobre prosa). Uma linha `Grafo: N/M Feature(s) com arestas legíveis (...)` sempre abre os avisos — cobertura baixa é sinal de que a auditoria não leu quase nada, mesmo quando não há achado material
 - **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
+- **Avisos**: dependência que não rastreia a Feature nenhuma (recurso sem dono — quem cria?), seção com prosa que não resolveu a NENHUMA Feature (`#123 ⟨sem arestas legíveis⟩` no grafo — distinto de uma seção que diz "Nenhuma" de propósito), sobreposição do slug com caminhos do código, decisão de modelagem do `tech_context.yml` com `criada_por: SEM DONO`, spec ausente, spec não verificável agora (rede/permissão — não é ausência), ou spec fora do template (sem a seção de Dependências)
 - 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

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

@@ -9,20 +9,24 @@ allowed-tools:
 
 # spec-wave doctor — preflight de auth e configuração
 
-Comando **local**, sem flags:
+Comando **local**:
 
 ```bash
 npx @spec-wave/cli@latest doctor
+npx @spec-wave/cli@latest doctor --deep   # confere também as Tasks de cada decomposição
 ```
 
 ## O que ele checa
 
-- **Token GitHub** e a fonte dele; **escopos** (`repo`, `project`, `workflow`), com degradação para checks funcionais em fine-grained PATs
+- **Token GitHub** e a fonte dele
+- **Cota da API (GraphQL)**: pontos restantes e horário do reset — medido de graça (a consulta não custa pontos) e usado pelos checks abaixo para decidir se cabem no orçamento
+- **Escopos** (`repo`, `project`, `workflow`), com degradação para checks funcionais em fine-grained PATs
 - **Conta ativa do `gh`** vs. o owner do repositório
 - **`.spec-wave.json`**: campos presentes e sincronia com o Project real
 - **Acesso ao repositório**
 - **Configuração de IA**: provider, modelo, `ai.models`, escalada da crítica, apelidos de modelo, teto de saída e os secrets do Actions
 - **Higiene do board e das labels**: colunas fora do fluxo canônico, labels `spec-wave:*` descontinuadas ou ausentes
+- **Decomposições aplicadas**: `decomposition.md` × issues reais. Por padrão confere só até o nível de Story (1 chamada por Feature); `--deep` desce até as Tasks (1 chamada a mais por Story) — mais completo, mais caro. Se a cota estiver baixa, o check é pulado com a causa explícita em vez de estourar em silêncio.
 - **spec-kit**: `specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, sugere exemplos por agente (Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code)
 - **Workflows**: presença + **versão da CLI fixada** (não `@latest`)
 

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

@@ -25,6 +25,7 @@ Comando **local** (lê o `.spec-wave.json`, como o `issue`), **não** disparado
 | `<issue>` | **Obrigatório**, posicional. Número da Feature, Story ou Task (`12` ou `#12`). |
 | `--feature-dir <path>` | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` (sobrescreve a resolução automática). |
 | `--dry-run` | Monta o contexto e imprime o comando **sem executar** e **sem escrever nada no GitHub**. |
+| `--verify-commits` | Depois de executar, confere se os commits recentes trazem o trailer `Spec-Wave-Story`/`Spec-Wave-Tasks` (rastro verificável, não depende do assunto do commit). Best-effort — nunca bloqueia. |
 
 **Pré-requisitos:** `.spec-wave.json` presente (senão → skill **setup**) e a issue ser Feature, Story ou Task. Para executar de fato, o spec-kit precisa estar configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`.
 
@@ -78,15 +79,20 @@ npx @spec-wave/cli@latest task start <n>   # Etapa 🚧 Desenvolvimento + Status
 npx @spec-wave/cli@latest task done <n>    # Etapa 🎉 Done + Status Done
 ```
 
-**Ao concluir toda a Story:** faça o commit, abra o PR e mova a Story:
+**Ao concluir toda a Story:** faça o commit e mova a Story. O **assunto** do commit é livre (o que você achar mais claro), mas o **rodapé** precisa trazer o rastro exato que o contexto montado dita — `Spec-Wave-Story: #<n>` e `Spec-Wave-Tasks: #<n>, #<n>...` — copiado literalmente, sem alterar as chaves. É esse rodapé, não o assunto, que `--verify-commits` e o `merge` conferem:
 
 ```bash
 npx @spec-wave/cli@latest story review <n>  # Etapa 👀 Code Review, Status Todo
 ```
 
+Se abre PR e onde faz push depende do **modo de entrega** — o contexto montado já diz qual é (não adivinhe pelo tipo de issue):
+
+- **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`) antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha.
+- **`agent`** (rodando sob o `dev-agent`): **NÃO crie branch, NÃO abra PR** — faça só o commit e o push no branch atual. O daemon mantém um único branch (`agent/issue-<n>`) e é ele quem abre o PR ao final, para a Feature inteira. Abrir um PR por Story aqui cria um branch lateral (`agent/issue-<n>-story-<m>`) cujo trabalho não entra no PR do agente.
+
 **A Feature só avança** para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. No modo Feature isso acontece dentro da mesma execução.
 
-**No modo Feature**, siga o contexto Story a Story, **na ordem listada**: implemente as Tasks, depois commit + PR + `story review`; só então passe à próxima Story.
+**No modo Feature**, siga o contexto Story a Story, **na ordem listada**: implemente as Tasks, depois commit (+ PR só em modo `pr-stack`) + `story review`; só então passe à próxima Story.
 
 > **Aviso de dependência pendente** no contexto (a issue depende de outra não concluída, via `Depende de: #N` ou *blocked by*) → **confirme com o usuário** antes de seguir fora de ordem.
 

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

@@ -26,6 +26,7 @@ O `implement` empilha os PRs de propósito (cada Story revisável sozinha, diff
 - **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.
+- Cada PR da fila é conferido contra o trailer `Spec-Wave-Story: #<n>` (rastro do `implement`, best-effort — nunca bloqueia): PR sem nenhum commit com o trailer certo vira aviso, vale conferir se é mesmo o trabalho daquela Story antes de mergear.
 
 ## Passos
 

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

@@ -48,7 +48,7 @@ O spec deve conter EXATAMENTE estas seções em português, nesta ordem:
   - OBRIGATORIAMENTE no formato Gherkin, dentro de um bloco ```gherkin com
     Given/When/Then. Um cenário por critério.
 # Dependências
-  - Subdivida em Internas e Externas.
+  - Subdivida em `## Internas` e `## Externas` (subseções, não bullets).
 # Requisitos Não-Funcionais
   - Performance, Segurança e Usabilidade.
 ```

package/src/setup/labels.mjs

@@ -7,11 +7,12 @@ function sleep(ms) {
   return new Promise(r => setTimeout(r, ms));
 }
 
-// `fileAi` traz as labels de modelo derivadas de `ai.modelAliases`. No `init` ele
-// vem vazio (o config ainda nem foi gravado) e o conjunto é só o do fluxo; quem
-// cria as de modelo depois é o `update`, que já lê o config do repo.
-export async function setupLabels(token, owner, repo, spinner, fileAi) {
-  const labels = allLabelsFor(fileAi);
+// `fileAi` traz as labels de modelo derivadas de `ai.modelAliases`, o mesmo
+// vale para `devAgent` e as filas extra do dev-agent. No `init` os dois vêm
+// vazios (o config ainda nem foi gravado) e o conjunto é só o do fluxo; quem
+// cria as de modelo/fila depois é o `update`, que já lê o config do repo.
+export async function setupLabels(token, owner, repo, spinner, fileAi, devAgent) {
+  const labels = allLabelsFor(fileAi, devAgent);
   for (let i = 0; i < labels.length; i++) {
     const label = labels[i];
     spinner.message(`Criando label ${i + 1}/${labels.length}: ${label.name}`);

package/src/templates/issue/spec-template.md

@@ -44,8 +44,13 @@ Feature: [Nome da Feature]
 
 # Dependências
 
-- **Internas:** <!-- Serviços/APIs dentro do sistema -->
-- **Externas:** <!-- Sistemas de terceiros -->
+## Internas
+
+- <!-- Serviços/APIs dentro do sistema -->
+
+## Externas
+
+- <!-- Sistemas de terceiros -->
 
 # Requisitos Não-Funcionais