@spec-wave/cli 0.18.0 → 0.19.0

package/src/lib/critique.mjs

@@ -42,11 +42,15 @@ const MAX_FINDING_CHARS = 800;
 export const CRITIQUE_TOOL_NAME = 'registrar_findings';
 
 // Rótulo do artefato auditado, por contexto — usado no cabeçalho do comentário.
-const KIND_LABEL = { plan: 'plan.md', stories: 'decomposition.md', bug: 'bug.md' };
+const KIND_LABEL = {
+  plan: 'plan.md', stories: 'decomposition.md', bug: 'bug.md', spec: 'spec.md',
+};
 
 // Prompt por tipo de auditoria. 'plan' audita o plan.md contra a spec;
 // 'stories' audita a decomposição proposta contra spec + plan.
-const KIND_PROMPT = { plan: 'plan/critique', stories: 'decompose/critique', bug: 'bug/critique' };
+const KIND_PROMPT = {
+  plan: 'plan/critique', stories: 'decompose/critique', bug: 'bug/critique', spec: 'spec/critique',
+};
 
 // A decomposição virou arquivo revisável (decomposition.md): um finding só é
 // acionável se disser ONDE está o problema. Os títulos "## Story N" e
@@ -83,6 +87,15 @@ Classifique cada finding no campo "severity", usando EXATAMENTE um destes dois v
 - "grave": contradiz um requisito ou regra explícita — causaria implementação errada;
 - "menor": inconsistência, omissão ou ambiguidade que merece atenção mas não inverte requisito.
 
