@spec-wave/cli 0.13.0 → 0.14.0

package/src/commands/dev-agent.mjs

@@ -20,6 +20,7 @@ import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CONFIG_FILE } from '../config.mjs';
+import { findConfigPath } from '../lib/project-root.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dir, '..', 'templates', 'agent');
@@ -180,8 +181,8 @@ function writeInstalledTag(home, tag) {
 }
 
 function readRepoConfig(cwd) {
-  const configPath = path.join(cwd, CONFIG_FILE);
-  if (!existsSync(configPath)) {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) {
     return { error: `${CONFIG_FILE} não encontrado. Rode \`spec-wave init\` neste repositório primeiro.` };
   }
   try {

package/src/commands/doctor.mjs

@@ -10,8 +10,15 @@ import chalk from 'chalk';
 import { Octokit } from '@octokit/rest';
 import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
-import { CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
-import { DEFAULT_MAX_TOKENS } from '../lib/claude.mjs';
+import {
+  CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
+  ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX, DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+} from '../config.mjs';
+import { findConfigPath } from '../lib/project-root.mjs';
+import {
+  DEFAULT_MAX_TOKENS, MAX_TOKENS_BY_ACTION, supportsStrictSchema,
+} from '../lib/claude.mjs';
+import { CLI_VERSION } from '../lib/templates.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.
@@ -199,11 +206,13 @@ async function checkGhAccount(ctx) {
 
 async function checkConfig(ctx) {
   const name = `Configuração (${CONFIG_FILE})`;
-  if (!existsSync(ctx.configPath)) {
+  if (!ctx.configPath) {
     return {
       name,
       status: 'fail',
-      detail: `${CONFIG_FILE} não encontrado em ${ctx.cwd}. Rode \`npx @spec-wave/cli@latest init\`.`,
+      detail:
+        `${CONFIG_FILE} não encontrado em ${ctx.cwd} nem em nenhum diretório acima. ` +
+        'Rode `npx @spec-wave/cli@latest init`.',
     };
   }
   if (ctx.cfgError) {
@@ -211,6 +220,9 @@ async function checkConfig(ctx) {
   }
   const { cfg } = ctx;
   const notes = [`Repositório: ${cfg.owner ?? '?'}/${cfg.repo ?? '?'}.`];
+  if (ctx.root && ctx.root !== ctx.cwd) {
+    notes.push(`Raiz do projeto: ${ctx.root} (o comando foi rodado de um subdiretório).`);
+  }
 
   const fields = cfg.project?.fields || {};
   const missingFields = ['Etapa', 'Status'].filter((f) => !fields[f]);
@@ -254,6 +266,109 @@ async function checkConfig(ctx) {
   return { name, status: 'ok', detail: notes.join('\n') };
 }
 
+/**
+ * Higiene do board e das labels (função PURA — testável sem rede).
+ *
+ * Dois problemas que passavam em silêncio:
+ *  • colunas de Etapa fora de STATUS_OPTIONS. A checagem de retrocesso compara a
+ *    etapa atual com a ordem canônica; um item numa coluna desconhecida não tem
+ *    posição na ordem, e o board perde a garantia de fluxo só-para-frente;
+ *  • labels `spec-wave:*` descontinuadas. O `update` só criava e atualizava, então
+ *    uma label removida do config ficava para sempre (caso da `spec-wave:force`).
+ *
+ * @param {object} params
+ * @param {string[]} [params.boardStages] opções reais de Etapa no project
+ * @param {string[]} [params.repoLabels] nomes das labels do repo
+ * @returns {{ unknownStages: string[], missingStages: string[], orphanLabels: string[], missingLabels: string[] }}
+ */
+export function inspectBoardHygiene({ boardStages = null, repoLabels = null } = {}) {
+  const canonical = STATUS_OPTIONS.map(s => s.name);
+  const known = new Set(canonical);
+  const unknownStages = boardStages ? boardStages.filter(s => !known.has(s)) : [];
+  const missingStages = boardStages ? canonical.filter(s => !boardStages.includes(s)) : [];
+
+  const knownLabels = new Set(ALL_LABELS.map(l => l.name));
+  const orphanLabels = repoLabels
+    ? repoLabels.filter(n => n.startsWith('spec-wave:') && !knownLabels.has(n))
+    : [];
+  const missingLabels = repoLabels
+    ? ALL_LABELS.map(l => l.name).filter(n => !repoLabels.includes(n))
+    : [];
+  return { unknownStages, missingStages, orphanLabels, missingLabels };
+}
+
+async function checkBoardHygiene(ctx) {
+  const name = 'Higiene do board e das labels';
+  const { cfg } = ctx;
+  if (!cfg?.project?.id) {
+    return { name, status: 'warn', detail: 'Sem project no config — verificação pulada.' };
+  }
+
+  let boardStages = null;
+  const snapshot = ctx.projectSnapshot;
+  if (snapshot?.fields?.['Etapa']?.options) {
+    boardStages = Object.keys(snapshot.fields['Etapa'].options);
+  } else if (cfg.project.fields?.['Etapa']?.options) {
+    // Sem snapshot (sem token/rede), o config é a melhor aproximação — foi nele
+    // que a coluna extra "📋 Backlog Técnico" ficou pendurada.
+    boardStages = Object.keys(cfg.project.fields['Etapa'].options);
+  }
+
+  let repoLabels = null;
+  if (ctx.token && cfg.owner && cfg.repo) {
+    try {
+      const res = await makeOctokit(ctx.token)
+        .paginate('GET /repos/{owner}/{repo}/labels', { owner: cfg.owner, repo: cfg.repo, per_page: 100 });
+      repoLabels = res.map(l => l.name);
+    } catch {
+      // labels não verificáveis agora — segue só com o board
+    }
+  }
+
+  const { unknownStages, missingStages, orphanLabels, missingLabels } =
+    inspectBoardHygiene({ boardStages, repoLabels });
+
+  const notes = [];
+  let status = 'ok';
+  if (boardStages) {
+    notes.push(`Etapas no board: ${boardStages.length}/${STATUS_OPTIONS.length} do RFC-001.`);
+  } else {
+    notes.push('Opções de Etapa não legíveis — verificação de colunas pulada.');
+  }
+  if (unknownStages.length > 0) {
+    status = 'warn';
+    notes.push(
+      `Colunas fora do fluxo canônico: ${unknownStages.join(', ')}. Um item nelas não tem ` +
+      'posição na ordem das etapas, e a garantia de "a Etapa nunca retrocede" não se aplica. ' +
+      'Mova os itens para uma etapa do fluxo e remova a coluna.'
+    );
+  }
+  if (missingStages.length > 0) {
+    status = 'warn';
+    notes.push(`Etapas do RFC-001 ausentes no board: ${missingStages.join(', ')} — rode \`refresh\`.`);
+  }
+  if (repoLabels) {
+    if (orphanLabels.length > 0) {
+      status = 'warn';
+      notes.push(
+        `Labels \`spec-wave:*\` descontinuadas ainda no repo: ${orphanLabels.join(', ')}. ` +
+        'Nenhum comando as honra — rode `npx @spec-wave/cli@latest update` para removê-las.'
+      );
+    }
+    if (missingLabels.length > 0) {
+      status = 'warn';
+      notes.push(`Labels do fluxo ausentes no repo: ${missingLabels.join(', ')} — rode \`update\`.`);
+    }
+    if (orphanLabels.length === 0 && missingLabels.length === 0) {
+      notes.push(`Labels: ${ALL_LABELS.length} do fluxo presentes, nenhuma descontinuada.`);
+    }
+  } else {
+    notes.push('Labels do repo não verificáveis agora (sem token ou sem acesso).');
+  }
+
+  return { name, status, detail: notes.join('\n') };
+}
+
 async function checkRepoAccess(ctx) {
   const name = 'Acesso ao repositório';
   const { cfg } = ctx;
@@ -307,9 +422,92 @@ async function checkAi(ctx) {
   const byAction = fileAi.maxTokensByAction && Object.keys(fileAi.maxTokensByAction).length > 0
     ? ` · por ação: ${Object.entries(fileAi.maxTokensByAction).map(([a, t]) => `${a}=${t}`).join(', ')}`
     : '';
-  notes.push(`Teto de saída: ${maxTokensNote}${byAction}.`);
+  const actionDefaults = Object.entries(MAX_TOKENS_BY_ACTION)
+    .filter(([a]) => !fileAi.maxTokensByAction?.[a] && !fileAi.maxTokens)
+    .map(([a, t]) => `${a}=${t} (default)`)
+    .join(', ');
+  notes.push(
+    `Teto de saída: ${maxTokensNote}${byAction}${actionDefaults ? ` · ${actionDefaults}` : ''}.`
+  );
 
   let status = 'ok';
+
+  // Escalada da crítica: sem escalationModel, a segunda tentativa apenas repete o
+  // MESMO modelo — a escalada existe no fluxo mas não muda nada.
+  const maxAttempts = Number.isInteger(fileAi.maxCritiqueAttempts) && fileAi.maxCritiqueAttempts > 0
+    ? fileAi.maxCritiqueAttempts
+    : DEFAULT_MAX_CRITIQUE_ATTEMPTS;
+  const critiqueModel = fileAi.models?.critique || model;
+  if (!fileAi.escalationModel) {
+    status = 'warn';
+    notes.push(
+      `Escalada da crítica: nenhuma (\`ai.escalationModel\` ausente) — na tentativa 2 a crítica ` +
+      `repete o mesmo modelo (\`${critiqueModel}\`). Teto: ${maxAttempts} tentativas → ` +
+      `label \`${LABEL_NEEDS_HUMAN}\`.`
+    );
+  } else if (fileAi.escalationModel === critiqueModel) {
+    status = 'warn';
+    notes.push(
+      `Escalada da crítica: \`ai.escalationModel\` é igual ao modelo da crítica ` +
+      `(\`${critiqueModel}\`) — escalar não troca de modelo. Teto: ${maxAttempts} tentativas.`
+    );
+  } else {
+    notes.push(
+      `Escalada da crítica: \`${fileAi.escalationModel}\` a partir da tentativa 2 · ` +
+      `teto de ${maxAttempts} tentativas → label \`${LABEL_NEEDS_HUMAN}\`.`
+    );
+  }
+  if (Number.isInteger(fileAi.maxCritiqueAttempts) === false && fileAi.maxCritiqueAttempts !== undefined) {
+    status = 'warn';
+    notes.push(
+      `\`ai.maxCritiqueAttempts\` = ${JSON.stringify(fileAi.maxCritiqueAttempts)} não é um inteiro ` +
+      `positivo — usando o default (${DEFAULT_MAX_CRITIQUE_ATTEMPTS}).`
+    );
+  }
+
+  // Apelidos de modelo por label (spec-wave:model:<apelido>).
+  const aliases = fileAi.modelAliases && Object.keys(fileAi.modelAliases).length > 0
+    ? fileAi.modelAliases
+    : null;
+  if (!aliases) {
+    notes.push(
+      `Apelidos de modelo: nenhum (\`ai.modelAliases\` ausente) — labels ` +
+      `\`${MODEL_LABEL_PREFIX}<apelido>\` serão ignoradas.`
+    );
+  } else {
+    notes.push(
+      `Apelidos de modelo (\`${MODEL_LABEL_PREFIX}<apelido>\`): ` +
+      `${Object.entries(aliases).map(([a, m]) => `${a}=${m}`).join(', ')}.`
+    );
+    // Slug da OpenRouter tem "/" (anthropic/claude-…); id da Anthropic, não.
+    const wrongShape = Object.entries(aliases).filter(([, m]) => (
+      provider.value === 'openrouter' ? !String(m).includes('/') : String(m).includes('/')
+    ));
+    if (wrongShape.length > 0) {
+      status = 'warn';
+      notes.push(
+        `Apelidos com formato incompatível com o provider ${provider.value}: ` +
+        `${wrongShape.map(([a, m]) => `${a}=${m}`).join(', ')}.`
+      );
+    }
+  }
+
+  // Saída estruturada da crítica: sem structured output confiável, a validação
+  // do schema queima os retries antes de falhar.
+  if (provider.value === 'openrouter' && !fileAi.models?.critique) {
+    status = 'warn';
+    notes.push(
+      `Saída estruturada da crítica: o provider é openrouter e \`ai.models.critique\` não está ` +
+      `definido — \`${model}\` pode não ser roteado para um endpoint com \`response_format\`, ` +
+      'e a crítica falha na primeira execução. Aponte `ai.models.critique` para um modelo com ' +
+      'saída estruturada.'
+    );
+  } else {
+    notes.push(
+      `Saída estruturada da crítica: ${provider.value === 'anthropic' ? 'tool call forçado' : 'response_format json_schema'} ` +
+      `· strict=${supportsStrictSchema(critiqueModel) ? 'sim' : 'não'} neste modelo.`
+    );
+  }
   if (process.env[provider.secret]) {
     notes.push(`${provider.secret} presente no ambiente local.`);
   } else {
@@ -377,7 +575,9 @@ export function checkSpecKit(ctx) {
 
 async function checkWorkflows(ctx) {
   const name = 'Workflows do Actions';
-  const dir = path.join(ctx.cwd, '.github', 'workflows');
+  // Ancorado na raiz do projeto, não no cwd: rodar o doctor de um subdiretório
+  // reportava ".github/workflows/ não encontrado" mesmo com tudo instalado.
+  const dir = path.join(ctx.root || ctx.cwd, '.github', 'workflows');
   if (!existsSync(dir)) {
     return {
       name,
@@ -394,7 +594,33 @@ async function checkWorkflows(ctx) {
       detail: `Workflows faltando em .github/workflows/: ${missing.join(', ')} — rode \`npx @spec-wave/cli@latest update\`.`,
     };
   }
-  return { name, status: 'ok', detail: `Os ${WORKFLOW_FILES.length} workflows do spec-wave estão presentes.` };
+
+  // Versão da CLI fixada nos workflows: um `@latest` deixa uma release mudar o
+  // comportamento de pipelines já em andamento.
+  const unpinned = [];
+  const otherVersion = [];
+  for (const file of WORKFLOW_FILES) {
+    const content = readFileSync(path.join(dir, file), 'utf-8');
+    if (/@spec-wave\/cli@latest/.test(content)) unpinned.push(file);
+    else if (!content.includes(`@spec-wave/cli@${CLI_VERSION}`)) otherVersion.push(file);
+  }
+  const notes = [`Os ${WORKFLOW_FILES.length} workflows do spec-wave estão presentes.`];
+  let status = 'ok';
+  if (unpinned.length > 0) {
+    status = 'warn';
+    notes.push(
+      `Chamando \`@spec-wave/cli@latest\` (sem versão fixada): ${unpinned.join(', ')}. ` +
+      'Uma release da CLI muda o comportamento de pipelines em andamento — rode `update`.'
+    );
+  }
+  if (otherVersion.length > 0) {
+    status = 'warn';
+    notes.push(
+      `Fixados em outra versão que não a ${CLI_VERSION}: ${otherVersion.join(', ')} — rode \`update\` ` +
+      'para fazer o bump explícito.'
+    );
+  }
+  return { name, status, detail: notes.join('\n') };
 }
 
 // ── Comando ─────────────────────────────────────────────────────────────────
@@ -404,11 +630,14 @@ export async function doctor() {
 
   // Contexto compartilhado entre os checks (token, config, resultados parciais).
   const ctx = { cwd: process.cwd() };
-  ctx.configPath = path.join(ctx.cwd, CONFIG_FILE);
+  // Procurado subindo na árvore: rodar o doctor de um subdiretório deve
+  // diagnosticar o repositório, não reportar "não inicializado".
+  ctx.configPath = findConfigPath(ctx.cwd);
+  ctx.root = ctx.configPath ? path.dirname(ctx.configPath) : null;
   ctx.cfg = null;
   ctx.cfgError = null;
   try {
-    if (existsSync(ctx.configPath)) {
+    if (ctx.configPath) {
       ctx.cfg = JSON.parse(readFileSync(ctx.configPath, 'utf-8'));
     }
   } catch (err) {
@@ -421,6 +650,7 @@ export async function doctor() {
     checkGhAccount,
     checkConfig,
     checkRepoAccess,
+    checkBoardHygiene,
     checkAi,
     checkSpecKit,
     checkWorkflows,

package/src/commands/generate-plan.mjs

@@ -1,13 +1,22 @@
 import { execSync } from 'node:child_process';
+import path from 'node:path';
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
-import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
+import {
+  getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
+} from '../api/github-rest.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE, LABEL_CRITIQUE_FAILED } from '../config.mjs';
+import {
+  allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE,
+  LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+} from '../config.mjs';
 import { generateDocument } from '../lib/claude.mjs';
-import { runCritique } from '../lib/critique.mjs';
+import {
+  runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
+} from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { loadConfig, resolveFromRoot } from '../lib/project-root.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 
 // Aviso anexado ao comentário quando o lint de idioma ainda reprova após o
@@ -41,9 +50,82 @@ Regras OBRIGATÓRIAS:
 - Forneça detalhes acionáveis: caminhos exatos de endpoints, nomes de DTOs, constraints de banco.
 - Responda APENAS com o conteúdo do plan.md, sem texto adicional.`;
 
+/**
+ * Roda a crítica do plan e aplica as labels de bloqueio.
+ *
+ * Extraída do fluxo principal por dois motivos:
+ *  • o `commentOnIssue` do resultado estava DENTRO do mesmo try do runCritique,
+ *    então uma falha ao comentar pulava o addLabel(critique-failed) e a crítica
+ *    grave deixava de bloquear em silêncio;
+ *  • a escalada de modelo e o teto de tentativas precisam do contador derivado
+ *    dos comentários da issue.
+ *
+ * Nunca lança: o plan já foi commitado e o humano precisa dele para corrigir.
+ */
+async function critiquePlan({
+  token, owner, repo, issueNumber, spec, plan, techContextYaml, labels, config, usage,
+}) {
+  if (labels.includes(LABEL_NEEDS_HUMAN)) {
+    console.log(`Crítica pulada: a issue tem a label ${LABEL_NEEDS_HUMAN} (revisão humana pendente).`);
+    return;
+  }
+
+  const maxAttempts = Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0
+    ? config.ai.maxCritiqueAttempts
+    : DEFAULT_MAX_CRITIQUE_ATTEMPTS;
+  const escalationModel = config?.ai?.escalationModel || null;
+
+  const comments = await listIssueComments(token, owner, repo, issueNumber).catch(err => {
+    console.warn(`Não foi possível listar comentários: ${err.message} — contador de tentativas em 1.`);
+    return [];
+  });
+  const { attempt, blocked } = resolveCritiqueAttempt({ comments, labels, kind: 'plan', maxAttempts });
+
+  if (blocked) {
+    console.log(`Teto de ${maxAttempts} tentativas de crítica atingido — exigindo revisão humana.`);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      renderNeedsHumanComment({ kind: 'plan', attempt, maxAttempts, escalationModel })).catch(() => {});
+    await addLabel(token, owner, repo, issueNumber, LABEL_NEEDS_HUMAN).catch(() => {});
+    return;
+  }
+
+  const model = attempt > 1 ? (escalationModel || undefined) : undefined;
+  if (model) console.log(`Tentativa ${attempt}: escalando a crítica para ${model}.`);
+
+  let critique;
+  try {
+    critique = await runCritique({
+      kind: 'plan', spec, plan, techContextYaml, attempt, maxAttempts, model, labels, usage,
+    });
+  } catch (err) {
+    console.warn(`Crítica adversarial não concluiu: ${err.message}`);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      `⚠️ **A crítica adversarial não concluiu** (erro abaixo) — o \`plan.md\` foi gerado, ` +
+      'mas **não foi auditado**. Revise-o com atenção extra.\n\n' +
+      `\`\`\`\n${err.message}\n\`\`\``
+    ).catch(() => {});
+    return;
+  }
+
+  // O comentário fica FORA do try da label: falhar ao comentar não pode impedir
+  // o bloqueio de uma crítica grave.
+  await commentOnIssue(token, owner, repo, issueNumber, critique.markdown)
+    .catch(err => console.warn(`Falha ao comentar a crítica: ${err.message}`));
+
+  if (critique.grave) {
+    await addLabel(token, owner, repo, issueNumber, LABEL_CRITIQUE_FAILED);
+    console.log(`Crítica adversarial apontou findings GRAVES — label ${LABEL_CRITIQUE_FAILED} aplicada.`);
+    return;
+  }
+  // Crítica limpa remove o bloqueio anterior — é isso que zera o contador de
+  // tentativas na rodada seguinte (ver resolveCritiqueAttempt).
+  await removeLabel(token, owner, repo, issueNumber, LABEL_CRITIQUE_FAILED).catch(() => {});
+}
+
 export async function generatePlan({ issueNumber }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { config, root } = loadConfig();
 
   if (!owner || !repo) {
     throw new Error(
@@ -58,6 +140,8 @@ export async function generatePlan({ issueNumber }) {
 
   // plan.md é artefato de Feature — não se aplica a Spike/RFC/Bug.
   const type = detectIssueType(issue);
+  // Alimentam o override de modelo por label (spec-wave:model:<apelido>).
+  const issueLabels = labelNames(issue);
   if (!allowsSpecPlan(type)) {
     console.log(`Issue #${issueNumber} é ${type}: plan.md não é gerado para ${SPEC_PLAN_EXCLUDED_TYPES.join('/')}.`);
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan');
@@ -70,11 +154,15 @@ export async function generatePlan({ issueNumber }) {
   }
 
   const slug = slugify(issue.title);
-  const featureDir = `docs/features/${slug}`;
-  const filePath = `${featureDir}/plan.md`;
+  // Caminho RELATIVO para links/commit; ABSOLUTO ancorado na raiz para o fs — o
+  // config é procurado subindo na árvore, e os documentos moram junto dele.
+  const featureRel = `docs/features/${slug}`;
+  const featureDir = resolveFromRoot(root, featureRel);
+  const filePath = path.join(featureDir, 'plan.md');
+  const fileRel = `${featureRel}/plan.md`;
 
   // Read existing spec.md if available (spec é gerada antes do plano)
-  const specPath = `${featureDir}/spec.md`;
+  const specPath = path.join(featureDir, 'spec.md');
   const specContent = existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null;
 
   // Tech context (RFC-002 §4): estático + dinâmico + override do corpo da issue.
@@ -100,6 +188,7 @@ export async function generatePlan({ issueNumber }) {
     console.log(`Gerando plan.md para: ${issue.title}`);
     const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
       action: 'plan',
+      labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
       withReport: true,
       usage: usageEntries,
@@ -124,36 +213,22 @@ export async function generatePlan({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **plan.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
       `Revise o plano e, quando estiver pronto, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\`` +
       formatLintWarning(lintFindings)
     );
 
     // Crítica adversarial: audita o plan recém-comitado contra spec +
-    // tech_context. NUNCA desfaz o plan — falha da crítica vira só um aviso.
-    try {
-      const critique = await runCritique({
-        kind: 'plan',
-        spec: specContent,
-        plan: content,
-        techContextYaml: tech.yaml,
-        usage: usageEntries,
-      });
-      await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10), critique.markdown);
-      if (critique.grave) {
-        await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_CRITIQUE_FAILED);
-        console.log(`Crítica adversarial apontou findings GRAVES — label ${LABEL_CRITIQUE_FAILED} aplicada.`);
-      }
-    } catch (err) {
-      console.warn(`Crítica adversarial indisponível: ${err.message}`);
-      await commentOnIssue(
-        token, owner, repo, parseInt(issueNumber, 10),
-        `⚠️ crítica adversarial indisponível (erro: ${err.message})`
-      ).catch(() => {});
-    }
-
-    console.log(`plan.md criado em: ${filePath}`);
+    // tech_context. NUNCA desfaz o plan — falha da crítica vira só um aviso, e o
+    // humano segue com a ferramenta que precisa para corrigir.
+    await critiquePlan({
+      token, owner, repo, issueNumber: parseInt(issueNumber, 10),
+      spec: specContent, plan: content, techContextYaml: tech.yaml,
+      labels: issueLabels, config, usage: usageEntries,
+    });
+
+    console.log(`plan.md criado em: ${fileRel}`);
   } catch (err) {
     // Mesmo beco sem saída do generate-spec: o gatilho é `issues: [labeled]`,
     // então com a label ainda aplicada re-adicioná-la não dispara nada. Remove

package/src/commands/generate-spec.mjs

@@ -1,12 +1,16 @@
 import { execSync } from 'node:child_process';
+import path from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { loadConfig, resolveFromRoot } from '../lib/project-root.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE } from '../config.mjs';
+import {
+  allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE, labelNames,
+} from '../config.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).
@@ -44,6 +48,7 @@ Regras:
 export async function generateSpec({ issueNumber }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { root } = loadConfig();
 
   if (!owner || !repo) {
     throw new Error(
@@ -59,6 +64,8 @@ export async function generateSpec({ issueNumber }) {
   // spec.md/plan.md são artefatos funcionais de Feature — não se aplicam a
   // Spike/RFC/Bug. Pula a geração, remove o trigger e avisa na issue.
   const type = detectIssueType(issue);
+  // Alimentam o override de modelo por label (spec-wave:model:<apelido>).
+  const issueLabels = labelNames(issue);
   if (!allowsSpecPlan(type)) {
     console.log(`Issue #${issueNumber} é ${type}: spec.md não é gerada para ${SPEC_PLAN_EXCLUDED_TYPES.join('/')}.`);
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
@@ -71,8 +78,12 @@ export async function generateSpec({ issueNumber }) {
   }
 
   const slug = slugify(issue.title);
-  const featureDir = `docs/features/${slug}`;
-  const filePath = `${featureDir}/spec.md`;
+  // Caminho RELATIVO para links/commit; ABSOLUTO ancorado na raiz para o fs — o
+  // config é procurado subindo na árvore, e os documentos moram junto dele.
+  const featureRel = `docs/features/${slug}`;
+  const featureDir = resolveFromRoot(root, featureRel);
+  const filePath = path.join(featureDir, 'spec.md');
+  const fileRel = `${featureRel}/spec.md`;
 
   // Payload estruturado (RFC-002 §5.1): metadata + entrada de negócio.
   const payload = {
@@ -94,6 +105,7 @@ export async function generateSpec({ issueNumber }) {
     console.log(`Gerando spec.md para: ${issue.title}`);
     const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
       action: 'spec',
+      labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
       withReport: true,
       usage: usageEntries,
@@ -118,13 +130,13 @@ export async function generateSpec({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **spec.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
       `Revise a especificação e, quando estiver pronto, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:plan"\n\`\`\`` +
       formatLintWarning(lintFindings)
     );
 
-    console.log(`spec.md criado em: ${filePath}`);
+    console.log(`spec.md criado em: ${fileRel}`);
   } catch (err) {
     // Sem isto a label de gatilho fica aplicada — e como o workflow dispara em
     // `issues: [labeled]`, re-adicionar uma label já presente não emite evento: