@spec-wave/cli 0.18.1 → 0.19.0

package/src/commands/doctor.mjs

@@ -8,18 +8,22 @@ import path from 'node:path';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { Octokit } from '@octokit/rest';
-import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
-import { getProjectSnapshot } from '../api/github-graphql.mjs';
+import {
+  resolveToken, verifyTokenScopes, describeTokenSource, activeGhAccount,
+  tokenMismatchWarning, parseActiveAccount,
+} from '../api/auth.mjs';
+import { getProjectSnapshot, listSubIssues } from '../api/github-graphql.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
-  RETIRED_STAGES, ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
-  DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS,
+  RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
+  DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS,
 } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import {
-  DEFAULT_MAX_TOKENS, MAX_TOKENS_BY_ACTION, supportsStrictSchema,
+  DEFAULT_MAX_TOKENS, supportsStrictSchema, resolveAiConfig,
 } from '../lib/claude.mjs';
 import { CLI_VERSION } from '../lib/templates.mjs';
+import { parseDecompositionDoc, DECOMPOSITION_FILE } from '../lib/decomposition-doc.mjs';
 
 // Mesmo padrão de instanciação de github-rest.mjs, mas com o logger mudo:
 // aqui 404/403 são resultados esperados dos checks, não erros a logar.
@@ -60,11 +64,20 @@ export function renderDoctorReport(results) {
 
 async function checkToken(ctx) {
   const name = 'Token GitHub';
-  let source = 'gh CLI (`gh auth token`)';
-  if (process.env.GITHUB_TOKEN) source = 'variável de ambiente GITHUB_TOKEN';
-  else if (process.env.GH_TOKEN) source = 'variável de ambiente GH_TOKEN';
+  // A origem sai do MESMO resolvedor que o comando usa — antes esta função
+  // reimplementava a precedência, e uma divergência entre as duas seria
+  // exatamente o tipo de erro que o doctor existe para pegar.
+  const source = describeTokenSource();
   try {
-    ctx.token = await resolveToken();
+    ctx.token = await resolveToken({ quiet: true });
+    // Divergência entre a conta ativa do gh e a origem do token: o sintoma é um
+    // GraphQL dizendo "Could not resolve to a Repository" enquanto o REST
+    // funciona — 403 mascarado de 404.
+    ctx.activeGhAccount = activeGhAccount();
+    const mismatch = tokenMismatchWarning();
+    if (mismatch) {
+      return { name, status: 'warn', detail: `Token resolvido via ${source}.\n${mismatch}` };
+    }
     return { name, status: 'ok', detail: `Token resolvido via ${source}.` };
   } catch {
     return {
@@ -157,19 +170,10 @@ async function checkGhAccount(ctx) {
     return { name, status: 'warn', detail: 'gh não instalado ou não logado — verificação de conta pulada.' };
   }
 
-  // Formato: "✓ Logged in to github.com account <login> (...)" seguido de
-  // "- Active account: true". Em versões antigas (uma conta só) não há a
-  // linha "Active account" — usa a primeira conta encontrada.
-  let active = null;
-  let last = null;
-  for (const line of out.split('\n')) {
-    const m = line.match(/account\s+(\S+)/);
-    if (m) {
-      last = m[1];
-      if (!active) active = last;
-    }
-    if (/Active account:\s*true/i.test(line) && last) active = last;
-  }
+  // O parser vive em api/auth.mjs, junto de quem RESOLVE o token: se as duas
+  // leituras de "conta ativa" divergissem, o doctor apontaria uma conta e o
+  // comando usaria outra — exatamente o erro que este check existe para pegar.
+  const active = parseActiveAccount(out);
   if (!active) {
     return { name, status: 'warn', detail: 'Não foi possível identificar a conta ativa na saída de `gh auth status`.' };
   }
@@ -310,7 +314,7 @@ export function inspectStageIds({ configOptions = null, boardOptions = null } =
   return { staleIds, checked: true };
 }
 
-export function inspectBoardHygiene({ boardStages = null, repoLabels = null } = {}) {
+export function inspectBoardHygiene({ boardStages = null, repoLabels = null, modelAliases = null } = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
   const retired = new Map(RETIRED_STAGES.map(s => [s.name, s]));
@@ -321,12 +325,25 @@ export function inspectBoardHygiene({ boardStages = null, repoLabels = null } =
   const unknownStages = foreign.filter(s => !retired.has(s));
   const missingStages = boardStages ? canonical.filter(s => !boardStages.includes(s)) : [];
 
-  const knownLabels = new Set(ALL_LABELS.map(l => l.name));
+  // As labels de modelo saem de `ai.modelAliases`, não de ALL_LABELS. Compará-las
+  // com a lista estática acusava TODO alias configurado como descontinuado, com
+  // o conselho de rodar `update` para removê-los — e o update, com a mesma
+  // cegueira, os removeria mesmo, quebrando o override de modelo por issue em
+  // silêncio. Pior: o próprio doctor lista esses apelidos como usáveis quatro
+  // linhas abaixo, no check de IA, contradizendo-se na mesma saída.
+  //
+  // Com o config em mãos, `spec-wave:model:<x>` só é órfã quando <x> NÃO está em
+  // ai.modelAliases — aí o aviso é verdadeiro (label aponta para apelido que não
+  // existe mais). Sem config (doctor sem acesso ao arquivo), nenhuma label de
+  // modelo é acusada: melhor calar do que mandar apagar o que funciona.
+  const wantedLabels = allLabelsFor(modelAliases ? { modelAliases } : undefined);
+  const knownLabels = new Set(wantedLabels.map(l => l.name));
   const orphanLabels = repoLabels
-    ? repoLabels.filter(n => n.startsWith('spec-wave:') && !knownLabels.has(n))
+    ? repoLabels.filter(n => n.startsWith('spec-wave:') && !knownLabels.has(n)
+        && (modelAliases !== null || !n.startsWith(MODEL_LABEL_PREFIX)))
     : [];
   const missingLabels = repoLabels
-    ? ALL_LABELS.map(l => l.name).filter(n => !repoLabels.includes(n))
+    ? wantedLabels.map(l => l.name).filter(n => !repoLabels.includes(n))
     : [];
   return { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels };
 }
@@ -391,7 +408,7 @@ async function checkBoardHygiene(ctx) {
   }
 
   const { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels } =
-    inspectBoardHygiene({ boardStages, repoLabels });
+    inspectBoardHygiene({ boardStages, repoLabels, modelAliases: cfg?.ai?.modelAliases ?? null });
 
   const notes = [];
   let status = 'ok';
@@ -521,18 +538,22 @@ async function checkAi(ctx) {
   // Teto de saída: quando o documento não cabe, a geração falha com
   // TruncatedOutputError em vez de gravar um arquivo cortado — mostrar o valor
   // resolvido evita ter que abrir o log do Action para descobri-lo.
+  //
+  // Mostrar o teto EFETIVO por ação (e não só o default global) porque a leitura
+  // "32768 (default) · critique=8192 (default)" já foi entendida como "o teto da
+  // crítica ignora a configuração", quando na verdade `ai.maxTokens` valia para
+  // ela também. Aqui cada ação vem com o número que de fato será usado.
   const maxTokensNote = fileAi.maxTokens
     ? `${fileAi.maxTokens} (ai.maxTokens)`
     : `${DEFAULT_MAX_TOKENS} (default)`;
-  const byAction = fileAi.maxTokensByAction && Object.keys(fileAi.maxTokensByAction).length > 0
-    ? ` · por ação: ${Object.entries(fileAi.maxTokensByAction).map(([a, t]) => `${a}=${t}`).join(', ')}`
-    : '';
-  const actionDefaults = Object.entries(MAX_TOKENS_BY_ACTION)
-    .filter(([a]) => !fileAi.maxTokensByAction?.[a] && !fileAi.maxTokens)
-    .map(([a, t]) => `${a}=${t} (default)`)
+  const efetivo = (action) => resolveAiConfig({ env: process.env, fileAi, action }).maxTokens;
+  const porAcao = AI_ACTIONS
+    .map(a => [a, efetivo(a)])
+    .filter(([, teto]) => teto !== efetivo(undefined))
+    .map(([a, teto]) => `${a}=${teto}`)
     .join(', ');
   notes.push(
-    `Teto de saída: ${maxTokensNote}${byAction}${actionDefaults ? ` · ${actionDefaults}` : ''}.`
+    `Teto de saída: ${maxTokensNote}${porAcao ? ` · efetivo por ação: ${porAcao}` : ' (vale para todas as ações)'}.`
   );
 
   let status = 'ok';
@@ -646,7 +667,16 @@ async function checkAi(ctx) {
         status = 'warn';
         notes.push(`Secrets do Actions faltando em ${cfg.owner}/${cfg.repo}: ${missing.join(', ')} — configure em Settings → Secrets.`);
       } else {
-        notes.push(`Secrets do Actions presentes: ${required.join(', ')}.`);
+        // PRESENÇA, não validade — a API expõe só os nomes dos secrets, nunca os
+        // valores, então não há como testar daqui se o token funciona. Dizer só
+        // "presentes" dava uma confiança que o check não sustenta: o
+        // GH_PROJECT_TOKEN do caso real ESTAVA presente e não alcançava o
+        // Project da organização, e as 27 issues criadas nasceram sem Etapa.
+        notes.push(
+          `Secrets do Actions presentes: ${required.join(', ')} ` +
+          '(só o NOME é verificável — a API não expõe o valor, então isto não atesta ' +
+          'que os tokens funcionam nem que têm o escopo necessário).'
+        );
       }
     } catch (err) {
       if (err.status === 403) {
@@ -660,6 +690,135 @@ async function checkAi(ctx) {
 }
 
 // Exportado para teste: só lê ctx.cfg e process.env — sem rede/filesystem.
+/**
+ * Compara o que o decomposition.md registra com as issues que existem hoje
+ * (função PURA — testável sem rede).
+ *
+ * Só faz sentido em arquivo com `applied=`: antes do apply ele é proposta, e
+ * proposta não tem com o que divergir. Depois, ele é REGISTRO — e registro que
+ * não bate com a realidade é pior que registro nenhum, porque parece confiável.
+ *
+ * @param {object} doc documento parseado (parseDecompositionDoc)
+ * @param {Map<number,{state?:string,title?:string}>} atual issues por número
+ * @returns {string[]} divergências em pt-BR (vazio = arquivo confere)
+ */
+export function decompositionDrift(doc, atual = new Map()) {
+  if (!doc?.appliedAt) return [];
+  const itens = [
+    ...(doc.stories || []).flatMap(s => [s, ...(s.tasks || [])]),
+    ...(doc.tasks || []),
+  ];
+  const out = [];
+  const registradas = new Set();
+  for (const item of itens) {
+    if (!item.issue) {
+      out.push(`${item.anchor} não tem "**Issue:** #N" — foi acrescentada ao arquivo depois do apply?`);
+      continue;
+    }
+    registradas.add(item.issue);
+    const issue = atual.get(item.issue);
+    if (!issue) {
+      out.push(`${item.anchor} aponta para #${item.issue}, que não existe mais (rescopada ou apagada).`);
+      continue;
+    }
+    if (issue.state === 'closed' && issue.stateReason === 'not_planned') {
+      out.push(`${item.anchor} (#${item.issue}) foi fechada como "não planejada" — o arquivo ainda a descreve.`);
+    }
+    if (issue.title && item.title && !issue.title.includes(item.title)) {
+      out.push(`${item.anchor} (#${item.issue}) foi renomeada: o arquivo diz "${item.title}", a issue diz "${issue.title}".`);
+    }
+  }
+  for (const [numero, issue] of atual) {
+    if (!registradas.has(numero)) {
+      out.push(`#${numero} ${issue.title || ''} existe na árvore mas não está no arquivo — criada fora do apply.`);
+    }
+  }
+  return out;
+}
+
+// Lê os decomposition.md aplicados e confere se ainda descrevem a árvore real.
+// Best-effort e sempre warn: divergência aqui é informação para o humano, não
+// falha de configuração — rescopar issues à mão é legítimo, esquecer de dizer
+// isso no arquivo é que não deveria passar despercebido.
+async function checkDecompositions(ctx) {
+  const name = 'Decomposições aplicadas (decomposition.md × issues)';
+  const root = ctx.root;
+  if (!root) return { name, status: 'warn', detail: `Sem ${CONFIG_FILE} — verificação pulada.` };
+
+  const featuresDir = path.join(root, 'docs', 'features');
+  if (!existsSync(featuresDir)) {
+    return { name, status: 'ok', detail: 'Nenhuma pasta docs/features — nada a conferir.' };
+  }
+
+  const arquivos = [];
+  for (const dir of readdirSync(featuresDir, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    const file = path.join(featuresDir, dir.name, DECOMPOSITION_FILE);
+    if (existsSync(file)) arquivos.push({ rel: `docs/features/${dir.name}/${DECOMPOSITION_FILE}`, file });
+  }
+  if (arquivos.length === 0) {
+    return { name, status: 'ok', detail: 'Nenhum decomposition.md encontrado.' };
+  }
+
+  const notes = [];
+  let status = 'ok';
+  let aplicados = 0;
+
+  for (const { rel, file } of arquivos) {
+    let doc;
+    try {
+      doc = parseDecompositionDoc(readFileSync(file, 'utf-8'));
+    } catch (err) {
+      status = 'warn';
+      notes.push(`${rel}: não foi possível ler — ${err.message}`);
+      continue;
+    }
+    if (!doc.appliedAt) continue; // ainda é proposta, não registro
+    aplicados += 1;
+
+    if (!ctx.token || !doc.issueNumber) {
+      notes.push(`${rel}: aplicado em ${doc.appliedAt} (issues não verificadas — sem token ou sem número no marcador).`);
+      continue;
+    }
+
+    // Monta a árvore real: sub-issues da Feature + as de cada Story.
+    const atual = new Map();
+    try {
+      const issue = await makeOctokit(ctx.token).rest.issues.get({
+        owner: ctx.cfg.owner, repo: ctx.cfg.repo, issue_number: doc.issueNumber,
+      });
+      const subs = await listSubIssues(ctx.token, issue.data.node_id);
+      for (const s of subs) {
+        atual.set(s.number, { title: s.title, state: s.state, stateReason: s.stateReason });
+        for (const t of await listSubIssues(ctx.token, s.nodeId).catch(() => [])) {
+          atual.set(t.number, { title: t.title, state: t.state, stateReason: t.stateReason });
+        }
+      }
+    } catch (err) {
+      notes.push(`${rel}: árvore de #${doc.issueNumber} não verificável agora (${err.message}).`);
+      continue;
+    }
+
+    const drift = decompositionDrift(doc, atual);
+    if (drift.length === 0) {
+      notes.push(`${rel}: confere com as ${atual.size} issue(s) de #${doc.issueNumber}.`);
+      continue;
+    }
+    status = 'warn';
+    notes.push(
+      `${rel} descreve um desenho diferente do que existe hoje:\n` +
+      drift.map(d => `  - ${d}`).join('\n') + '\n' +
+      '  Atualize o arquivo ou marque-o como histórico — aplicado ele é registro, e registro ' +
+      'errado parece confiável.'
+    );
+  }
+
+  if (aplicados === 0) {
+    return { name, status: 'ok', detail: `${arquivos.length} rascunho(s) ainda não aplicado(s) — nada a conferir.` };
+  }
+  return { name, status, detail: notes.join('\n') };
+}
+
 export function checkSpecKit(ctx) {
   const name = 'Spec-kit (specKit.command para o implement)';
   const fromEnv = process.env.SPEC_WAVE_IMPLEMENT_CMD;
@@ -769,6 +928,7 @@ export async function doctor() {
     checkRepoAccess,
     checkBoardHygiene,
     checkAi,
+    checkDecompositions,
     checkSpecKit,
     checkWorkflows,
   ];

package/src/commands/generate-bug.mjs

@@ -8,8 +8,6 @@
 //     pergunta que ela responde é se a causa raiz proposta explica OS SINTOMAS
 //     RELATADOS — sem o relato, ela só avalia coerência interna.
 //  3. Escreve em docs/bugs/<slug>/, fora de docs/features/.
-import { execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import {
   getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
@@ -18,9 +16,10 @@ import { generateDocument } from '../lib/claude.mjs';
 import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
-import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
+import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
+import { commitGenerated, executionMode } from '../lib/flow-run.mjs';
 import {
   runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
 } from '../lib/critique.mjs';
@@ -84,7 +83,7 @@ export async function generateBug({ issueNumber }) {
     return;
   }
 
-  const { slug, dirRel, fileRel, dirAbs, fileAbs } = bugDocPaths(issue.title, root);
+  const { slug, dirRel, fileRel, fileAbs } = bugDocPaths(issue.title, root);
 
   const comments = await listIssueComments(token, owner, repo, n).catch(() => []);
   const report = buildReport(issue, comments);
@@ -103,9 +102,11 @@ export async function generateBug({ issueNumber }) {
   const usageEntries = [];
   try {
     console.log(`Gerando bug.md para: ${issue.title}`);
-    const systemPrompt = toolFreeSystemPrompt(loadPrompt('bug', { cwd: root }));
+    const bugPrompt = loadPrompt('bug', { cwd: root });
+    const systemPrompt = systemPromptWithTools(bugPrompt);
     const { content: bruto } = await generateDocument(systemPrompt, userContent, {
       action: 'bug',
+      maxTurns: bugPrompt.maxTurns,
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
       withReport: true,
@@ -116,16 +117,18 @@ export async function generateBug({ issueNumber }) {
     // ver lib/unwrap-doc.mjs. O que vai para o repositório é o documento.
     const content = unwrapGeneratedDoc(bruto);
 
-    mkdirSync(dirAbs, { recursive: true });
-    writeFileSync(fileAbs, content, 'utf-8');
-
-    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-    git('git config user.email "spec-wave[bot]@github.com"');
-    git('git config user.name "spec-wave[bot]"');
-    git(`git add "${fileAbs}"`);
-    git(`git commit -m "docs: generate bug.md for ${slug} [spec-wave]"`);
-    git('git pull --rebase');
-    git('git push');
+    // Publica pelo mesmo caminho do generate-spec/plan/decompose: commit
+    // escopado ao arquivo, identidade do bot só no runner e repetição quando
+    // outro run rouba a ponta da branch. O bloco de git solto que existia aqui
+    // não tinha nada disso — em particular, o `git commit` sem `-- <arquivo>`
+    // varria para dentro do commit qualquer coisa que estivesse no index.
+    const published = commitGenerated({
+      filePath: fileAbs,
+      content,
+      message: `docs: generate bug.md for ${slug} [spec-wave]`,
+      mode: executionMode(),
+    });
+    if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
     await removeLabel(token, owner, repo, n, LABEL_BUG);
 

package/src/commands/generate-plan.mjs

@@ -21,7 +21,7 @@ import { slugify } from '../lib/slugify.mjs';
 import { resolveFromRoot } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
-import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
+import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 
 // Aviso anexado ao comentário quando o lint de idioma ainda reprova após o
 // retry automático do generateDocument (excertos ao redor de cada vazamento).
@@ -35,8 +35,10 @@ function formatLintWarning(lintFindings) {
 }
 
 // O prompt vive em `src/plugin/skills/plan/model-prompt.md` (sobrescrevível pelo
-// projeto em `.spec-wave/prompts/plan.md`). `toolFreeSystemPrompt` remove a orientação que
-// assume Read/Glob/Grep: aqui a geração é UMA chamada, sem tool loop.
+// projeto em `.spec-wave/prompts/plan.md`). `systemPromptWithTools` PRESERVA o
+// bloco `requires-tools`: o `generateDocument` entrega Read/Glob/Grep ao modelo,
+// e é esse bloco que o ensina a explorar o repositório e a parar de explorar.
+// Recortá-lo daqui deixava o modelo com as ferramentas e sem o manual.
 
 /**
  * Roda a crítica do plan e aplica as labels de bloqueio.
@@ -181,9 +183,11 @@ export async function generatePlan({ issueNumber }) {
   const usageEntries = [];
   try {
     console.log(`Gerando plan.md para: ${issue.title}`);
-    const systemPrompt = toolFreeSystemPrompt(loadPrompt('plan', { cwd: root }));
+    const planPrompt = loadPrompt('plan', { cwd: root });
+    const systemPrompt = systemPromptWithTools(planPrompt);
     const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
       action: 'plan',
+      maxTurns: planPrompt.maxTurns,
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
       withReport: true,
@@ -258,7 +262,91 @@ export async function generatePlan({ issueNumber }) {
  * presente é criticado como está. Para gerar outro plano do zero, o caminho
  * continua sendo `spec-wave:plan`.
  */
-export async function critique({ issueNumber }) {
+/**
+ * Tipo de crítica a partir do nome do arquivo (função PURA).
+ *
+ * `decomposition.md` é `stories` (e não `decomposition`) porque é esse o nome do
+ * kind na crítica desde antes de o rascunho virar arquivo — renomear aqui
+ * quebraria o contador de tentativas, que grava o kind no marcador.
+ *
+ * @param {string} filePath
+ * @returns {'plan'|'spec'|'stories'|'bug'|null}
+ */
+export function inferCritiqueKind(filePath) {
+  const base = path.basename(String(filePath || '')).toLowerCase();
+  if (base === 'plan.md') return 'plan';
+  if (base === 'spec.md') return 'spec';
+  if (base === 'decomposition.md') return 'stories';
+  if (base === 'bug.md') return 'bug';
+  return null;
+}
+
+/**
+ * Crítica AVULSA de um arquivo, sem issue e sem efeito colateral.
+ *
+ * Modo "quero saber como está": lê o arquivo (e os vizinhos que servem de
+ * contexto), roda a crítica e imprime. Não comenta, não aplica label, não conta
+ * tentativa — é consulta, não portão. É o que faltava enquanto se corrige um
+ * documento à mão, que é justamente o que o fluxo exige quando a crítica reprova.
+ */
+async function critiqueFile({ file, kind, failOnGrave }) {
+  const filePath = path.resolve(file);
+  if (!existsSync(filePath)) {
+    throw new Error(`Arquivo não encontrado: ${filePath}`);
+  }
+  const resolvedKind = kind || inferCritiqueKind(filePath);
+  if (!resolvedKind) {
+    throw new Error(
+      `Não consegui inferir o tipo de crítica de "${path.basename(filePath)}". ` +
+      'Use --kind plan|spec|stories|bug.'
+    );
+  }
+
+  // Vizinhos do mesmo diretório entram como contexto quando existem: o plan é
+  // auditado CONTRA a spec, e a decomposição contra as duas.
+  const dir = path.dirname(filePath);
+  const ler = (nome) => {
+    const p = path.join(dir, nome);
+    return existsSync(p) && p !== filePath ? readFileSync(p, 'utf-8') : null;
+  };
+  const conteudo = readFileSync(filePath, 'utf-8');
+
+  console.log(`Crítica avulsa de ${path.relative(process.cwd(), filePath)} (kind=${resolvedKind}).`);
+  const result = await runCritique({
+    kind: resolvedKind,
+    spec: resolvedKind === 'spec' ? conteudo : ler('spec.md'),
+    plan: resolvedKind === 'plan' ? conteudo : ler('plan.md'),
+    decomposition: resolvedKind === 'stories' ? conteudo : null,
+    bugDoc: resolvedKind === 'bug' ? conteudo : null,
+    cwd: dir,
+    standalone: true,
+    usage: [],
+  });
+
+  console.log(`\n${result.markdown}\n`);
+  if (result.grave && failOnGrave) {
+    console.error('Findings graves encontrados (--fail-on-grave).');
+    process.exitCode = 1;
+  }
+  return result;
+}
+
+export async function critique({ issueNumber, file, kind, failOnGrave = false }) {
+  // `--file` é o modo local: sem issue, sem label, sem contador de tentativas.
+  if (file && !issueNumber) {
+    await critiqueFile({ file, kind, failOnGrave });
+    return;
+  }
+  if (!issueNumber) {
+    throw new Error('Informe --issue-number <n> ou --file <caminho>.');
+  }
+  if (kind && kind !== 'plan') {
+    throw new Error(
+      `--kind ${kind} só funciona com --file: pela issue, o gatilho \`spec-wave:critique\` ` +
+      'audita o plan.md (é ele que destrava o `spec-wave:ready`).'
+    );
+  }
+
   const token = await resolveToken();
   const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'critique' });
   console.log(`Modo de execução: ${mode}`);

package/src/commands/generate-spec.mjs

@@ -7,7 +7,7 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { resolveFromRoot } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
-import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
+import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
   allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE, labelNames,
@@ -25,8 +25,9 @@ function formatLintWarning(lintFindings) {
 }
 
 // O prompt vive em `src/plugin/skills/spec/model-prompt.md` (sobrescrevível pelo
-// projeto em `.spec-wave/prompts/spec.md`). `toolFreeSystemPrompt` remove a orientação que assume
-// Read/Glob/Grep: aqui a geração é UMA chamada de completions, sem tool loop.
+// projeto em `.spec-wave/prompts/spec.md`). `systemPromptWithTools` PRESERVA o
+// bloco `requires-tools`: o `generateDocument` entrega Read/Glob/Grep ao modelo,
+// e é esse bloco que o ensina a explorar o repositório e a parar de explorar.
 
 export async function generateSpec({ issueNumber }) {
   const token = await resolveToken();
@@ -79,9 +80,11 @@ export async function generateSpec({ issueNumber }) {
   const usageEntries = [];
   try {
     console.log(`Gerando spec.md para: ${issue.title}`);
-    const systemPrompt = toolFreeSystemPrompt(loadPrompt('spec', { cwd: root }));
+    const specPrompt = loadPrompt('spec', { cwd: root });
+    const systemPrompt = systemPromptWithTools(specPrompt);
     const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
       action: 'spec',
+      maxTurns: specPrompt.maxTurns,
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
       withReport: true,