+Todo finding "grave" DEVE trazer, no campo "quote", um trecho LITERAL do documento auditado
+(copiado byte a byte, 10 a 200 caracteres) onde o problema está. Grave sem citação verificável é
+rebaixado para "menor" automaticamente — não porque o achado seja falso, mas porque bloquear o
+fluxo exige poder apontar onde.
+
+Antes de marcar "grave", releia o que você escreveu: se o próprio texto conclui que não há
+contradição ("consistente com", "sem contradição real", "está correto"), então o finding é "menor"
+ou não é finding.
+
 Escreva os findings em português (pt-BR), em uma frase objetiva cada.${anchor}
 
 Registre o resultado chamando a ferramenta \`${CRITIQUE_TOOL_NAME}\`. Nunca responda em texto livre.
@@ -106,6 +119,12 @@ function critiqueJsonSchema(kind) {
       type: 'string',
       description: 'Descrição do finding em português (pt-BR), em uma única frase objetiva.',
     },
+    quote: {
+      type: 'string',
+      description:
+        'Trecho LITERAL do documento auditado (10–200 caracteres) onde o problema está. ' +
+        'Obrigatório em findings "grave" — sem ele o finding é rebaixado para "menor".',
+    },
   };
   const required = ['severity', 'text'];
   if (kind === 'stories') {
@@ -225,7 +244,8 @@ export function validateCritiquePayload(payload) {
         'O campo com a descrição do finding DEVE se chamar "text".'
       );
     }
-    const extra = itemKeys.filter(k => k !== 'severity' && k !== 'text' && k !== 'anchor');
+    const extra = itemKeys.filter(
+      k => k !== 'severity' && k !== 'text' && k !== 'anchor' && k !== 'quote');
     if (extra.length > 0) {
       throw new CritiqueSchemaError(`${at} tem campo(s) não reconhecido(s): ${extra.join(', ')}.`);
     }
@@ -244,12 +264,122 @@ export function validateCritiquePayload(payload) {
       );
     }
     const anchor = normalizeAnchor(item.anchor);
-    return { severity, ...(anchor ? { anchor } : {}), text: item.text.trim() };
+    const quote = typeof item.quote === 'string' ? item.quote.trim() : '';
+    return {
+      severity,
+      ...(anchor ? { anchor } : {}),
+      ...(quote ? { quote } : {}),
+      text: item.text.trim(),
+    };
   });
 
   return { grave: findings.some(f => f.severity === 'grave'), findings };
 }
 
+// ---------------------------------------------------------------------------
+// Coerência: um "grave" tem de se sustentar sozinho
+// ---------------------------------------------------------------------------
+//
+// Na segunda rodada do decompose da EP1-F8, o único achado grave terminava com
+// "consistente na Story, sem contradição real" — o modelo classificou como grave
+// algo que ele mesmo concluiu não existir. Grave faz o Action sair com 1 e
+// aplicar `spec-wave:critique-failed`: aquele parágrafo custou uma rodada
+// inteira do fluxo.
+//
+// A checagem aqui é DETERMINÍSTICA e barata (sem IA):
+//   1. o texto do finding se auto-refuta?
+//   2. a citação existe mesmo no documento auditado?
+// Nenhuma das duas julga o MÉRITO do achado — as duas julgam se ele se sustenta
+// como bloqueio. Quando não se sustenta, o finding é REBAIXADO para menor com o
+// motivo à vista, nunca descartado: apagar achado em silêncio foi o vício da
+// versão antiga da crítica, e o remédio não pode reintroduzi-lo.
+
+// Frases em que o modelo desmente o próprio finding. Deliberadamente curtas e
+// literais: heurística ampla aqui rebaixaria achado legítimo, e o custo de um
+// falso rebaixamento (grave que deixa de bloquear) é maior que o de um falso
+// grave (uma rodada perdida, com o TL podendo decidir).
+const SELF_REFUTING = [
+  'sem contradição real',
+  'sem contradicao real',
+  'não há contradição',
+  'nao ha contradicao',
+  'não existe contradição',
+  'nao existe contradicao',
+  'sem inconsistência real',
+  'sem inconsistencia real',
+  'não há inconsistência',
+  'nao ha inconsistencia',
+  'está correto',
+  'esta correto',
+  'está coerente',
+  'esta coerente',
+  'consistente na story',
+  'nenhum problema real',
+];
+
+function normalizeForSearch(text) {
+  return String(text ?? '')
+    .normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** O texto do finding conclui que o problema não existe? (função PURA) */
+export function isSelfRefuting(text) {
+  const alvo = normalizeForSearch(text);
+  return SELF_REFUTING.some(frase => alvo.includes(normalizeForSearch(frase)));
+}
+
+/** A citação aparece literalmente no documento auditado? (função PURA) */
+export function quoteIsVerifiable(quote, documents = []) {
+  const trecho = normalizeForSearch(quote);
+  if (trecho.length < 10) return false; // curto demais para localizar
+  return documents.some(doc => normalizeForSearch(doc).includes(trecho));
+}
+
+/**
+ * Rebaixa os "grave" que não se sustentam como bloqueio (função PURA).
+ *
+ * Rebaixado ≠ descartado: o finding continua no comentário, com o motivo do
+ * rebaixamento, e só deixa de fazer o Action falhar. Quem discordar do
+ * rebaixamento tem o texto na frente para decidir.
+ *
+ * @param {Array} findings findings validados
+ * @param {string[]} documents conteúdos auditados (spec, plan, decomposition…)
+ * @returns {Array} findings com `downgraded` e `downgradeReason` quando aplicável
+ */
+export function downgradeUnsupportedFindings(findings = [], documents = []) {
+  return findings.map((f) => {
+    if (f.severity !== 'grave') return f;
+    if (isSelfRefuting(f.text)) {
+      return {
+        ...f,
+        severity: 'menor',
+        downgraded: 'grave',
+        downgradeReason: 'o próprio texto conclui que não há contradição',
+      };
+    }
+    if (!f.quote) {
+      return {
+        ...f,
+        severity: 'menor',
+        downgraded: 'grave',
+        downgradeReason: 'veio sem citação do trecho (o contrato exige uma para bloquear)',
+      };
+    }
+    if (!quoteIsVerifiable(f.quote, documents)) {
+      return {
+        ...f,
+        severity: 'menor',
+        downgraded: 'grave',
+        downgradeReason: 'a citação não foi encontrada nos documentos auditados',
+      };
+    }
+    return f;
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Marcador de tentativa e contador
 // ---------------------------------------------------------------------------
@@ -623,15 +753,29 @@ export function sanitizeFindingText(text) {
  */
 export function renderCritiqueMarkdown({
   kind = 'plan', findings = [], attempt = 1,
-  maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS, model = '',
+  maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS, model = '', standalone = false,
 } = {}) {
   const graves = findings.filter(f => f.severity === 'grave');
-  const menores = findings.filter(f => f.severity === 'menor');
-  const parts = [
-    critiqueMarker({ kind, attempt, verdict: graves.length > 0 ? 'grave' : 'limpa' }),
-    `🔎 **Crítica adversarial (spec-wave)** — ${KIND_LABEL[kind] || KIND_LABEL.plan} · ` +
-    `tentativa ${attempt}/${maxAttempts}${model ? ` · modelo \`${model}\`` : ''}`,
-  ];
+  // Rebaixados saem da lista de menores e ganham seção própria: enterrá-los
+  // entre os menores esconderia que a crítica MUDOU a classificação do modelo,
+  // que é justamente o que o humano precisa poder contestar.
+  const rebaixados = findings.filter(f => f.downgraded);
+  const menores = findings.filter(f => f.severity === 'menor' && !f.downgraded);
+  // `standalone`: crítica AVULSA (spec-wave critique --file), fora do ciclo de
+  // tentativas. Sem marcador de propósito — é o marcador que alimenta o
+  // contador, e uma consulta sob demanda não pode consumir tentativa nem
+  // disparar o portão humano.
+  const parts = standalone
+    ? [
+      `🔎 **Crítica avulsa (spec-wave)** — ${KIND_LABEL[kind] || KIND_LABEL.plan}` +
+      `${model ? ` · modelo \`${model}\`` : ''}`,
+      '_Rodada sob demanda, sobre o documento como está: não conta tentativa e não aplica labels._',
+    ]
+    : [
+      critiqueMarker({ kind, attempt, verdict: graves.length > 0 ? 'grave' : 'limpa' }),
+      `🔎 **Crítica adversarial (spec-wave)** — ${KIND_LABEL[kind] || KIND_LABEL.plan} · ` +
+      `tentativa ${attempt}/${maxAttempts}${model ? ` · modelo \`${model}\`` : ''}`,
+    ];
 
   if (findings.length === 0) {
     parts.push('✅ Nenhuma contradição encontrada.');
@@ -643,6 +787,17 @@ export function renderCritiqueMarkdown({
     .join('\n');
   if (graves.length > 0) parts.push(`### ❌ Graves\n\n${bullets(graves)}`);
   if (menores.length > 0) parts.push(`### ⚠️ Menores\n\n${bullets(menores)}`);
