@spec-wave/cli 0.12.0 → 0.14.0

package/src/commands/validate.mjs

@@ -3,76 +3,85 @@ import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { resolveDoc } from '../lib/feature-docs.mjs';
-import { CONFIG_FILE, LABEL_CRITIQUE_FAILED, REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
+import {
+  CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN,
+  REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, labelNames,
+} from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
 
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  let cfg = {};
-  try { if (existsSync(configPath)) cfg = JSON.parse(readFileSync(configPath, 'utf-8')); } catch {}
-  const owner = envOwner || cfg.owner;
-  const repo = envRepo || cfg.repo;
+  const { config: cfg, root } = loadConfig();
+  const owner = envOwner || cfg?.owner;
+  const repo = envRepo || cfg?.repo;
 
   if (!owner || !repo) {
     throw new Error(
       'Não foi possível determinar owner/repo.\n' +
-      'Defina GITHUB_REPOSITORY=owner/repo ou rode o comando dentro de um repositório com .spec-wave.json.'
+      `Defina GITHUB_REPOSITORY=owner/repo ou rode o comando dentro de um repositório com ${CONFIG_FILE}.`
     );
   }
 
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
   const slug = slugify(issue.title);
-  const featureDir = `docs/features/${slug}`;
+  // Ancorado na RAIZ do repo, não no cwd: rodar de um subdiretório encontra o
+  // config subindo na árvore e precisa encontrar os documentos no mesmo lugar.
+  const featureRel = `docs/features/${slug}`;
+  const featureDir = path.resolve(root || process.cwd(), featureRel);
 
   const errors = [];
 
   // Bloqueio da crítica adversarial: enquanto a label critique-failed estiver
   // na issue, o ready não é liberado — a correção dos documentos é manual.
-  const labelNames = (issue.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
-  const critiqueFailed = labelNames.includes(LABEL_CRITIQUE_FAILED);
+  const names = labelNames(issue);
+  const critiqueFailed = names.includes(LABEL_CRITIQUE_FAILED);
+  const needsHuman = names.includes(LABEL_NEEDS_HUMAN);
   if (critiqueFailed) {
     errors.push(
       '🔎 A crítica adversarial apontou contradições GRAVES (veja o comentário na issue). ' +
       `Corrija os documentos e remova a label \`${LABEL_CRITIQUE_FAILED}\` para liberar o ready.`
     );
   }
+  if (needsHuman) {
+    errors.push(
+      `🛑 A crítica reprovou repetidas vezes e a label \`${LABEL_NEEDS_HUMAN}\` foi aplicada. ` +
+      'Uma pessoa precisa revisar os documentos e remover a label para liberar o ready.'
+    );
+  }
 
-  // Valida sempre o documento ATUAL de cada tipo — com regerações forçadas a
-  // versão vigente é a maior (plan-v2.md, plan-v3.md…), não o plan.md original.
-  const plan = resolveDoc(featureDir, 'plan');
-  const planPath = plan?.path || `${featureDir}/plan.md`;
-  if (!plan) {
-    errors.push('❌ `plan.md` não encontrado em `' + planPath + '`');
+  // Check plan.md
+  const planPath = path.join(featureDir, 'plan.md');
+  if (!existsSync(planPath)) {
+    errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
   } else {
-    const planContent = readFileSync(plan.path, 'utf-8');
+    const planContent = readFileSync(planPath, 'utf-8');
     for (const section of REQUIRED_PLAN_SECTIONS) {
       if (!planContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no plano (v${plan.version}): **${section}**`);
+        errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
       }
     }
     for (const problem of findIncompleteDocSigns(planContent)) {
-      errors.push(`❌ \`${planPath}\` parece incompleto: ${problem}`);
+      errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
     }
   }
 
-  const spec = resolveDoc(featureDir, 'spec');
-  const specPath = spec?.path || `${featureDir}/spec.md`;
-  if (!spec) {
-    errors.push('❌ `spec.md` não encontrado em `' + specPath + '`');
+  // Check spec.md
+  const specPath = path.join(featureDir, 'spec.md');
+  if (!existsSync(specPath)) {
+    errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
   } else {
-    const specContent = readFileSync(spec.path, 'utf-8');
+    const specContent = readFileSync(specPath, 'utf-8');
     for (const section of REQUIRED_SPEC_SECTIONS) {
       if (!specContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente na spec (v${spec.version}): **${section}**`);
+        errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
       }
     }
     // Seções presentes não garantem documento completo: um corte dentro da
     // última seção passa na checagem acima (foi o caso da EP2-F13).
     for (const problem of findIncompleteDocSigns(specContent)) {
-      errors.push(`❌ \`${specPath}\` parece incompleto: ${problem}`);
+      errors.push(`❌ \`spec.md\` parece incompleto: ${problem}`);
     }
   }
 
@@ -86,11 +95,13 @@ export async function validate({ issueNumber }) {
       errors.join('\n') +
       `\n\nCorreija os problemas e adicione novamente a label \`spec-wave:ready\`.`
     );
-    // Quando a ÚNICA falha é a da crítica adversarial, os documentos existem e
-    // estão estruturalmente válidos — só precisam de correção manual. Nesse
-    // caso NÃO devolvemos a feature para a etapa de spec (spec-wave:spec).
-    const onlyCritiqueFailed = critiqueFailed && errors.length === 1;
-    if (!onlyCritiqueFailed) {
+    // Quando as ÚNICAS falhas são os portões humanos (crítica grave / revisão
+    // exigida), os documentos existem e estão estruturalmente válidos — só
+    // precisam de correção manual. Nesse caso NÃO devolvemos a feature para a
+    // etapa de spec (spec-wave:spec).
+    const humanGates = (critiqueFailed ? 1 : 0) + (needsHuman ? 1 : 0);
+    const onlyHumanGates = humanGates > 0 && errors.length === humanGates;
+    if (!onlyHumanGates) {
       // Send back to spec stage
       await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
     }
@@ -104,9 +115,10 @@ export async function validate({ issueNumber }) {
   await commentOnIssue(
     token, owner, repo, parseInt(issueNumber, 10),
     `✅ **Validação concluída com sucesso!**\n\n` +
-    `- [\`${specPath}\`](${specPath}) ✓\n` +
-    `- [\`${planPath}\`](${planPath}) ✓\n\n` +
-    `A Feature está pronta para decomposição. Use:\n` +
+    `- [\`${featureRel}/spec.md\`](${featureRel}/spec.md) ✓\n` +
+    `- [\`${featureRel}/plan.md\`](${featureRel}/plan.md) ✓\n\n` +
+    `A Feature está pronta para a decomposição. O próximo passo gera o **rascunho** ` +
+    `em \`${featureRel}/decomposition.md\` para revisão (nada é criado ainda):\n` +
     `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:decompose"\n\`\`\``
   );
 

package/src/config.mjs

@@ -37,6 +37,17 @@ export const DEFAULT_PROVIDER = 'anthropic';
 // por resolveAiConfig() em src/lib/claude.mjs.
 export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique'];
 
+// Override de modelo POR EXECUÇÃO: a label `spec-wave:model:<apelido>` na issue
+// aponta para uma entrada de `ai.modelAliases` do .spec-wave.json. Serve para
+// reprocessar um caso difícil num modelo mais forte sem editar a configuração do
+// repositório inteiro. Resolvido por resolveModelLabel() em src/lib/claude.mjs.
+export const MODEL_LABEL_PREFIX = 'spec-wave:model:';
+
+// Quantas críticas seguidas podem reprovar a mesma issue antes de exigir revisão
+// humana. Na última tentativa a IA NÃO é chamada: o fluxo aplica
+// `spec-wave:needs-human` e para. Ajustável por `ai.maxCritiqueAttempts`.
+export const DEFAULT_MAX_CRITIQUE_ATTEMPTS = 3;
+
 // Idioma-alvo de todos os documentos gerados por IA (spec/plan/decompose/critique).
 // Usado pelo lint de saída (src/lib/output-lint.mjs) para detectar vazamento
 // de caracteres de outros alfabetos.
@@ -180,27 +191,50 @@ export const PRIORITY_LABELS = [
   { name: 'P3', color: 'EDEDED', description: 'Baixa'    },
 ];
 
+// Labels de gatilho do fluxo de decomposição. São DUAS etapas: `:decompose`
+// gera (ou re-critica) o rascunho em decomposition.md sem criar nada, e
+// `:decompose-apply` cria as Stories/Tasks a partir do rascunho já revisado.
+// A separação existe porque a crítica precisa de um artefato ESTÁVEL para
+// apontar ("Story 3", "Task 3.2") e o humano precisa de um arquivo para corrigir.
+export const LABEL_DECOMPOSE = 'spec-wave:decompose';
+export const LABEL_DECOMPOSE_APPLY = 'spec-wave:decompose-apply';
+
 // Labels de estado gravadas pelas automações (não são gatilhos do usuário).
 export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
-// Modificador (não é gatilho — sozinha não dispara workflow nenhum): quando
-// presente junto de uma label de gatilho, manda o comando re-executar a etapa
-// ignorando os guards. É consumida (removida) pelo run que a leu.
-export const LABEL_FORCE = 'spec-wave:force';
+export const LABEL_DECOMPOSE_READY = 'spec-wave:decompose-ready';
+export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
 
 export const TRIGGER_LABELS = [
   { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
   { name: 'spec-wave:plan',          color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
   { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
   { name: 'spec-wave:plan-approved', color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
-  { name: 'spec-wave:decompose',     color: 'BFD4F2', description: 'Decompor em Stories e Tasks'          },
+  { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
+  { name: LABEL_DECOMPOSE_APPLY,     color: 'BFD4F2', description: 'Aplicar o decomposition.md revisado: criar Stories e Tasks' },
+  { name: LABEL_DECOMPOSE_READY,     color: '0E8A16', description: 'Rascunho de decomposição pronto para revisão humana' },
   { name: LABEL_CRITIQUE_FAILED,     color: 'B60205', description: 'Crítica adversarial apontou contradições graves' },
+  { name: LABEL_NEEDS_HUMAN,         color: 'B60205', description: 'Crítica reprovou N vezes seguidas — precisa de revisão humana' },
   { name: LABEL_DECOMPOSED,          color: 'EDEDED', description: 'Feature já decomposta em Stories e Tasks' },
-  { name: LABEL_FORCE,               color: 'D93F0B', description: 'Re-executa a etapa ignorando os guards (consumida no run)' },
 ];
 
 export const ALL_LABELS = [...TYPE_LABELS, ...PRIORITY_LABELS, ...TRIGGER_LABELS];
 
+/**
+ * Nomes das labels de uma issue (função PURA).
+ *
+ * A REST devolve `labels` como array de objetos `{name}`, mas partes do fluxo
+ * (e os testes) passam strings — este helper aceita os dois, e também a issue
+ * inteira, porque a maioria dos chamadores já tem a issue em mão.
+ *
+ * @param {object|Array<string|{name:string}>} issueOrLabels issue ou array de labels
+ * @returns {string[]} nomes, sem entradas vazias
+ */
+export function labelNames(issueOrLabels) {
+  const labels = Array.isArray(issueOrLabels) ? issueOrLabels : (issueOrLabels?.labels || []);
+  return labels.map(l => (typeof l === 'string' ? l : l?.name)).filter(Boolean);
+}
+
 export const WORKFLOW_FILES = [
   'generate-plan.yml',
   'generate-spec.yml',

package/src/lib/board.mjs

@@ -1,35 +1,29 @@
 // Helpers compartilhados de manipulação do board (GitHub Projects v2).
 // Extraídos de code-review.mjs/qa.mjs para uso também pelos comandos de CLI
 // (task/story/order). Ver a distinção Etapa × Status em config.mjs.
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { addProjectItem, setItemSingleSelect, getSingleSelectField, getItemSingleSelectValue } from '../api/github-graphql.mjs';
-import { CONFIG_FILE, STAGE_ORDER } from '../config.mjs';
+import { CONFIG_FILE, STAGE_ORDER, STATUS_OPTIONS } from '../config.mjs';
+import { loadConfig } from './project-root.mjs';
 
 /**
- * Carrega o bloco `project` do .spec-wave.json do diretório atual.
+ * Carrega o bloco `project` do .spec-wave.json, procurando-o a partir de `cwd`
+ * e subindo na árvore (ver src/lib/project-root.mjs).
  *
  * @param {object} [opts]
- * @param {string} [opts.cwd=process.cwd()] diretório onde procurar o config
- * @returns {{ project: object|null, error: string|null }} project = bloco com
- *          id/fields; error = motivo legível quando project é null (compõe os
- *          avisos "… — board não atualizado." dos chamadores).
+ * @param {string} [opts.cwd=process.cwd()] diretório onde começar a busca
+ * @returns {{ project: object|null, root: string|null, error: string|null }}
+ *          project = bloco com id/fields; root = diretório do config;
+ *          error = motivo legível quando project é null (compõe os avisos
+ *          "… — board não atualizado." dos chamadores).
  */
 export function loadProjectConfig({ cwd = process.cwd() } = {}) {
-  const configPath = path.join(cwd, CONFIG_FILE);
-  if (!existsSync(configPath)) {
-    return { project: null, error: `${CONFIG_FILE} não encontrado` };
-  }
-  let project;
-  try {
-    project = JSON.parse(readFileSync(configPath, 'utf-8')).project || {};
-  } catch (err) {
-    return { project: null, error: `${CONFIG_FILE} corrompido (${err.message})` };
-  }
+  const { config, root, error } = loadConfig(cwd);
+  if (error) return { project: null, root, error };
+  const project = config.project || {};
   if (!project.id) {
-    return { project: null, error: `Project não configurado em ${CONFIG_FILE}` };
+    return { project: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
   }
-  return { project, error: null };
+  return { project, root, error: null };
 }
 
 /**
@@ -50,6 +44,78 @@ export async function resolveField(token, project, name) {
   return await getSingleSelectField(token, project.id, name);
 }
 
+/**
+ * A Etapa pode avançar de `current` para `target`? (função PURA — testável).
+ *
+ * Regra do board: a Etapa só AVANÇA. Três casos param o movimento:
+ *  • já está no destino ou adiante na ordem canônica;
+ *  • a etapa ATUAL não está em STAGE_ORDER (coluna criada à mão no board, ou
+ *    resíduo de uma versão anterior do config). Antes esse caso caía no
+ *    `curIdx === -1` e DESLIGAVA o guard, permitindo retrocesso — sem saber onde
+ *    o item está na ordem, o certo é não mexer;
+ *  • a etapa de DESTINO não está em STAGE_ORDER (nome inválido).
+ *
+ * @param {string|null} current etapa atual do item (null = ainda sem etapa)
+ * @param {string} target etapa de destino
+ * @returns {boolean} true se deve escrever a nova Etapa
+ */
+export function shouldAdvanceStage(current, target) {
+  const tgtIdx = STAGE_ORDER.indexOf(target);
+  if (tgtIdx === -1) return false;
+  if (!current) return true; // item ainda sem Etapa definida
+  const curIdx = STAGE_ORDER.indexOf(current);
+  if (curIdx === -1) return false; // etapa atual desconhecida — não arrisca retroceder
+  return curIdx < tgtIdx;
+}
+
+// Normaliza para comparação: sem emoji/pontuação, minúsculo, espaços colapsados.
+// "👀 Code Review" e "code review" precisam casar.
+function stageKey(value) {
+  return String(value ?? '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')            // acentos (após NFD)
+    .replace(/[^\p{Letter}\p{Number}]+/gu, ' ') // emoji e pontuação
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * Resolve o nome canônico de uma Etapa a partir de entrada humana (função PURA).
+ *
+ * Aceita o nome com ou sem emoji, com qualquer caixa e sem acento
+ * ("code review", "Homologacao", "🚧 Desenvolvimento"). Casa primeiro exato,
+ * depois por prefixo; prefixo que casa com mais de uma etapa é AMBÍGUO e vira
+ * erro listando as candidatas — melhor recusar que mover para a coluna errada.
+ *
+ * @param {string} input entrada do usuário
+ * @returns {{ stage: string|null, error: string|null }}
+ */
+export function resolveStageName(input) {
+  const key = stageKey(input);
+  const options = STATUS_OPTIONS.map(s => ({ name: s.name, key: stageKey(s.name) }));
+  const list = () => STATUS_OPTIONS.map(s => `"${s.name}"`).join(', ');
+
+  if (!key) {
+    return { stage: null, error: `Etapa não informada. Use uma destas: ${list()}.` };
+  }
+
+  const exact = options.find(o => o.key === key);
+  if (exact) return { stage: exact.name, error: null };
+
+  const partial = options.filter(o => o.key.startsWith(key));
+  if (partial.length === 1) return { stage: partial[0].name, error: null };
+  if (partial.length > 1) {
+    return {
+      stage: null,
+      error:
+        `Etapa "${input}" é ambígua — casa com ${partial.map(o => `"${o.name}"`).join(' e ')}. ` +
+        'Seja mais específico.',
+    };
+  }
+
+  return { stage: null, error: `Etapa "${input}" não existe. Use uma destas: ${list()}.` };
+}
+
 /**
  * Avança um item do board para `targetStage` (Etapa) e define o Status para
  * `targetStatus`. Uma issue só AVANÇA: se já estiver em `targetStage` ou em uma
@@ -68,13 +134,9 @@ export async function advanceToStage(token, project, etapaField, statusField, no
   const itemId = await addProjectItem(token, project.id, nodeId);
 
   if (etapaField?.id && targetStage) {
-    // Nunca retroceder: compara a etapa atual com a de destino na ordem canônica.
+    // Nunca retroceder — a decisão vive em shouldAdvanceStage (pura, testada).
     const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
-    const curIdx = current ? STAGE_ORDER.indexOf(current) : -1;
-    const tgtIdx = STAGE_ORDER.indexOf(targetStage);
-    if (curIdx !== -1 && tgtIdx !== -1 && curIdx >= tgtIdx) {
-      return false; // já está nessa etapa ou adiante — não retrocede
-    }
+    if (!shouldAdvanceStage(current, targetStage)) return false;
     const optionId = etapaField.options?.[targetStage];
     if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
   }