@spec-wave/cli 0.15.0 → 0.16.1

package/src/lib/claude.mjs

@@ -5,6 +5,8 @@ import {
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
 } from '../config.mjs';
 import { lintLanguage } from './output-lint.mjs';
+import { runAgent } from '../agent/index.mjs';
+import { TruncatedOutputError, isTruncationReason } from '../agent/errors.mjs';
 import { computeCost } from './usage-report.mjs';
 import { findConfigPath } from './project-root.mjs';
 
@@ -180,33 +182,11 @@ export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs =
   throw lastErr;
 }
 
-// Truncamento: os dois provedores dizem explicitamente que cortaram a saída no
-// teto de tokens — OpenRouter (formato OpenAI) em `choices[0].finish_reason`,
-// Anthropic em `message.stop_reason`. Ignorar esse campo é o que produzia um
-// documento cortado no meio de uma frase, commitado como se estivesse completo.
-const TRUNCATION_REASONS = new Set(['length', 'max_tokens']);
-
-/** Motivo de parada indica saída cortada no teto de tokens? (função PURA) */
-export function isTruncationReason(reason) {
-  return TRUNCATION_REASONS.has(reason);
-}
-
-// Repetir a MESMA requisição depois de truncar dá o mesmo corte — só sobe o
-// custo. Por isso NÃO é marcado como transitório: o erro sobe, o Action falha
-// visível, destrava a label e comenta na issue o que ajustar.
-export class TruncatedOutputError extends Error {
-  constructor({ provider, model, maxTokens, reason, chars }) {
-    super(
-      `Saída truncada pelo teto de tokens (${provider} · ${model} · max_tokens=${maxTokens} · ` +
-      `motivo=${reason}). Foram gerados ~${chars} caracteres antes do corte. ` +
-      'Aumente `ai.maxTokens` (ou `ai.maxTokensByAction`) no .spec-wave.json, ou reduza o ' +
-      'tamanho da issue de origem. O documento NÃO foi gravado — um documento cortado ' +
-      'passaria na validação de seções e valeria menos que nenhum.'
-    );
-    this.name = 'TruncatedOutputError';
-    this.truncated = true;
-  }
-}
+// `TruncatedOutputError` e `isTruncationReason` saíram daqui para
+// `agent/errors.mjs` quando os backends portados passaram a precisar deles.
+// Re-exportados para não quebrar os 5 consumidores e os testes que importam
+// deste módulo.
+export { TruncatedOutputError, isTruncationReason };
 
 // Os parâmetros de sampling foram REMOVIDOS a partir do Claude Opus 4.7 (vale
 // para 4.8 e 5, Sonnet 5, Fable 5 e Mythos 5): enviar temperature/top_p/top_k
@@ -234,67 +214,11 @@ export function supportsStrictSchema(model) {
   return MODELS_WITH_STRICT_SCHEMA.test(model || '');
 }
 
-/**
- * Corpo EXATO de `client.messages.create` (função PURA — testável sem HTTP).
- *
- * Com `schema`, força a ferramenta via tool_choice: o modelo não tem como
- * responder em texto livre, que é o que produzia JSON sujo na crítica.
- * `disable_parallel_tool_use` garante no máximo um bloco tool_use.
- */
-export function buildAnthropicRequest({
-  ai, systemPrompt, userContent, temperature, maxTokens, schema, strict,
-}) {
-  return {
-    model: ai.model,
-    max_tokens: maxTokens,
-    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5):
-    // enviá-la devolve 400.
-    ...(temperature === undefined ? {} : { temperature }),
-    messages: [{ role: 'user', content: userContent }],
-    system: systemPrompt,
-    ...(schema ? {
-      tools: [{
-        name: schema.name,
-        description: schema.description,
-        input_schema: schema.jsonSchema,
-        ...(strict ? { strict: true } : {}),
-      }],
-      tool_choice: { type: 'tool', name: schema.name, disable_parallel_tool_use: true },
-    } : {}),
-  };
-}
+// `buildAnthropicRequest` e `buildOpenRouterBody` foram REMOVIDOS: quem monta
+// a requisição agora é o motor (`src/agent/`). No backend openrouter isso é
+// `buildChatCompletionBody`; no anthropic, o subprocesso do Claude Code monta
+// a própria — este processo não fala com a API da Anthropic.
 
-/**
- * Corpo EXATO do POST da OpenRouter (função PURA — testável sem HTTP).
- *
- * `provider.require_parameters` é obrigatório junto do response_format: sem ele o
- * roteador escolhe endpoints que IGNORAM o schema e devolvem prosa, e o erro só
- * apareceria no JSON.parse, três retries depois. Com ele, a recusa é imediata e
- * a mensagem diz o que trocar.
- */
-export function buildOpenRouterBody({
-  ai, systemPrompt, userContent, temperature, maxTokens, schema,
-}) {
-  return {
-    model: ai.model,
-    max_tokens: maxTokens,
-    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5).
-    ...(temperature === undefined ? {} : { temperature }),
-    messages: [
-      { role: 'system', content: systemPrompt },
-      { role: 'user', content: userContent },
-    ],
-    // Pede o bloco `usage` completo na resposta (inclui `cost` em USD).
-    usage: { include: true },
-    ...(schema ? {
-      response_format: {
-        type: 'json_schema',
-        json_schema: { name: schema.name, strict: true, schema: schema.jsonSchema },
-      },
-      provider: { require_parameters: true },
-    } : {}),
-  };
-}
 
 // temperature padrão 0.2 (RFC-002 §5): "Determinism over Creativity". Pode ser
 // sobrescrita por chamada via opts, mas o default cobre spec/plan/decompose.
@@ -333,11 +257,14 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
     const callOpts = {
       temperature: sendTemperature ? temperature : undefined,
       maxTokens,
+      action: opts.action,
+      // É aqui que o motor paga por si: o modelo passa a poder LER o
+      // repositório antes de escrever o documento. É o que os blocos
+      // `requires-tools` dos model-prompt sempre descreveram.
+      tools: opts.tools ?? ['Read', 'Glob', 'Grep'],
     };
     const { text, usage } = await withRetry(`Geração via ${ai.provider}`, () =>
-      ai.provider === 'openrouter'
-        ? generateWithOpenRouter(system, userContent, ai, callOpts)
-        : generateWithAnthropic(system, userContent, ai, callOpts));
+      generateViaEngine(system, userContent, ai, callOpts));
     inputTokens += usage.inputTokens;
     outputTokens += usage.outputTokens;
     if (typeof usage.cost === 'number') cost = (cost ?? 0) + usage.cost;
@@ -441,14 +368,13 @@ export async function generateStructured(systemPrompt, userContent, opts = {}) {
     maxTokens,
     schema,
     strict,
+    action: opts.action,
   };
 
   // A validação roda DENTRO do retry de propósito: um payload fora do schema é
   // marcado como transitório, e repetir a mesma requisição costuma resolver.
   const { value, usage } = await withRetry(`Geração estruturada via ${ai.provider}`, async () => {
-    const res = ai.provider === 'openrouter'
-      ? await generateWithOpenRouter(systemPrompt, userContent, ai, callOpts)
-      : await generateWithAnthropic(systemPrompt, userContent, ai, callOpts);
+    const res = await generateViaEngine(systemPrompt, userContent, ai, callOpts);
     return { value: schema.validate ? schema.validate(res.json) : res.json, usage: res.usage };
   }, opts.retry);
 
@@ -506,181 +432,72 @@ export function extractOpenRouterUsage(usage) {
   };
 }
 
-async function generateWithAnthropic(
-  systemPrompt, userContent, ai, { temperature, maxTokens, schema, strict }
+/**
+ * Ponte para o motor do agente (`src/agent/`).
+ *
+ * Substitui as duas funções que falavam com a API diretamente
+ * (`generateWithAnthropic` / `generateWithOpenRouter`). O motor foi portado do
+ * agent-cli e traz o que o caminho direto não tinha: loop agêntico com
+ * Read/Glob/Grep de verdade e instrumentação Langfuse.
+ *
+ * Tudo o que já estava CERTO neste módulo continua acima desta linha —
+ * resolução de modelo por ação/label, retry, lint de idioma, contagem de uso.
+ * O motor cuida da chamada; este arquivo segue dono da política.
+ *
+ * O prompt do sistema vira `systemPromptAppend` de propósito: no backend
+ * anthropic ele é ANEXADO ao preset `claude_code`, preservando a competência de
+ * uso de tools do harness em vez de substituí-la.
+ *
+ * @returns {Promise<{text: string, json?: object, usage: object}>}
+ */
+async function generateViaEngine(
+  systemPrompt, userContent, ai, { temperature, maxTokens, schema, strict, action, tools },
 ) {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    throw new Error(
-      'ANTHROPIC_API_KEY not set.\n' +
-      'Add it as a GitHub Actions secret or set it in your environment.'
-    );
-  }
+  const result = await runAgent(userContent, {
+    provider: ai.provider,
+    model: ai.model,
+    systemPromptAppend: systemPrompt,
+    // Sessão/usuário alimentam o agrupamento das traces no Langfuse. Sem
+    // telemetria configurada nada disso sai do processo.
+    sessionId: `spec-wave-${action || 'run'}`,
+    userId: 'spec-wave',
+    ...(tools ? { tools } : {}),
+    ...(maxTokens ? { maxTokens } : {}),
+    ...(temperature !== undefined ? { temperature } : {}),
+    ...(schema
+      ? { responseSchema: { ...schema, strict: strict === true } }
+      : {}),
+    ...(action ? { action, extraTags: [action] } : {}),
+    cwd: ai.cwd ?? process.cwd(),
+    quiet: true,
+  });
 
-  const client = new Anthropic({ apiKey });
-  const message = await client.messages.create(buildAnthropicRequest({
-    ai, systemPrompt, userContent, temperature, maxTokens, schema, strict,
-  }));
-
-  // A resposta nem sempre começa com um bloco de texto (recusa, resposta vazia):
-  // `content[0].text` cru virava TypeError com mensagem inútil.
-  const text = (message.content || [])
-    .filter((block) => block.type === 'text')
-    .map((block) => block.text)
-    .join('');
-  // Com tool_choice forçado a resposta traz um bloco tool_use e NENHUM bloco de
-  // texto — daí a necessidade do branch dedicado antes da checagem de texto vazio.
-  const tool = (message.content || [])
-    .find((block) => block.type === 'tool_use' && block.name === schema?.name);
-
-  if (message.stop_reason === 'refusal') {
-    throw new Error(
-      `A Anthropic recusou a requisição (stop_reason=refusal` +
-      `${message.stop_details?.category ? `, categoria=${message.stop_details.category}` : ''}). ` +
-      'Revise o conteúdo da issue de origem.'
-    );
-  }
-  if (message.stop_reason === 'model_context_window_exceeded') {
-    // Estouro na ENTRADA — subir max_tokens não resolve; o que precisa encolher
-    // é a issue/contexto enviado.
-    throw new Error(
-      `Contexto de entrada excedido (${ai.model}). Reduza o tamanho da issue de origem ` +
-      'ou do tech_context antes de repetir.'
-    );
-  }
-  if (isTruncationReason(message.stop_reason)) {
-    throw new TruncatedOutputError({
-      provider: 'anthropic',
-      model: ai.model,
-      maxTokens,
-      reason: message.stop_reason,
-      // Sob tool call forçado não há bloco de texto: medir `text.length` diria
-      // sempre "~0 caracteres antes do corte".
-      chars: schema ? JSON.stringify(tool?.input ?? '').length : text.length,
-    });
-  }
+  const usage = {
+    inputTokens: result.usage?.inputTokens ?? 0,
+    outputTokens: result.usage?.outputTokens ?? 0,
+    cost: result.costUsd,
+  };
 
-  // ATENÇÃO: este branch precisa vir ANTES da checagem de `!text` — uma resposta
-  // com tool call forçado não tem bloco de texto, e cair no `!text` faria toda
-  // crítica queimar os 3 retries com a mensagem errada.
   if (schema) {
-    if (!tool || typeof tool.input !== 'object' || tool.input === null) {
+    if (result.structured === null || result.structured === undefined) {
       const err = new Error(
-        `A Anthropic não devolveu a ferramenta \`${schema.name}\` ` +
-        `(stop_reason=${message.stop_reason}). Conteúdo: ${text.slice(0, 200) || '(vazio)'}`
+        `O modelo ${ai.model} não devolveu a saída estruturada "${schema.name}" ` +
+        `(subtype=${result.resultSubtype}).`
       );
-      err.transient = true; // ferramenta forçada: repetir a requisição costuma resolver
+      err.transient = true; // repetir a mesma requisição costuma resolver
       throw err;
     }
-    return {
-      text: JSON.stringify(tool.input),
-      json: tool.input,
-      usage: extractAnthropicUsage(message.usage),
-    };
+    return { text: result.outputText, json: result.structured, usage };
   }
 
+  const text = stripReasoning(result.outputText || '');
   if (!text) {
     const err = new Error(
-      `A Anthropic retornou resposta sem texto (stop_reason=${message.stop_reason}).`
-    );
-    err.transient = true;
-    throw err;
-  }
-
-  return { text, usage: extractAnthropicUsage(message.usage) };
-}
-
-async function generateWithOpenRouter(
-  systemPrompt, userContent, ai, { temperature, maxTokens, schema }
-) {
-  const apiKey = process.env.OPENROUTER_API_KEY;
-  if (!apiKey) {
-    throw new Error(
-      'OPENROUTER_API_KEY not set.\n' +
-      'Add it as a GitHub Actions secret or set it in your environment.'
-    );
-  }
-
-  const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-      'HTTP-Referer': 'https://github.com/moacsjr/spec-wave',
-      'X-Title': 'spec-wave',
-    },
-    body: JSON.stringify(buildOpenRouterBody({
-      ai, systemPrompt, userContent, temperature, maxTokens, schema,
-    })),
-  });
-
-  if (!res.ok) {
-    const body = await res.text();
-    const err = new Error(
-      `OpenRouter API ${res.status}: ${body}` +
-      // require_parameters faz o roteador recusar quando nenhum provedor do modelo
-      // implementa response_format — erro de CONFIGURAÇÃO, não de rede.
-      (schema && (res.status === 404 || res.status === 400)
-        ? `\nNenhum provedor de ${ai.model} suporta response_format/json_schema. ` +
-          'Aponte `ai.models.critique` no .spec-wave.json para um modelo com saída estruturada.'
-        : '')
-    );
-    err.status = res.status;
-    throw err;
-  }
-
-  // Um 200 com corpo vazio ou cortado acontece em gerações longas. `res.json()`
-  // cru lançaria "Unexpected end of JSON input" — mensagem que não diz nada a
-  // quem está olhando o board. Lê como texto, reporta o que veio e marca como
-  // transitória para o retry pegar.
-  const raw = await res.text();
-  let data;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    const err = new Error(
-      `OpenRouter devolveu ${res.status} com corpo inválido (${raw.length} bytes): ` +
-      `${raw.slice(0, 200) || '(vazio)'}`
+      `O provider ${ai.provider} retornou resposta sem texto ` +
+      `(subtype=${result.resultSubtype}, turnos=${result.numTurns}).`
     );
     err.transient = true;
     throw err;
   }
-
-  const choice = data?.choices?.[0];
-  const content = stripReasoning(choice?.message?.content || '');
-
-  // finish_reason='length' = cortado no teto. Checado ANTES do conteúdo vazio:
-  // um corte durante o raciocínio devolve texto vazio, e "resposta vazia" (que
-  // é tratada como transitória) esconderia a causa real por trás de 3 retries.
-  if (isTruncationReason(choice?.finish_reason)) {
-    throw new TruncatedOutputError({
-      provider: 'openrouter',
-      model: ai.model,
-      maxTokens,
-      // native_finish_reason preserva o motivo cru do provedor upstream.
-      reason: `${choice.finish_reason}${choice.native_finish_reason ? `/${choice.native_finish_reason}` : ''}`,
-      chars: content.length,
-    });
-  }
-  if (!content) {
-    const err = new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
-    err.transient = true;
-    throw err;
-  }
-
-  if (schema) {
-    const raw = stripOuterFence(content);
-    try {
-      return { text: raw, json: JSON.parse(raw), usage: extractOpenRouterUsage(data.usage) };
-    } catch {
-      const err = new Error(
-        `O modelo ${ai.model} ignorou response_format e devolveu texto não-JSON ` +
-        `(${raw.length} bytes): ${raw.slice(0, 200)}`
-      );
-      err.transient = true; // ≠ truncamento: repetir pode dar certo
-      throw err;
-    }
-  }
-
-  return { text: content, usage: extractOpenRouterUsage(data.usage) };
+  return { text, usage };
 }

package/src/lib/critique.mjs

@@ -22,6 +22,7 @@ import { generateStructured } from './claude.mjs';
 import {
   LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
 } from '../config.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from './prompt-loader.mjs';
 
 // Severidades aceitas — enum FECHADO. O teste de prefixo /^grave/i sobre texto
 // livre que existia aqui aceitava "gravíssimo" e rebaixava "critical"/"high"
@@ -41,21 +42,11 @@ 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' };
-
-// Redação específica por tipo de auditoria. 'plan' audita o plan.md contra a
-// spec; 'stories' audita a decomposição proposta contra spec + plan.
-const KIND_FOCUS = {
-  plan:
-    'Audite o plan.md contra o spec.md, as regras de negócio e o tech_context fornecidos. ' +
-    'Procure decisões técnicas que contradizem ou ignoram requisitos da spec e ' +
-    'tecnologias/serviços fora do tech_context.',
-  stories:
-    'Audite a decomposição proposta (documento Markdown com Stories e suas Tasks) contra o ' +
-    'spec.md e o plan.md fornecidos. Procure Stories que contradizem, invertem ou ignoram ' +
-    'requisitos da spec ou decisões do plan, critérios de aceite incompatíveis com as regras ' +
-    'de negócio, e Tasks que não sustentam a Story a que pertencem.',
-};
+const KIND_LABEL = { plan: 'plan.md', stories: 'decomposition.md', bug: 'bug.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' };
 
 // 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
@@ -67,28 +58,39 @@ const ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho audita
 - "geral" quando o problema for da decomposição como um todo (ex.: requisito da spec que nenhuma Story cobre).
 Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "### Task N.M — ..." do documento.`;
 
-function buildSystemPrompt(kind) {
-  const focus = KIND_FOCUS[kind] || KIND_FOCUS.plan;
+/**
+ * Monta o system prompt da crítica: corpo editável + contrato de máquina.
+ *
+ * A divisão não é estética. O CORPO (`model-prompt.critique.md` da skill do comando) é a redação
+ * — foco da auditoria, o que conta como achado, a barra de rigor — e o time
+ * pode sobrescrevê-lo em `.spec-wave/prompts/` para apertar ou afrouxar o
+ * critério. O CONTRATO abaixo é acoplado a `critiqueJsonSchema()` e a
+ * `validateCritiquePayload()`: o enum de `severity`, a âncora `Story N` /
+ * `Task N.M` e a obrigação de chamar a tool. Ele é anexado por ÚLTIMO
+ * justamente para que um override de projeto não consiga anulá-lo — um payload
+ * fora do contrato falha alto, e não vale deixar isso na mão do texto.
+ *
+ * @param {'plan'|'stories'} kind
+ * @param {string} [cwd] raiz do repositório (resolve o override do projeto)
+ */
+function buildSystemPrompt(kind, cwd) {
+  const prompt = loadPrompt(KIND_PROMPT[kind] || KIND_PROMPT.plan, ...(cwd ? [{ cwd }] : []));
   const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}` : '';
-  return `Você é um revisor técnico CÉTICO e adversarial. Seu papel é encontrar problemas, não elogiar.
 
-${focus}
-
-Liste:
-- contradições diretas entre os documentos;
-- inversões de requisito (ex.: consentimento→persistência invertidos: a spec exige consentimento ANTES de persistir e o documento persiste antes de pedir consentimento);
-- violações de restrições explícitas (ex.: minimização de dados LGPD, limites de retenção, campos proibidos);
-- itens que contradizem ou ignoram a spec.
+  const contract = `## Contrato de saída
 
 Classifique cada finding no campo "severity", usando EXATAMENTE um destes dois valores:
 - "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.
 
-NÃO invente problemas: se os documentos estiverem consistentes, retorne a lista vazia.
 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.
 Se os documentos estiverem consistentes, chame-a com "findings": [].`;
+
+  // Sem tool loop de leitura aqui: `generateStructured` faz UMA chamada, com a
+  // tool de saída estruturada como única ferramenta.
+  return toolFreeSystemPrompt(prompt, contract);
 }
 
 function critiqueJsonSchema(kind) {
@@ -338,6 +340,11 @@ const KIND_TRAILER = {
       `\`decomposition.md\` (as âncoras acima apontam para ele), remova a label ` +
       `\`${LABEL_CRITIQUE_FAILED}\` e reaplique \`spec-wave:decompose\` para uma nova crítica.`
     : '_Findings menores não bloqueiam a decomposição._'),
+  bug: (graves) => (graves
+    ? `⛔ Há findings **graves**: a label \`${LABEL_CRITIQUE_FAILED}\` bloqueia a triagem ` +
+      'até ser removida. Um bug com causa raiz errada produz correção errada — corrija o ' +
+      '`bug.md` e reaplique `spec-wave:bug`.'
+    : '_Findings menores não bloqueiam a triagem._'),
 };
 
 /**
@@ -406,11 +413,13 @@ export function renderCritiqueMarkdown({
  * chamador decidir entre seguir com aviso e abortar.
  *
  * @param {object} params
- * @param {'plan'|'stories'} params.kind o que está sendo auditado
+ * @param {'plan'|'stories'|'bug'} params.kind o que está sendo auditado
  * @param {string} [params.spec] conteúdo do spec.md
  * @param {string} [params.plan] conteúdo do plan.md
  * @param {string} [params.techContextYaml] tech_context serializado em YAML
  * @param {string} [params.decomposition] conteúdo do decomposition.md
+ * @param {string} [params.bugDoc] conteúdo do bug.md
+ * @param {string} [params.bugReport] relato original (corpo da issue + comentários)
  * @param {number} [params.attempt] tentativa em curso (cabeçalho e marcador)
  * @param {number} [params.maxAttempts]
  * @param {string} [params.model] modelo imposto (escalada); undefined = cadeia normal
@@ -419,9 +428,9 @@ export function renderCritiqueMarkdown({
  * @returns {Promise<{grave, findings, markdown, attempt, model}>}
  */
 export async function runCritique({
-  kind, spec, plan, techContextYaml, decomposition,
+  kind, spec, plan, techContextYaml, decomposition, bugDoc, bugReport,
   attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
-  model, labels = [], usage,
+  model, labels = [], usage, cwd,
 } = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
@@ -434,9 +443,13 @@ export async function runCritique({
       `## Decomposição proposta (decomposition.md)\n\n\`\`\`\`markdown\n${decomposition}\n\`\`\`\``
     );
   }
+  // O relato é a fonte contra a qual o bug.md é auditado: a causa raiz proposta
+  // tem que explicar OS SINTOMAS RELATADOS, não sintomas plausíveis quaisquer.
+  if (bugReport) sections.push(`## Relato original (issue e comentários)\n\n${bugReport}`);
+  if (bugDoc) sections.push(`## bug.md\n\n${bugDoc}`);
   const userContent = sections.join('\n\n') || '(nenhum documento fornecido)';
 
-  const report = await generateStructured(buildSystemPrompt(kind), userContent, {
+  const report = await generateStructured(buildSystemPrompt(kind, cwd), userContent, {
     action: 'critique',
     temperature: 0,
     schema: {

package/src/lib/flow-run.mjs

@@ -0,0 +1,145 @@
+// Modo de execução do fluxo: GitHub Actions ou sessão local.
+//
+// `generate-spec`, `generate-plan` e `decompose` nasceram como comandos de
+// Action e exigiam `GITHUB_REPOSITORY`, recusando qualquer execução fora do
+// runner. Mas eles são só comandos — o que os prendia ao CI era a resolução de
+// owner/repo, não o trabalho em si. Agora o MESMO comando roda nos dois lugares:
+// dentro do Action, disparado por label, ou na sua sessão do agente.
+//
+// O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), não por flag: um
+// comando com dois nomes para a mesma coisa envelhece mal.
+//
+// **O comportamento é deliberadamente IDÊNTICO nos dois modos** — gera, commita,
+// dá pull --rebase, faz push, comenta na issue e avança a Etapa. O board é a
+// fonte de verdade do RFC-001 independentemente de onde a geração rodou; um modo
+// local que não sincronizasse o board deixaria o próximo passo do fluxo cego.
+//
+// Duas diferenças existem, e as duas são de SEGURANÇA, não de resultado:
+//
+//  1. IDENTIDADE DO GIT. O Action roda `git config user.email "spec-wave[bot]"`
+//     sem `--global`, o que grava em `.git/config`. Num runner descartável isso
+//     é inócuo; no seu clone, mudaria o autor de TODOS os seus commits futuros
+//     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.
+
+import { execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveRepoContext } from './project-root.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+
+/** Rodando dentro do GitHub Actions? (função PURA) */
+export function isActionsRun(env = process.env) {
+  return env.GITHUB_ACTIONS === 'true';
+}
+
+/** 'actions' | 'local' (função PURA) */
+export function executionMode(env = process.env) {
+  return isActionsRun(env) ? 'actions' : 'local';
+}
+
+/**
+ * Resolve owner/repo + modo, ou lança com a instrução certa para cada contexto.
+ *
+ * Nos Actions o `GITHUB_REPOSITORY` vem do runner; local, o `.spec-wave.json`
+ * gravado pelo `init` é a fonte. `resolveRepoContext` já cobre os dois.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.command] nome do comando, para a mensagem de erro
+ * @param {object} [opts.env]
+ * @returns {{owner: string, repo: string, root: string|null, config: object|null, mode: 'actions'|'local'}}
+ */
+export function resolveFlowContext({ cwd = process.cwd(), command = 'este comando', env = process.env } = {}) {
+  // Repassa o `env` recebido: sem isso o modo local fica intestável dentro do
+  // GitHub Actions, que define GITHUB_REPOSITORY em toda execução.
+  const { owner, repo, root, config } = resolveRepoContext(cwd, env);
+  const mode = executionMode(env);
+
+  if (!owner || !repo) {
+    throw new Error(
+      'Não foi possível determinar owner/repo.\n' +
+      (mode === 'actions'
+        ? 'No GitHub Actions, o runner define GITHUB_REPOSITORY — verifique o workflow.'
+        : `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`), ` +
+          `ou defina GITHUB_REPOSITORY=owner/repo:\n` +
+          `  GITHUB_REPOSITORY=owner/repo spec-wave ${command} --issue-number 1`)
+    );
+  }
+  return { owner, repo, root, config, mode };
+}
+
+/**
+ * Grava um arquivo gerado e o publica: commit + pull --rebase + push.
+ *
+ * Era o mesmo bloco copiado em `generate-spec`, `generate-plan` e `decompose`,
+ * com a identidade do bot embutida. Centralizado aqui para que a diferença
+ * entre os modos exista num lugar só.
+ *
+ * O commit é escopado ao caminho (`git commit -- <arquivo>`): sem isso, qualquer
+ * coisa que você já tivesse no index entraria junto no commit do spec-wave —
+ * irrelevante num runner limpo, nada irrelevante no seu clone.
+ *
+ * @param {object} params
+ * @param {string} params.filePath caminho absoluto do arquivo
+ * @param {string} params.content
+ * @param {string} params.message mensagem de commit
+ * @param {'actions'|'local'} params.mode
+ * @returns {{committed: boolean, pushed: boolean, warning: string|null}}
+ */
+export function commitGenerated({ filePath, content, message, mode }) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content, 'utf-8');
+
+  const git = (cmd, opts = {}) => execSync(cmd, { stdio: 'inherit', ...opts });
+  const gitQuiet = (cmd) => execSync(cmd, { stdio: 'pipe' }).toString().trim();
+
+  if (mode === 'actions') {
+    // Runner descartável: identidade do bot é o que se quer no histórico.
+    git('git config user.email "spec-wave[bot]@github.com"');
+    git('git config user.name "spec-wave[bot]"');
+  }
+
+  git(`git add "${filePath}"`);
+
+  // Nada mudou (regerar conteúdo idêntico) → `git commit` sairia 1 e derrubaria
+  // o comando depois de o trabalho estar feito.
+  let hasChanges = true;
+  try {
+    execSync(`git diff --cached --quiet -- "${filePath}"`, { stdio: 'pipe' });
+    hasChanges = false;
+  } catch {
+    hasChanges = true;
+  }
+  if (!hasChanges) {
+    return { committed: false, pushed: false, warning: 'conteúdo idêntico ao já versionado — nada a commitar' };
+  }
+
+  git(`git commit -m "${message}" -- "${filePath}"`);
+
+  try {
+    git('git pull --rebase');
+    git('git push');
+    return { committed: true, pushed: true, warning: null };
+  } catch (err) {
+    if (mode === 'actions') throw err;
+    // Local: o arquivo está gerado e commitado. Derrubar o comando aqui
+    // esconderia esse fato atrás de um erro de rede/divergência.
+    const branch = (() => {
+      try {
+        return gitQuiet('git rev-parse --abbrev-ref HEAD');
+      } catch {
+        return 'seu branch';
+      }
+    })();
+    return {
+      committed: true,
+      pushed: false,
+      warning:
+        `commit feito em ${branch}, mas o push falhou (${err.message.split('\n')[0]}). ` +
+        'O arquivo está salvo e versionado — publique quando resolver.',
+    };
+  }
+}