+  if (rebaixados.length > 0) {
+    parts.push(
+      '### ↘️ Rebaixados (vieram como graves, não bloqueiam)\n\n' +
+      rebaixados
+        .map(f => `- ${f.anchor ? `**${f.anchor}** — ` : ''}${sanitizeFindingText(f.text)}\n` +
+          `  - _Rebaixado: ${sanitizeFindingText(f.downgradeReason || 'não se sustenta como bloqueio')}._`)
+        .join('\n') +
+      '\n\n_Continuam valendo como observação. Se algum for mesmo grave, corrija o documento ' +
+      'ou peça nova crítica citando o trecho._'
+    );
+  }
   parts.push((KIND_TRAILER[kind] || KIND_TRAILER.plan)(graves.length > 0));
   // Findings estruturados, com a MESMA digital que o portão usa. É o que
   // permite decidir item a item numa UI: parsear os bullets de volta seria
@@ -657,6 +812,7 @@ export function renderCritiqueMarkdown({
         severity: f.severity,
         anchor: f.anchor || null,
         text: sanitizeFindingText(f.text),
+        ...(f.downgraded ? { downgradedFrom: f.downgraded, downgradeReason: f.downgradeReason } : {}),
       })),
     }, null, 2),
     '```',
@@ -693,7 +849,7 @@ export function renderCritiqueMarkdown({
 export async function runCritique({
   kind, spec, plan, techContextYaml, decomposition, bugDoc, bugReport,
   attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
-  model, labels = [], usage, cwd, decisions = null,
+  model, labels = [], usage, cwd, decisions = null, standalone = false,
 } = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
@@ -738,12 +894,28 @@ export async function runCritique({
     withReport: true,
   });
 
-  const { grave, findings } = report.value;
+  // Coerência ANTES de tudo o que depende da severidade: um grave que não se
+  // sustenta não deve entrar no contador de tentativas nem bloquear o Action.
+  const findings = downgradeUnsupportedFindings(
+    report.value.findings,
+    [spec, plan, decomposition, bugDoc, techContextYaml].filter(Boolean),
+  );
+  const grave = findings.some(f => f.severity === 'grave');
+  const rebaixados = findings.filter(f => f.downgraded).length;
+  if (rebaixados > 0) {
+    console.log(
+      `${rebaixados} finding(s) grave(s) rebaixado(s) para menor por não se sustentarem ` +
+      '(auto-refutação no texto ou citação não verificável) — seguem no comentário, com o motivo.'
+    );
+  }
+
   return {
     grave,
     findings,
     attempt,
     model: report.model,
-    markdown: renderCritiqueMarkdown({ kind, findings, attempt, maxAttempts, model: report.model }),
+    markdown: renderCritiqueMarkdown({
+      kind, findings, attempt, maxAttempts, model: report.model, standalone,
+    }),
   };
 }

package/src/lib/decomposition-doc.mjs

@@ -49,6 +49,11 @@ const H1_RE         = /^#[ \t]+(.*)$/;
 const MARKER_RE     = /^<!--[ \t]*spec-wave:decomposition[ \t]+(.*?)-->[ \t]*$/i;
 const USER_STORY_RE = /^\*\*User story:?\*\*:?[ \t]*(.*)$/i;
 const DEPENDS_RE    = /^\*\*Depende de:?\*\*:?[ \t]*(.*)$/i;
+// Gravado pelo `decompose-apply` DEPOIS de criar a issue. É o que liga o
+// rascunho ao que existe de fato no GitHub — sem isso o arquivo continua
+// descrevendo a proposta original para sempre, e um rescopo feito nas issues
+// deixa o documento como registro enganoso, sem que nada perceba.
+const ISSUE_RE      = /^\*\*Issue:?\*\*:?[ \t]*#?(\d+)[ \t]*$/i;
 const EMPTY_VALUE_RE = /^(—|–|-|nenhuma|nenhum|none|n\/a)$/i;
 const FENCE_RE      = /^ {0,3}(`{3,}|~{3,})(.*)$/;
 
@@ -176,6 +181,7 @@ function normalizeDependsOn(dependsOn, index) {
  */
 export function renderDecompositionDoc({
   title = '', issueNumber = null, kind = 'stories', preamble = '', stories = [], tasks = [],
+  appliedAt = null,
 } = {}) {
   if (kind !== 'stories' && kind !== 'tasks') {
     throw new Error(`decomposition.md: kind inválido "${kind}" (use "stories" ou "tasks").`);
@@ -185,6 +191,10 @@ export function renderDecompositionDoc({
   const issue = Number(issueNumber);
   if (Number.isInteger(issue) && issue > 0) attrs.push(`issue=${issue}`);
   attrs.push(`kind=${kind}`);
+  // `applied=<ISO>` marca que as issues JÁ existem. É o que separa "proposta
+  // ainda em revisão" de "registro do que foi criado" — e o que o doctor usa
+  // para conferir se o arquivo ainda descreve a árvore real.
+  if (appliedAt) attrs.push(`applied=${appliedAt}`);
 
   const head = flatten(title) ? `# Decomposição — ${flatten(title)}` : '# Decomposição';
   const blocks = [`${head}\n<!-- spec-wave:decomposition ${attrs.join(' ')} -->`];
@@ -192,8 +202,17 @@ export function renderDecompositionDoc({
   const note = renderBody(preamble);
   if (note) blocks.push(note);
 
+  // A linha `**Issue:** #N` sai como PRIMEIRO bloco depois do título, separada
+  // do corpo por linha em branco — mesma regra dos campos da Story, e é isso que
+  // impede um corpo começando com "**Issue:** #12" de ser lido como o campo.
+  const issueLine = (item) => {
+    const n = Number(item?.issue);
+    return Number.isInteger(n) && n > 0 ? `**Issue:** #${n}` : '';
+  };
   const pushItem = (heading, item) => {
     blocks.push(`${heading} — ${flatten(item?.title) || '(sem título)'}`);
+    const linha = issueLine(item);
+    if (linha) blocks.push(linha);
     const body = renderBody(item?.body);
     if (body) blocks.push(body);
   };
@@ -207,10 +226,13 @@ export function renderDecompositionDoc({
       // As DUAS linhas de campo saem SEMPRE, seguidas de linha em branco: é essa
       // linha em branco que impede um corpo começando com "**Depende de:** …" de
       // ser confundido com o campo.
-      blocks.push([
+      const campos = [
         `**User story:** ${flatten(story?.userStory) || '—'}`,
         `**Depende de:** ${deps.length ? deps.map(d => `Story ${d + 1}`).join(', ') : '—'}`,
-      ].join('\n'));
+      ];
+      const linhaIssue = issueLine(story);
+      if (linhaIssue) campos.push(linhaIssue);
+      blocks.push(campos.join('\n'));
       const body = renderBody(story?.body);
       if (body) blocks.push(body);
       (story?.tasks || []).forEach((task, j) => pushItem(`### Task ${i + 1}.${j + 1}`, task));
@@ -225,10 +247,12 @@ function parseMarker(attrs) {
   const version = /(?:^|\s)v(\d+)(?:\s|$)/.exec(text);
   const issue = /\bissue=(\d+)\b/.exec(text);
   const kind = /\bkind=(stories|tasks)\b/i.exec(text);
+  const applied = /\bapplied=(\S+)/.exec(text);
   return {
     version: version ? parseInt(version[1], 10) : DOC_VERSION,
     issueNumber: issue ? parseInt(issue[1], 10) : null,
     kind: kind ? kind[1].toLowerCase() : null,
+    appliedAt: applied ? applied[1] : null,
   };
 }
 
@@ -276,6 +300,21 @@ function parseDependsValue(raw, index, anchor) {
   return out.sort((a, b) => a - b);
 }
 
+// Tasks não têm campos de gramática além do título — só a linha `**Issue:** #N`
+// gravada pelo apply. Mesma regra dos campos da Story: vale apenas no primeiro
+// bloco não-vazio abaixo do título.
+function splitTaskSection(lines) {
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++;
+  let issue = null;
+  const m = i < lines.length ? ISSUE_RE.exec(lines[i]) : null;
+  if (m) {
+    issue = parseInt(m[1], 10);
+    i++;
+  }
+  return { issue, body: readBody(lines.slice(i)) };
+}
+
 // Os campos valem SÓ no primeiro bloco não-vazio abaixo do título. É o que deixa
 // o corpo conter uma linha "**Depende de:** #12" sem que ela vire campo.
 function splitStorySection(lines, anchor) {
@@ -283,22 +322,28 @@ function splitStorySection(lines, anchor) {
   while (i < lines.length && !lines[i].trim()) i++;
   let userStory = null;
   let depends = null;
+  let issue = null;
   while (i < lines.length && lines[i].trim()) {
     const us = USER_STORY_RE.exec(lines[i]);
     const dep = us ? null : DEPENDS_RE.exec(lines[i]);
-    if (!us && !dep) break;
+    const iss = us || dep ? null : ISSUE_RE.exec(lines[i]);
+    if (!us && !dep && !iss) break;
     if (us) {
       if (userStory !== null) throw invalid(`${anchor} tem duas linhas "**User story:**"`);
       userStory = us[1].trim();
-    } else {
+    } else if (dep) {
       if (depends !== null) throw invalid(`${anchor} tem duas linhas "**Depende de:**"`);
       depends = dep[1].trim();
+    } else {
+      if (issue !== null) throw invalid(`${anchor} tem duas linhas "**Issue:**"`);
+      issue = parseInt(iss[1], 10);
     }
     i++;
   }
   return {
     userStory: !userStory || EMPTY_VALUE_RE.test(userStory) ? '' : userStory,
     depends,
+    issue,
     body: readBody(lines.slice(i)),
   };
 }
@@ -394,6 +439,8 @@ export function parseDecompositionDoc(markdown) {
     issueNumber: marker.issueNumber,
     kind,
     title,
+    // null = a decomposição ainda não foi aplicada; ISO = quando foi.
+    appliedAt: marker.appliedAt,
     preamble: readBody(preamble),
     stories: [],
     tasks: [],
@@ -409,7 +456,8 @@ export function parseDecompositionDoc(markdown) {
     }
     doc.tasks = sections.map((s, i) => {
       const anchor = `Task ${i + 1}`;
-      return { anchor, title: requireTitle(s.title, anchor), body: readBody(s.lines) };
+      const { issue, body } = splitTaskSection(s.lines);
+      return { anchor, title: requireTitle(s.title, anchor), issue, body };
     });
     if (doc.tasks.length === 0) throw invalid('não encontrei nenhuma Task ("## Task 1 — …")');
     return doc;
@@ -418,12 +466,13 @@ export function parseDecompositionDoc(markdown) {
   for (const section of sections) {
     if (section.type === 'story') {
       const anchor = `Story ${doc.stories.length + 1}`;
-      const { userStory, depends, body } = splitStorySection(section.lines, anchor);
+      const { userStory, depends, issue, body } = splitStorySection(section.lines, anchor);
       doc.stories.push({
         anchor,
         title: requireTitle(section.title, anchor),
         userStory,
         body,
+        issue,
         dependsOn: parseDependsValue(depends, doc.stories.length, anchor),
         tasks: [],
       });
@@ -443,7 +492,10 @@ export function parseDecompositionDoc(markdown) {
     }
     const story = doc.stories[doc.stories.length - 1];
     const anchor = `Task ${doc.stories.length}.${story.tasks.length + 1}`;
-    story.tasks.push({ anchor, title: requireTitle(section.title, anchor), body: readBody(section.lines) });
+    const { issue: taskIssue, body: taskBody } = splitTaskSection(section.lines);
+    story.tasks.push({
+      anchor, title: requireTitle(section.title, anchor), issue: taskIssue, body: taskBody,
+    });
   }
 
   if (doc.stories.length === 0) throw invalid('não encontrei nenhuma Story ("## Story 1 — …")');

package/src/lib/flow-run.mjs

@@ -22,10 +22,12 @@
 //     naquele repositório. Localmente a sua identidade é preservada.
 //  2. FALHA DE PUSH. No Action, não conseguir publicar é falha do job. Local, o
 //     arquivo já está gerado e commitado — perder isso porque o remoto andou
-//     seria pior que avisar e deixar você resolver o push.
+//     seria pior que avisar e deixar você resolver o push. Antes de chegar
+//     nessa bifurcação, os dois modos repetem pull+push enquanto a rejeição for
+//     disputa com outro run — ver §publicação concorrente.
 
 import { execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { resolveRepoContext } from './project-root.mjs';
 import { CONFIG_FILE } from '../config.mjs';
@@ -71,6 +73,129 @@ export function resolveFlowContext({ cwd = process.cwd(), command = 'este comand
   return { owner, repo, root, config, mode };
 }
 
+// --- publicação concorrente -------------------------------------------------
+//
+// `pull --rebase` seguido de `push` NÃO é atômico. Entre os dois cabe o push de
+// outro run: dois `generate-spec` de issues DIFERENTES disparados juntos rodam
+// em paralelo (a `concurrency` dos workflows é por issue, e é por issue que ela
+// tem que ser — serializar o repositório inteiro mataria a vazão), terminam
+// juntos e disputam a ponta da branch. O perdedor levava non-fast-forward,
+// falhava o job e PERDIA o documento recém-gerado — com a chamada de IA já
+// paga. Repetir pull+push resolve: o rebase reaplica o commit sobre a ponta
+// nova e o segundo push passa.
+
+export const PUSH_ATTEMPTS = 5;
+const PUSH_BASE_MS = 500;
+
+// Rejeição por CORRIDA: o remoto andou, e reaplicar por cima resolve.
+const RACE_PATTERNS = /non-fast-forward|fetch first|Updates were rejected|cannot lock ref|failed to lock/i;
+
+// Recusa DELIBERADA do remoto. Compartilha a linha genérica "failed to push
+// some refs" com a corrida, então precisa ser testada ANTES: repetir aqui só
+// atrasa a mensagem que o usuário precisa ler. Mesma filosofia de
+// `isTransientProviderError` (lib/claude.mjs).
+const REFUSED_PATTERNS = /GH006|protected branch|pre-receive hook declined|permission to .* denied|403 Forbidden|Authentication failed|could not read Username|Repository not found/i;
+
+/**
+ * A saída do git indica disputa pela ponta da branch? (função PURA)
+ *
+ * @param {string} output stdout+stderr do comando que falhou
+ * @returns {boolean}
+ */
+export function isRacePushError(output) {
+  const text = String(output || '');
+  if (!text) return false;
+  if (REFUSED_PATTERNS.test(text)) return false;
+  return RACE_PATTERNS.test(text);
+}
+
+/**
+ * Espera antes da próxima tentativa (função PURA).
+ *
+ * Exponencial COM jitter: sem o jitter, dois runs que colidiram uma vez voltam
+ * a colidir no mesmo instante — o backoff determinístico os mantém em fase.
+ *
+ * @param {number} attempt tentativa que acabou de falhar (1-based)
+ * @param {object} [opts]
+ * @param {number} [opts.baseMs]
+ * @param {() => number} [opts.random] injetável para o teste
+ * @returns {number} milissegundos
+ */
+export function pushBackoffMs(attempt, { baseMs = PUSH_BASE_MS, random = Math.random } = {}) {
+  const teto = baseMs * 2 ** (attempt - 1); // 500ms, 1s, 2s, 4s…
+  return Math.round(teto * (1 + random()));  // [teto, 2*teto)
+}
+
+// Sleep BLOQUEANTE de propósito: `commitGenerated` é síncrona de ponta a ponta
+// (execSync), e um único `await` no meio obrigaria os três comandos chamadores
+// e a suíte inteira a virarem async para nada — nada mais roda nesta thread
+// enquanto o git trabalha.
+function sleepSync(ms) {
+  if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Roda um comando git capturando a saída, e a devolve anexada ao erro.
+ *
+ * Com `stdio: 'inherit'` o texto do git vai para o log mas NÃO chega ao
+ * processo: `err.message` é só "Command failed: git push", e não dá para
+ * distinguir corrida de branch protegida. Capturando, o log continua igual
+ * (reemitimos) e a classificação passa a ser possível.
+ */
+function gitCaptured(cmd) {
+  try {
+    const out = execSync(cmd, { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (out?.length) process.stdout.write(out);
+    return;
+  } catch (err) {
+    const detail = [err.stdout, err.stderr].map(b => b?.toString() || '').join('').trim();
+    if (detail) process.stderr.write(`${detail}\n`);
+    const resumo = detail.split('\n').find(l => l.trim()) || err.message;
+    const erro = new Error(`${cmd} falhou: ${resumo}`);
+    erro.gitOutput = detail;
+    throw erro;
+  }
+}
+
+// Rebase interrompido (conflito, ou pull abortado no meio) deixa o repositório
+// EM rebase. No runner descartável tanto faz; no clone do usuário, sair assim
+// é deixar um estado que ele não pediu e talvez nem perceba.
+function abortRebaseIfAny() {
+  try {
+    const dir = execSync('git rev-parse --git-path rebase-merge', { stdio: 'pipe' }).toString().trim();
+    const dirApply = execSync('git rev-parse --git-path rebase-apply', { stdio: 'pipe' }).toString().trim();
+    if (!existsSync(dir) && !existsSync(dirApply)) return;
+    execSync('git rebase --abort', { stdio: 'pipe' });
+  } catch {
+    // Melhor esforço: se nem abortar dá, o erro original é o que importa.
+  }
+}
+
+/**
+ * pull --rebase + push, repetindo enquanto a falha for disputa pela branch.
+ *
+ * @returns {{attempts: number}}
+ * @throws o erro do git quando não é corrida, ou quando as tentativas acabam
+ */
+function publishWithRetry({ attempts, baseMs }) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      gitCaptured('git pull --rebase');
+      gitCaptured('git push');
+      return { attempts: attempt };
+    } catch (err) {
+      abortRebaseIfAny();
+      if (attempt >= attempts || !isRacePushError(err.gitOutput || err.message)) throw err;
+      const espera = pushBackoffMs(attempt, { baseMs });
+      console.warn(
+        `Publicação disputada por outro run (tentativa ${attempt}/${attempts}) — ` +
+        `repetindo em ${(espera / 1000).toFixed(1)}s.`
+      );
+      sleepSync(espera);
+    }
+  }
+}
+
 /**
  * Grava um arquivo gerado e o publica: commit + pull --rebase + push.
  *
@@ -87,9 +212,11 @@ export function resolveFlowContext({ cwd = process.cwd(), command = 'este comand
  * @param {string} params.content
  * @param {string} params.message mensagem de commit
  * @param {'actions'|'local'} params.mode
+ * @param {{attempts?: number, baseMs?: number}} [params.retry] ajuste do laço de
+ *        publicação — existe para o teste não dormir o backoff real
  * @returns {{committed: boolean, pushed: boolean, warning: string|null}}
  */
-export function commitGenerated({ filePath, content, message, mode }) {
+export function commitGenerated({ filePath, content, message, mode, retry = {} }) {
   mkdirSync(path.dirname(filePath), { recursive: true });
   writeFileSync(filePath, content, 'utf-8');
 
@@ -120,8 +247,10 @@ export function commitGenerated({ filePath, content, message, mode }) {
   git(`git commit -m "${message}" -- "${filePath}"`);
 
   try {
-    git('git pull --rebase');
-    git('git push');
+    publishWithRetry({
+      attempts: retry.attempts ?? PUSH_ATTEMPTS,
+      baseMs: retry.baseMs ?? PUSH_BASE_MS,
+    });
     return { committed: true, pushed: true, warning: null };
   } catch (err) {
     if (mode === 'actions') throw err;

package/src/lib/prompt-loader.mjs

@@ -187,12 +187,19 @@ const REQUIRES_TOOLS_RE = /<!--\s*requires-tools\s*-->[\s\S]*?<!--\s*\/requires-
 /**
  * Texto de sistema para um runtime SEM ferramentas (função PURA).
  *
- * `generateDocument`/`generateStructured` fazem UMA chamada de completions: não
- * há loop de tool use, então o modelo não tem `Read`/`Glob`/`Grep` por mais que
- * o frontmatter os declare. Um prompt que afirme possuir ferramentas nesse
+ * `generateStructured` faz UMA chamada com `tool_choice` forçado: não há loop de
+ * tool use, então o modelo não tem `Read`/`Glob`/`Grep` por mais que o
+ * frontmatter os declare. Um prompt que afirme possuir ferramentas nesse
  * runtime mente para o modelo — e o resultado típico é uma seção inventada
  * "conforme verifiquei no repositório".
  *
+ * ATENÇÃO ao escolher entre esta e `systemPromptWithTools`: `generateDocument`
+ * JÁ NÃO é um runtime sem ferramentas — ele passa `['Read','Glob','Grep']` ao
+ * motor (ver `lib/claude.mjs`). Usar este recorte lá inverte o problema que ele
+ * resolve: o modelo recebe as ferramentas com a orientação de uso arrancada, e
+ * um modelo que não fecha o loop sozinho perambula até o teto de turnos sem
+ * escrever o documento. Foi o que travou um Action por 55 minutos.
+ *
  * Por isso o corpo marca a orientação dependente de ferramentas entre
  * `<!-- requires-tools -->` e `<!-- /requires-tools -->`, e este recorte a
  * remove. O mesmo arquivo serve os dois runtimes sem manter duas versões.
@@ -210,6 +217,26 @@ export function toolFreeSystemPrompt(prompt, appendInstruction = '') {
   return [stripped, (appendInstruction || '').trim()].filter(Boolean).join('\n\n');
 }
 
+/**
+ * Texto de sistema para um runtime COM ferramentas de leitura (função PURA).
+ *
+ * Par de `toolFreeSystemPrompt`: preserva o bloco `<!-- requires-tools -->`, que
+ * é onde o prompt ensina o modelo a explorar o repositório E a parar de
+ * explorar. É o que `generateDocument` precisa, porque ali o modelo de fato
+ * recebe `Read`/`Glob`/`Grep`.
+ *
+ * O `appendInstruction` vem por ÚLTIMO pela mesma razão que na irmã: um prompt
+ * sobrescrito pelo projeto não pode anular uma regra que a CLI garante.
+ *
+ * @param {ReturnType<typeof normalizePrompt>} prompt
+ * @param {string} [appendInstruction]
+ * @returns {string}
+ */
+export function systemPromptWithTools(prompt, appendInstruction = '') {
+  const body = prompt.prompt.replace(/\n{3,}/g, '\n\n').trim();
+  return [body, (appendInstruction || '').trim()].filter(Boolean).join('\n\n');
+}
+
 /**
  * Converte um prompt em `AgentRunOptions` do `@spec-wave/agent` (função PURA).
  *