@spec-wave/cli 0.21.0 → 0.23.0

package/src/commands/order.mjs

@@ -1,24 +1,176 @@
-// Ordena as Stories de uma Feature pelas dependências (topológica, Kahn —
+// Ordena as Stories pelas dependências (topológica, Kahn —
 // ver orderStories em src/lib/dependencies.mjs). As dependências vêm de duas
 // fontes, mescladas: a linha "Depende de: #N" no corpo da Story e a relação
 // nativa blocked_by do GitHub.
 //
+// Dependência para FORA da Feature não entra na ordenação (não há como saber
+// onde a Story de outra Feature entra nesta sequência), mas é EXIBIDA: era lida,
+// descartada em silêncio por orderStories e ignorada de novo no aviso de
+// fora-de-ordem. Quem montava o mapa de trabalho de dois devs tinha que
+// reconstruir isso à mão, lendo os decomposition.md.
+//
+// Dois escopos: `order <feature>` (uma Feature) e `order` sem argumento — o
+// mapa de TODAS as Features com trabalho no board, onde as dependências entre
+// Features deixam de ser "externas" e entram no mesmo grafo.
+//
 // Comando LOCAL — rodado pelo dev no terminal. owner/repo vêm da env
 // GITHUB_REPOSITORY quando existir, senão do .spec-wave.json (gravado pelo init).
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, listBlockedBy } from '../api/github-rest.mjs';
-import { addProjectItem, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import {
+  addProjectItem, listSubIssues, getItemSingleSelectValue, listProjectItems,
+} from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
-import { loadProjectConfig, resolveField } from '../lib/board.mjs';
+import {
+  loadProjectConfig, resolveField, indexBoardItems, selectOpenFeatures,
+} from '../lib/board.mjs';
 import { resolveRepoContext } from '../lib/project-root.mjs';
 import { CONFIG_FILE, STAGE_ORDER, STAGE_DEVELOPMENT, STAGE_DONE } from '../config.mjs';
 
-export async function order({ feature: featureArg }) {
+/**
+ * Rótulo curto de uma Feature para a coluna do mapa (função PURA).
+ */
+export function featureLabel(feature) {
+  const titulo = String(feature?.title || '').replace(/^\s*\[FEATURE\]\s*/i, '').trim();
+  const curto = titulo.length > 28 ? `${titulo.slice(0, 27)}…` : titulo;
+  return `#${feature?.number} ${curto}`.trim();
+}
+
+/**
+ * O mapa de execução de várias Features (função PURA).
+ *
+ * Uma ordem SÓ, não uma lista por Feature: é isso que responde "o que os dois
+ * devs pegam agora" — a pergunta que obrigava a abrir nove decomposition.md e
+ * reconstruir o grafo à mão. A coluna da Feature vem junto porque, num grafo de
+ * várias, saber a que Feature cada Story pertence é metade da informação.
+ *
+ * @param {object} params
+ * @param {number[]} params.sorted ordem topológica (números de Story)
+ * @param {Map<number, {title:string, dependsOn:number[]}>} params.byNumber
+ * @param {Map<number, object>} params.featureOf Story → Feature dona
+ * @param {Map<number, string|null>} params.stageOf Story → Etapa
+ * @returns {string}
+ */
+export function renderBoardOrder({ sorted, byNumber, featureOf, stageOf }) {
+  return (sorted || []).map((n, i) => {
+    const s = byNumber.get(n);
+    const etapa = stageOf.get(n) || '—';
+    const deps = (s?.dependsOn || []).filter(d => byNumber.has(d));
+    const dep = deps.length > 0 ? `  ← depende de ${deps.map(d => `#${d}`).join(', ')}` : '';
+    return `${String(i + 1).padStart(2)}. #${n} ${s?.title || ''}\n` +
+      `    ${featureLabel(featureOf.get(n))} · Etapa: ${etapa}${dep}`;
+  }).join('\n');
+}
+
+/**
+ * `spec-wave order` sem argumento: o grafo de TODAS as Features com trabalho.
+ *
+ * Fonte do conjunto é o BOARD, não os arquivos — `decomposition.md` registra o
+ * que foi proposto, a issue é o que existe. Uma query paginada de itens do
+ * project resolve Etapa e tipo de todo mundo de uma vez, no lugar do laço de
+ * duas chamadas por Story que o modo de uma Feature ainda usa.
+ */
+async function orderBoard({ token, owner, repo }) {
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) {
+    p.log.error(
+      `${projectError} — sem board não há como saber quais Features têm trabalho. ` +
+      'Use `spec-wave order <feature>` para ordenar uma Feature específica.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let itens;
+  try {
+    itens = await listProjectItems(token, project.id);
+  } catch (err) {
+    p.log.error(`Não foi possível ler os itens do Project: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const indice = indexBoardItems(itens);
+  const features = selectOpenFeatures(itens);
+  if (features.length === 0) {
+    p.log.info(`Nenhuma Feature aberta fora de "${STAGE_DONE}" no board — nada a ordenar.`);
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  const enriched = [];
+  const featureOf = new Map();
+  const stageOf = new Map();
+  const semStories = [];
+  for (const feature of features) {
+    const subs = await listSubIssues(token, feature.nodeId).catch(() => []);
+    const stories = subs.filter(sub =>
+      detectIssueType({ title: sub.title, labels: sub.labels }) === 'Story');
+    if (stories.length === 0) { semStories.push(feature); continue; }
+    for (const story of stories) {
+      // Story concluída não entra: o mapa é do que falta fazer.
+      if (indice.get(story.number)?.fields?.Etapa === STAGE_DONE) continue;
+      const fromBody = parseDependencies(story.body);
+      const fromBlockedBy = (await listBlockedBy(token, owner, repo, story.number).catch(() => []))
+        .map(b => b.number);
+      enriched.push({
+        number: story.number,
+        title: story.title,
+        dependsOn: [...new Set([...fromBody, ...fromBlockedBy])],
+      });
+      featureOf.set(story.number, feature);
+      stageOf.set(story.number, indice.get(story.number)?.fields?.Etapa || null);
+    }
+  }
+
+  if (enriched.length === 0) {
+    p.log.info(`${features.length} Feature(s) aberta(s), nenhuma com Story pendente.`);
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  const byNumber = new Map(enriched.map(s => [s.number, s]));
+  const { order: sorted, cycle, external } = orderStories(
+    enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+
+  if (cycle.length > 0) {
+    p.log.warn(
+      chalk.yellow.bold('⚠ CICLO DE DEPENDÊNCIAS detectado!') + '\n' +
+      `Stories envolvidas (ou bloqueadas pelo ciclo): ${cycle.map(n => `#${n}`).join(', ')}.\n` +
+      'Elas ficaram fora da ordem abaixo. Num grafo de várias Features o ciclo pode ' +
+      'ATRAVESSAR a fronteira delas — confira as linhas "Depende de" dos dois lados.'
+    );
+  }
+
+  p.note(
+    renderBoardOrder({ sorted, byNumber, featureOf, stageOf }),
+    `Ordem de execução — ${sorted.length} Story(ies) de ${features.length} Feature(s)`
+  );
+
+  // Aqui "fora do conjunto" não é mais "de outra Feature" (essas agora estão
+  // DENTRO): é Story já concluída, Feature em Done ou issue de outro board.
+  if (external.size > 0) {
+    const linhas = [...external.entries()].map(([n, deps]) =>
+      `  #${n} ← ${deps.map(d => `#${d}`).join(', ')}`);
+    p.note(
+      linhas.join('\n'),
+      'Dependências fora do conjunto (concluídas, de Feature em Done ou de outro board)'
+    );
+  }
+
+  if (semStories.length > 0) {
+    p.log.info(`Sem Stories (ainda não decompostas): ${semStories.map(f => `#${f.number}`).join(', ')}.`);
+  }
+  p.outro(`${chalk.green('✓')} ${sorted.length} de ${enriched.length} story(ies) ordenada(s).`);
+}
+
+export async function order({ feature: featureArg } = {}) {
+  const semArgumento = featureArg === undefined || featureArg === null
+    || String(featureArg).trim() === '';
   const featureNumber = parseInt(String(featureArg).replace('#', ''), 10);
-  if (!Number.isInteger(featureNumber) || featureNumber <= 0) {
+  if (!semArgumento && (!Number.isInteger(featureNumber) || featureNumber <= 0)) {
     p.log.error(`Feature inválida: "${featureArg}". Use o número da issue, ex.: 12 ou #12.`);
     process.exitCode = 1;
     return;
@@ -43,6 +195,11 @@ export async function order({ feature: featureArg }) {
     return;
   }
 
+  if (semArgumento) {
+    p.intro(chalk.bold('spec-wave order — todas as Features com trabalho'));
+    return await orderBoard({ token, owner, repo });
+  }
+
   p.intro(chalk.bold(`spec-wave order #${featureNumber}`));
 
   // 1. Lê a Feature e valida o tipo.
@@ -116,7 +273,19 @@ export async function order({ feature: featureArg }) {
 
   // 5. Ordenação topológica (nunca lança; ciclo vem em `cycle`).
   const byNumber = new Map(enriched.map(s => [s.number, s]));
-  const { order: sorted, cycle } = orderStories(enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+  const { order: sorted, cycle, external } = orderStories(
+    enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+
+  // Uma leitura por issue externa DISTINTA — o estado dela é o que diz se o
+  // bloqueio ainda vale.
+  const foraDoConjunto = [...new Set([...external.values()].flat())];
+  const externasInfo = new Map();
+  await Promise.all(foraDoConjunto.map(async (n) => {
+    const issue = await getIssue(token, owner, repo, n).catch(() => null);
+    externasInfo.set(n, issue
+      ? { title: issue.title, state: issue.state, aberta: issue.state === 'open' }
+      : { title: '(não foi possível ler)', state: null, aberta: true });
+  }));
 
   if (cycle.length > 0) {
     p.log.warn(
@@ -136,6 +305,18 @@ export async function order({ feature: featureArg }) {
   };
   p.note(sorted.map(line).join('\n'), `Ordem de execução das Stories da Feature #${featureNumber}`);
 
+  if (external.size > 0) {
+    const linhas = [...external.entries()].map(([n, deps]) => {
+      const detalhe = deps.map(d => {
+        const info = externasInfo.get(d);
+        const marca = info?.aberta ? chalk.yellow('aberta') : chalk.green('fechada');
+        return `#${d} (${marca}) ${info?.title || ''}`.trim();
+      }).join('\n      ');
+      return `  #${n} ${byNumber.get(n)?.title || ''}\n    ← ${detalhe}`;
+    });
+    p.note(linhas.join('\n'), 'Bloqueadas por fora desta Feature');
+  }
+
   // 6. Aviso final: dependente já em Desenvolvimento+ com dependência não-Done.
   const devIdx = STAGE_ORDER.indexOf(STAGE_DEVELOPMENT);
   const outOfOrder = [];
@@ -144,7 +325,19 @@ export async function order({ feature: featureArg }) {
     const idx = stage ? STAGE_ORDER.indexOf(stage) : -1;
     if (idx === -1 || idx < devIdx) continue; // ainda não chegou em Desenvolvimento
     for (const d of s.dependsOn) {
-      if (!byNumber.has(d)) continue; // dependência externa ao conjunto — sem Etapa conhecida
+      if (!byNumber.has(d)) {
+        // Externa: não tem Etapa neste conjunto, mas tem ESTADO — e uma issue
+        // aberta bloqueando quem já está em Desenvolvimento é a mesma falha que
+        // o aviso abaixo denuncia, só que atravessando a fronteira.
+        const info = externasInfo.get(d);
+        if (info?.aberta) {
+          outOfOrder.push(
+            `#${s.number} já está em "${stage}", mas depende de #${d}, de outra Feature, ` +
+            'que continua ABERTA.'
+          );
+        }
+        continue;
+      }
       const depStage = stageOf.get(d);
       if (depStage !== STAGE_DONE) {
         outOfOrder.push(

package/src/commands/validate.mjs

@@ -8,7 +8,7 @@ import {
   REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, REQUIRED_BUG_SECTIONS, labelNames,
 } from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
-import { bugDocPaths, findMissingSections } from '../lib/bug-doc.mjs';
+import { bugDocPaths, describeMissingSections } from '../lib/bug-doc.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 
@@ -47,8 +47,8 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
     );
   } else {
     const content = readFileSync(fileAbs, 'utf-8');
-    for (const section of findMissingSections(content, REQUIRED_BUG_SECTIONS)) {
-      errors.push(`❌ Seção obrigatória ausente no bug.md: **${section}**`);
+    for (const faltante of describeMissingSections(content, REQUIRED_BUG_SECTIONS)) {
+      errors.push(renderMissingSection('bug.md', faltante));
     }
     for (const problem of findIncompleteDocSigns(content)) {
       errors.push(`❌ \`bug.md\` parece incompleto: ${problem}`);
@@ -79,6 +79,22 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
   console.log('bug.md validado.');
 }
 
+/**
+ * Linha de erro de seção ausente (função PURA).
+ *
+ * Dizer só o que falta obriga o humano a comparar título a título; dizer o que
+ * EXISTE no lugar resolve em segundos o caso real (um "# Rollout e
+ * Monitoramento" onde se esperava "# Rollback e Monitoramento", com o conteúdo
+ * certo embaixo).
+ */
+export function renderMissingSection(doc, { section, found }) {
+  const base = `❌ Seção obrigatória ausente no ${doc}: **${section}**`;
+  return found
+    ? `${base} — encontrei \`# ${found}\`, esperava \`# ${section}\`. ` +
+      'Se o conteúdo é o certo, basta renomear o título.'
+    : base;
+}
+
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
@@ -133,8 +149,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
   } else {
     const planContent = readFileSync(planPath, 'utf-8');
-    for (const section of findMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
-      errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
+    for (const faltante of describeMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
+      errors.push(renderMissingSection('plan.md', faltante));
     }
     for (const problem of findIncompleteDocSigns(planContent)) {
       errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
@@ -147,8 +163,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
   } else {
     const specContent = readFileSync(specPath, 'utf-8');
-    for (const section of findMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
-      errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
+    for (const faltante of describeMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
+      errors.push(renderMissingSection('spec.md', faltante));
     }
     // Seções presentes não garantem documento completo: um corte dentro da
     // última seção passa na checagem acima (foi o caso da EP2-F13).
@@ -165,18 +181,23 @@ export async function validate({ issueNumber }) {
       token, owner, repo, parseInt(issueNumber, 10),
       `⚠️ **Validação falhou — Feature não está pronta.**\n\n` +
       errors.join('\n') +
-      `\n\nCorreija os problemas e adicione novamente a label \`spec-wave:ready\`.`
+      `\n\nCorrija os problemas e adicione novamente a label \`spec-wave:ready\`.` +
+      `\n\nSe os documentos precisam mesmo ser REGERADOS (e não só corrigidos), aplique ` +
+      `você a label \`spec-wave:spec\` — ela **sobrescreve** o \`spec.md\`, inclusive o que ` +
+      'foi revisado à mão.'
     );
-    // Quando as ÚNICAS falhas são os portões humanos (crítica grave / revisão
-    // exigida), os documentos existem e estão estruturalmente válidos — só
-    // precisam de correção manual. Nesse caso NÃO devolvemos a feature para a
-    // etapa de spec (spec-wave:spec).
-    const humanGates = (critiqueFailed ? 1 : 0) + (needsHuman ? 1 : 0);
-    const onlyHumanGates = humanGates > 0 && errors.length === humanGates;
-    if (!onlyHumanGates) {
-      // Send back to spec stage
-      await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
-    }
+    // A reprova NÃO aplica mais `spec-wave:spec` sozinha.
+    //
+    // `spec-wave:spec` é label de GATILHO: aplicá-la manda o generate-spec
+    // sobrescrever o spec.md. Uma reprova por título trocado ("# Rollout" onde
+    // se esperava "# Rollback", com o conteúdo certo embaixo) apagaria uma spec
+    // revisada à mão por causa de uma palavra. Isso não aconteceu até hoje por
+    // um acidente: o GitHub não dispara `labeled` para eventos do GITHUB_TOKEN,
+    // então a label ficava inerte. Quem trocasse por um PAT — o que a própria
+    // documentação sugere para alcançar Projects de organização — perderia o
+    // documento sem nunca ter pedido isso.
+    //
+    // Regenerar é decisão humana, e o comentário acima diz como e o que custa.
     console.error('Validação falhou:', errors.join(', '));
     process.exit(1);
   }

package/src/config.mjs

@@ -372,6 +372,12 @@ export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
 export const LABEL_DECOMPOSE_READY = 'spec-wave:decompose-ready';
 export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
+// Selo de que spec+plan passaram pelo `validate`. É o que distingue uma Feature
+// pronta de uma que só foi movida à mão para ✅ Ready.
+export const LABEL_PLAN_APPROVED = 'spec-wave:plan-approved';
+// Gatilhos que REGERAM documento: presentes na issue, indicam etapa pendente.
+export const LABEL_SPEC = 'spec-wave:spec';
+export const LABEL_PLAN = 'spec-wave:plan';
 // Achado GRAVE que o Tech Leader aceitou como risco conhecido. Fica na issue
 // depois que a crítica passa: sem ela, o risco aceito some da vista assim que a
 // rodada seguinte roda limpa, e ninguém mais sabe que houve uma decisão.
@@ -382,11 +388,11 @@ export const LABEL_RISK_ACCEPTED = 'spec-wave:risk-accepted';
 export const LABEL_CRITIQUE = 'spec-wave:critique';
 
 export const TRIGGER_LABELS = [
-  { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
-  { name: 'spec-wave:plan',          color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
+  { name: LABEL_SPEC,                color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
+  { name: LABEL_PLAN,                color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
   { name: LABEL_CRITIQUE,            color: 'BFD4F2', description: 'Re-criticar o plan.md COMO ESTÁ, sem regerar' },
   { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
-  { name: 'spec-wave:plan-approved', color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
+  { name: LABEL_PLAN_APPROVED,       color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
   { name: LABEL_DECOMPOSE_APPLY,     color: 'BFD4F2', description: 'Aplicar o decomposition.md revisado: criar Stories e Tasks' },
   { name: LABEL_DEV_AGENT,           color: '5319E7', description: 'Enfileira a issue para o dev-agent autônomo' },

package/src/lib/board.mjs

@@ -2,7 +2,7 @@
 // Extraídos de code-review.mjs/qa.mjs para uso também pelos comandos de CLI
 // (task/story/order). Ver a distinção Etapa × Status em config.mjs.
 import { addProjectItem, setItemSingleSelect, getSingleSelectField, getItemSingleSelectValue } from '../api/github-graphql.mjs';
-import { CONFIG_FILE, STAGE_ORDER, STATUS_OPTIONS, WORK_ITEM_TYPES } from '../config.mjs';
+import { CONFIG_FILE, STAGE_ORDER, STATUS_OPTIONS, WORK_ITEM_TYPES, STAGE_DONE } from '../config.mjs';
 import { loadConfig } from './project-root.mjs';
 
 /**
@@ -116,6 +116,39 @@ export function resolveStageName(input) {
   return { stage: null, error: `Etapa "${input}" não existe. Use uma destas: ${list()}.` };
 }
 
+/**
+ * Índice do board por número de issue (função PURA).
+ *
+ * @param {Array<{number:number}>} items saída de listProjectItems
+ * @returns {Map<number, object>}
+ */
+export function indexBoardItems(items) {
+  return new Map((items || []).filter(i => i?.number).map(i => [i.number, i]));
+}
+
+/**
+ * As Features que ainda têm trabalho (função PURA).
+ *
+ * "Ainda tem trabalho" = issue aberta e Etapa diferente de 🎉 Done. É este o
+ * conjunto do `order` sem argumento: o mapa de quem depende de quem quando o
+ * trabalho de uma onda inteira está espalhado por várias Features.
+ *
+ * O tipo sai do campo "Work Item Type", com FALLBACK no prefixo do título: o
+ * campo ficou vazio em todo item criado pelo apply até a v0.21.0, e um board com
+ * esse buraco não pode virar um mapa vazio em silêncio.
+ *
+ * @param {Array<object>} items saída de listProjectItems
+ * @returns {Array<object>} Features, em ordem crescente de número
+ */
+export function selectOpenFeatures(items) {
+  return (items || [])
+    .filter(i => i?.number
+      && String(i.state || '').toUpperCase() !== 'CLOSED'
+      && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
+      && i.fields?.Etapa !== STAGE_DONE)
+    .sort((a, b) => a.number - b.number);
+}
+
 /**
  * Preenche o "Work Item Type" do item quando ele está VAZIO (best-effort).
  *

package/src/lib/bug-doc.mjs

@@ -49,3 +49,74 @@ export function findMissingSections(content, sections) {
   const text = String(content || '');
   return (sections || []).filter(section => !text.includes(`# ${section}`));
 }
+
+/**
+ * Títulos presentes no documento (função PURA).
+ */
+export function listHeadings(content) {
+  return [...String(content || '').matchAll(/^#{1,6}[ \t]+(.+?)[ \t]*$/gm)].map(m => m[1].trim());
+}
+
+// Comparação tolerante: sem acento, sem pontuação, caixa única.
+function normalizeHeading(value) {
+  return String(value ?? '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^\p{Letter}\p{Number}]+/gu, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function bigrams(value) {
+  const s = normalizeHeading(value).replace(/ /g, '');
+  const out = new Set();
+  for (let i = 0; i < s.length - 1; i++) out.add(s.slice(i, i + 2));
+  return out;
+}
+
+/**
+ * Semelhança entre dois títulos, 0..1 (função PURA — coeficiente de Dice).
+ */
+export function headingSimilarity(a, b) {
+  const A = bigrams(a);
+  const B = bigrams(b);
+  if (A.size === 0 || B.size === 0) return normalizeHeading(a) === normalizeHeading(b) ? 1 : 0;
+  let comuns = 0;
+  for (const g of A) if (B.has(g)) comuns += 1;
+  return (2 * comuns) / (A.size + B.size);
+}
+
+// Abaixo disto são dois títulos diferentes, não um errado. "Rollout e
+// Monitoramento" × "Rollback e Monitoramento" fica bem acima; "Riscos" ×
+// "Rollback e Monitoramento", bem abaixo.
+const SIMILARIDADE_MINIMA = 0.6;
+
+/**
+ * O que falta E o que existe no lugar (função PURA).
+ *
+ * `findMissingSections` só sabe dizer o que não achou, e foi isso que fez uma
+ * Feature ser reprovada por ter escrito "# Rollout e Monitoramento" no lugar de
+ * "# Rollback e Monitoramento" — com todo o conteúdo certo embaixo. A mensagem
+ * dizia "seção ausente" e o humano tinha que caçar a diferença de uma palavra.
+ *
+ * Só sugere um título que NÃO satisfaz nenhuma seção obrigatória: senão o
+ * "Riscos" legítimo do documento vira sugestão para o "Rollback" que falta.
+ *
+ * @returns {Array<{section: string, found: string|null}>}
+ */
+export function describeMissingSections(content, sections) {
+  const faltando = findMissingSections(content, sections);
+  if (faltando.length === 0) return [];
+  const presentes = (sections || []).filter(s => !faltando.includes(s)).map(normalizeHeading);
+  const candidatos = listHeadings(content)
+    .filter(h => !presentes.includes(normalizeHeading(h)));
+  return faltando.map(section => {
+    let melhor = null;
+    let score = SIMILARIDADE_MINIMA;
+    for (const h of candidatos) {
+      const s = headingSimilarity(h, section);
+      if (s >= score) { score = s; melhor = h; }
+    }
+    return { section, found: melhor };
+  });
+}

package/src/lib/claude.mjs

@@ -193,6 +193,21 @@ export function isTransientProviderError(err) {
     .test(err.message || '');
 }
 
+/**
+ * O teto de turnos merece UMA repetição? (função PURA)
+ *
+ * Só quando o erro se classificou como exploração (ver MaxTurnsError): aí a
+ * falha é variância entre execuções, e a repetição costuma custar uma fração do
+ * run que falhou. Loop degenerado continua sem retry — repetir o determinístico
+ * foi o que custou 55 minutos de Action.
+ *
+ * UMA, e não `attempts`: o ganho observado está na segunda tentativa; da
+ * terceira em diante o padrão vira "gastar caro para confirmar o óbvio".
+ */
+export function shouldRetryMaxTurns(err) {
+  return Boolean(err?.maxTurns && err.exploration);
+}
+
 export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs = RETRY_BASE_MS } = {}) {
   let lastErr;
   for (let attempt = 1; attempt <= attempts; attempt++) {
@@ -200,11 +215,12 @@ export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs =
       return await fn();
     } catch (err) {
       lastErr = err;
-      if (attempt === attempts || !isTransientProviderError(err)) break;
+      const repeteTeto = attempt === 1 && shouldRetryMaxTurns(err);
+      if (attempt === attempts || (!isTransientProviderError(err) && !repeteTeto)) break;
       const delayMs = baseMs * 2 ** (attempt - 1); // 2s, 4s, 8s…
       console.warn(
-        `${label}: falha transitória na tentativa ${attempt}/${attempts} (${err.message}) — ` +
-        `repetindo em ${delayMs / 1000}s.`
+        `${label}: ${repeteTeto ? 'teto de turnos gasto explorando' : 'falha transitória'} na ` +
+        `tentativa ${attempt}/${attempts} (${err.message}) — repetindo em ${delayMs / 1000}s.`
       );
       await sleep(delayMs);
     }
@@ -530,9 +546,9 @@ async function generateViaEngine(
 
   const text = stripReasoning(result.outputText || '');
   if (!text) {
-    // Teto de turnos tem causa e remédio próprios, e NÃO é transitório: o
-    // modelo gastou todos os turnos em tool calls sem nunca escrever o
-    // documento, e repetir reproduz isso. Ver MaxTurnsError.
+    // Teto de turnos tem causa e remédio próprios. Só é repetível quando as
+    // tool calls foram de EXPLORAÇÃO (variância); loop degenerado não é.
+    // Quem classifica é o próprio erro. Ver MaxTurnsError.
     if (result.resultSubtype === 'error_max_turns') {
       throw new MaxTurnsError({
         provider: ai.provider,
@@ -540,6 +556,7 @@ async function generateViaEngine(
         turns: result.numTurns,
         action: action || null,
         toolCalls: result.toolCalls || [],
+        toolSignatures: result.toolSignatures || [],
       });
     }
     const err = new Error(