@spec-wave/cli 0.6.0 → 0.7.0

package/src/commands/implement.mjs

@@ -8,10 +8,12 @@ import {
   CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE,
   PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
 } from '../config.mjs';
-import { getIssue } from '../api/github-rest.mjs';
+import { getIssue, listIssueComments, listBlockedBy } from '../api/github-rest.mjs';
 import { listSubIssues, getIssueParent } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { parseDependencies } from '../lib/dependencies.mjs';
+import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
 
 // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
 const WORK_DIR = '.spec-wave';
@@ -46,7 +48,10 @@ function readSpecPlan(featureDir) {
 }
 
 // Monta o markdown de contexto que será entregue ao spec-kit implement.
-function buildContext({ type, issue, tasks, feature, siblingStories = [], spec, plan, specPath, planPath }) {
+function buildContext({
+  type, issue, tasks, feature, siblingStories = [], spec, plan, specPath, planPath,
+  comments = [], codeDigest = null, blockedByWarnings = [],
+}) {
   const lines = [];
   lines.push(`# Contexto de implementação — ${type} #${issue.number}`);
   lines.push('');
@@ -56,6 +61,19 @@ function buildContext({ type, issue, tasks, feature, siblingStories = [], spec,
     lines.push(issue.body.trim());
   }
 
+  // Dependências ainda abertas — logo após o cabeçalho, para máxima visibilidade.
+  if (blockedByWarnings.length > 0) {
+    lines.push('');
+    lines.push('## ⚠️ Dependências pendentes');
+    lines.push('');
+    for (const w of blockedByWarnings) lines.push(`- ${w}`);
+    lines.push('');
+    lines.push(
+      '**Implemente somente se tiver certeza de que a dependência não é bloqueante; ' +
+      'caso contrário, pare e reporte.**'
+    );
+  }
+
   // Modelo do board: "Etapa" (coluna do kanban) = DIREÇÃO, só avança; "Status"
   // (Todo/In Progress/Done) = PROGRESSO dentro da etapa. O desenvolvimento de
   // cada Task acontece na Etapa Desenvolvimento (Status In Progress); ao concluir,
@@ -120,6 +138,42 @@ function buildContext({ type, issue, tasks, feature, siblingStories = [], spec,
     if (t.body && t.body.trim()) lines.push(t.body.trim());
   });
 
+  // Comentários das issues — é onde vivem as revisões/correções feitas depois
+  // que spec/plan/stories foram escritos; em conflito, o comentário vence.
+  if (comments.length > 0) {
+    lines.push('');
+    lines.push('## Comentários das issues (revisões e correções)');
+    lines.push('');
+    lines.push(
+      '> Comentários frequentemente **corrigem ou substituem** instruções dos documentos ' +
+      'acima — em caso de conflito, o comentário mais recente prevalece.'
+    );
+    for (const group of comments) {
+      lines.push('');
+      lines.push(`### Comentários da ${group.kind} #${group.issueNumber}`);
+      if (group.total > group.items.length) {
+        lines.push('');
+        lines.push(`_(mostrando os ${group.items.length} mais recentes de ${group.total})_`);
+      }
+      for (const c of group.items) {
+        lines.push('');
+        lines.push(`**${c.author || 'desconhecido'}** (${c.createdAt}):`);
+        lines.push('');
+        lines.push(c.body.trim());
+      }
+    }
+  }
+
+  // Estado atual do código — evita reimplementar módulos que já existem.
+  if (codeDigest) {
+    lines.push('');
+    lines.push('## Estado atual do código');
+    lines.push('');
+    lines.push('> **NÃO reimplemente o que já existe; estenda os módulos listados abaixo.**');
+    lines.push('');
+    lines.push(codeDigest.trim());
+  }
+
   if (spec) {
     lines.push('');
     lines.push(`## spec.md (${specPath})`);
@@ -241,8 +295,69 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
       .map(s => ({ number: s.number, title: s.title }));
   }
 
+  // 4c. Comentários das issues (best-effort) — revisões e correções vivem nos
+  // comentários, não no body; sem eles o agente implementa instruções já
+  // corrigidas. Feature primeiro (correções de escopo), depois a issue-alvo.
+  const MAX_COMMENTS_PER_ISSUE = 15;
+  const MAX_COMMENT_CHARS = 2000;
+  const comments = [];
+  const commentSources = [];
+  if (feature && feature.number !== issue.number) {
+    commentSources.push({ number: feature.number, kind: 'Feature' });
+  }
+  commentSources.push({ number: issue.number, kind: type });
+  for (const src of commentSources) {
+    const all = await listIssueComments(token, owner, repo, src.number).catch(() => []);
+    if (all.length === 0) continue;
+    const items = all.slice(-MAX_COMMENTS_PER_ISSUE).map(c => ({
+      ...c,
+      body: c.body.length > MAX_COMMENT_CHARS
+        ? `${c.body.slice(0, MAX_COMMENT_CHARS)}…[truncado]`
+        : c.body,
+    }));
+    comments.push({ issueNumber: src.number, kind: src.kind, total: all.length, items });
+  }
+
+  // 4d. Digest do estado do código (best-effort) — commits desde a criação da
+  // Feature + árvore dos módulos citados no plan, para o agente estender o que
+  // já existe em vez de reimplementar.
+  let codeDigest = null;
+  try {
+    let sinceIso = issue.created_at || null;
+    if (feature?.number) {
+      const featureIssue = await getIssue(token, owner, repo, feature.number).catch(() => null);
+      if (featureIssue?.created_at) sinceIso = featureIssue.created_at;
+    }
+    const paths = specPlan.plan ? extractPathsFromPlan(specPlan.plan) : [];
+    codeDigest = await buildCodeDigest({ sinceIso, paths });
+  } catch {
+    codeDigest = null;
+  }
+
+  // 4e. Dependências pendentes (best-effort) — une a linha "Depende de:" do
+  // body com a relação nativa blocked_by do GitHub; considera pendente toda
+  // dependência ainda não fechada.
+  const blockedByWarnings = [];
+  try {
+    const depNumbers = new Set(parseDependencies(issue.body));
+    const blocked = await listBlockedBy(token, owner, repo, issue.number).catch(() => []);
+    for (const b of blocked) depNumbers.add(b.number);
+    for (const depNumber of [...depNumbers].sort((a, b) => a - b)) {
+      const dep = await getIssue(token, owner, repo, depNumber).catch(() => null);
+      if (!dep || dep.state === 'closed') continue;
+      const warning =
+        `${type} #${issue.number} depende de #${depNumber} («${dep.title}»), ` +
+        `que ainda não está concluída (state: ${dep.state}).`;
+      blockedByWarnings.push(warning);
+      p.log.warn(warning);
+    }
+  } catch { /* aviso é best-effort — segue sem ele */ }
+
   // 5. Monta e grava o arquivo de contexto.
-  const context = buildContext({ type, issue, tasks, feature, siblingStories, ...specPlan });
+  const context = buildContext({
+    type, issue, tasks, feature, siblingStories, ...specPlan,
+    comments, codeDigest, blockedByWarnings,
+  });
   mkdirSync(WORK_DIR, { recursive: true });
   const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
   writeFileSync(tasksFile, context);

package/src/commands/init.mjs

@@ -9,7 +9,7 @@ import { setupProject } from '../setup/project.mjs';
 import { setupLabels } from '../setup/labels.mjs';
 import { setupFiles } from '../setup/files.mjs';
 import { getFileContent } from '../api/github-rest.mjs';
-import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL } from '../config.mjs';
+import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES } from '../config.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
@@ -160,7 +160,7 @@ export async function init(options) {
     filesSpinner.start('Criando arquivos no repositório...');
     try {
       await setupFiles(token, owner, repo, filesSpinner);
-      filesSpinner.stop('Arquivos criados (4 workflows + 2 issue templates)');
+      filesSpinner.stop(`Arquivos criados (${WORKFLOW_FILES.length} workflows + ${ISSUE_TEMPLATE_FILES.length} issue templates)`);
     } catch (err) {
       filesSpinner.stop('');
       p.log.error(`Erro ao criar arquivos: ${err.message}`);

package/src/commands/order.mjs

@@ -0,0 +1,172 @@
+// Ordena as Stories de uma Feature pelas dependências (topológica, Kahn —
+// ver orderStories em src/lib/dependencies.mjs). As dependências vêm de duas
+// fontes, mescladas: a linha "Depende de: #N" no corpo da Story e a relação
+// nativa blocked_by do GitHub.
+//
+// Comando LOCAL — rodado pelo dev no terminal. owner/repo vêm da env
+// GITHUB_REPOSITORY quando existir, senão do .spec-wave.json (gravado pelo init).
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue, listBlockedBy } from '../api/github-rest.mjs';
+import { addProjectItem, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
+import { loadProjectConfig, resolveField } from '../lib/board.mjs';
+import { CONFIG_FILE, STAGE_ORDER, STAGE_DEVELOPMENT, STAGE_DONE } from '../config.mjs';
+
+// Resolve owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
+// fallback no .spec-wave.json — comandos locais rodam sem essa env.
+function resolveRepoContext() {
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  let cfg = {};
+  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
+  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
+  return { owner: envOwner || cfg.owner, repo: envRepo || cfg.repo };
+}
+
+export async function order({ feature: featureArg }) {
+  const featureNumber = parseInt(String(featureArg).replace('#', ''), 10);
+  if (!Number.isInteger(featureNumber) || featureNumber <= 0) {
+    p.log.error(`Feature inválida: "${featureArg}". Use o número da issue, ex.: 12 ou #12.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { owner, repo } = resolveRepoContext();
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`) ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(`spec-wave order #${featureNumber}`));
+
+  // 1. Lê a Feature e valida o tipo.
+  let featureIssue;
+  try {
+    featureIssue = await getIssue(token, owner, repo, featureNumber);
+  } catch (err) {
+    p.log.error(`Não foi possível ler a issue #${featureNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const type = detectIssueType(featureIssue);
+  if (type !== 'Feature') {
+    p.log.error(
+      `\`spec-wave order\` só aceita issues do tipo Feature. ` +
+      `Issue #${featureNumber} é do tipo ${type || 'desconhecido'} (${featureIssue.title}).`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Sub-issues da Feature → só as Stories entram na ordenação.
+  let subs;
+  try {
+    subs = await listSubIssues(token, featureIssue.node_id);
+  } catch (err) {
+    p.log.error(`Não foi possível listar as sub-issues da Feature #${featureNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const stories = subs.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+  if (stories.length === 0) {
+    p.log.info(`Feature #${featureNumber} não tem Stories (sub-issues) — nada a ordenar. Rode \`spec-wave decompose\` antes.`);
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  // 3. Dependências de cada Story: linha "Depende de: #N" do corpo (buscando o
+  // corpo via getIssue quando listSubIssues não o trouxer) mesclada com a
+  // relação nativa blocked_by (falha na API → sem bloqueios, não interrompe).
+  const enriched = await Promise.all(stories.map(async (s) => {
+    let body = s.body;
+    if (!body) {
+      body = (await getIssue(token, owner, repo, s.number).catch(() => null))?.body || '';
+    }
+    const fromBody = parseDependencies(body);
+    const fromBlockedBy = (await listBlockedBy(token, owner, repo, s.number).catch(() => []))
+      .map(b => b.number);
+    const dependsOn = [...new Set([...fromBody, ...fromBlockedBy])];
+    return { number: s.number, title: s.title, nodeId: s.nodeId, dependsOn };
+  }));
+
+  // 4. Etapa atual de cada Story no board (falha em qualquer leitura → '—').
+  const stageOf = new Map();
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) {
+    p.log.warn(`${projectError} — Etapas do board não consultadas.`);
+  } else {
+    const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+    if (etapaField?.id) {
+      await Promise.all(enriched.map(async (s) => {
+        try {
+          const itemId = await addProjectItem(token, project.id, s.nodeId);
+          stageOf.set(s.number, await getItemSingleSelectValue(token, itemId, etapaField.id));
+        } catch {
+          stageOf.set(s.number, null);
+        }
+      }));
+    }
+  }
+
+  // 5. Ordenação topológica (nunca lança; ciclo vem em `cycle`).
+  const byNumber = new Map(enriched.map(s => [s.number, s]));
+  const { order: sorted, cycle } = orderStories(enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+
+  if (cycle.length > 0) {
+    p.log.warn(
+      chalk.yellow.bold('⚠ CICLO DE DEPENDÊNCIAS detectado!') + '\n' +
+      `Stories envolvidas (ou bloqueadas pelo ciclo): ${cycle.map(n => `#${n}`).join(', ')}.\n` +
+      'Elas ficaram fora da ordem abaixo — corrija as linhas "Depende de" (ou as relações blocked_by) dessas issues.'
+    );
+  }
+
+  const line = (n, i) => {
+    const s = byNumber.get(n);
+    const stage = stageOf.get(n) || '—';
+    const deps = s.dependsOn.length > 0
+      ? `  ${chalk.dim(`← depende de ${s.dependsOn.map(d => `#${d}`).join(', ')}`)}`
+      : '';
+    return `${String(i + 1).padStart(2)}. #${n} ${s.title}\n    Etapa: ${stage}${deps}`;
+  };
+  p.note(sorted.map(line).join('\n'), `Ordem de execução das Stories da Feature #${featureNumber}`);
+
+  // 6. Aviso final: dependente já em Desenvolvimento+ com dependência não-Done.
+  const devIdx = STAGE_ORDER.indexOf(STAGE_DEVELOPMENT);
+  const outOfOrder = [];
+  for (const s of enriched) {
+    const stage = stageOf.get(s.number);
+    const idx = stage ? STAGE_ORDER.indexOf(stage) : -1;
+    if (idx === -1 || idx < devIdx) continue; // ainda não chegou em Desenvolvimento
+    for (const d of s.dependsOn) {
+      if (!byNumber.has(d)) continue; // dependência externa ao conjunto — sem Etapa conhecida
+      const depStage = stageOf.get(d);
+      if (depStage !== STAGE_DONE) {
+        outOfOrder.push(
+          `#${s.number} já está em "${stage}", mas depende de #${d} (Etapa: ${depStage || '—'}), que ainda não chegou em "${STAGE_DONE}".`
+        );
+      }
+    }
+  }
+  if (outOfOrder.length > 0) {
+    p.log.warn('Dependências fora de ordem:\n' + outOfOrder.map(w => `  • ${w}`).join('\n'));
+  }
+
+  p.outro(`${chalk.green('✓')} ${sorted.length} de ${enriched.length} story(ies) ordenada(s).`);
+}

package/src/commands/qa.mjs

@@ -2,9 +2,10 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, getPR, commentOnIssue } from '../api/github-rest.mjs';
-import { addProjectItem, setItemSingleSelect, getSingleSelectField, getIssueParent, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { getIssueParent } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { CONFIG_FILE, STATUS_OPTIONS, STAGE_ORDER, PROGRESS_TODO } from '../config.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { CONFIG_FILE, STATUS_OPTIONS, PROGRESS_TODO } from '../config.mjs';
 
 const QA_STAGE = STATUS_OPTIONS.find(s => s.name.includes('QA'))?.name;
 const TODO_STATUS = PROGRESS_TODO;
@@ -20,14 +21,6 @@ function extractIssueNumbers(body) {
   return [...nums];
 }
 
-async function resolveField(token, project, name) {
-  if (project.fields?.[name]) return project.fields[name];
-  if (name === 'Etapa' && project.etapaFieldId) {
-    return { id: project.etapaFieldId, options: project.stageOptions || {} };
-  }
-  return await getSingleSelectField(token, project.id, name);
-}
-
 async function resolveFeatureIssue(token, owner, repo, issueNumber) {
   let issue;
   try {
@@ -50,27 +43,6 @@ async function resolveFeatureIssue(token, owner, repo, issueNumber) {
   return null;
 }
 
-// Avança para a Etapa "🧪 QA" e reinicia o Status para "Todo". Uma issue só
-// AVANÇA: se já estiver em QA ou etapa posterior, não é tocada (retorna false).
-async function setQA(token, project, etapaField, statusField, nodeId) {
-  const itemId = await addProjectItem(token, project.id, nodeId);
-  if (etapaField?.id && QA_STAGE) {
-    const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
-    const curIdx = current ? STAGE_ORDER.indexOf(current) : -1;
-    const tgtIdx = STAGE_ORDER.indexOf(QA_STAGE);
-    if (curIdx !== -1 && tgtIdx !== -1 && curIdx >= tgtIdx) {
-      return false; // já está em QA ou adiante — não retrocede
-    }
-    const optionId = etapaField.options?.[QA_STAGE];
-    if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
-  }
-  if (statusField?.id) {
-    const optionId = statusField.options?.[TODO_STATUS];
-    if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
-  }
-  return true;
-}
-
 export async function qa({ prNumber }) {
   const token = await resolveToken();
   const projectToken = process.env.PROJECT_TOKEN || token;
@@ -96,20 +68,9 @@ export async function qa({ prNumber }) {
     return;
   }
 
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  if (!existsSync(configPath)) {
-    console.warn(`${CONFIG_FILE} não encontrado — board não atualizado.`);
-    return;
-  }
-  let project;
-  try {
-    project = JSON.parse(readFileSync(configPath, 'utf-8')).project || {};
-  } catch (err) {
-    console.warn(`${CONFIG_FILE} corrompido (${err.message}) — board não atualizado.`);
-    return;
-  }
-  if (!project.id) {
-    console.warn(`Project não configurado em ${CONFIG_FILE} — board não atualizado.`);
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) {
+    console.warn(`${projectError} — board não atualizado.`);
     return;
   }
 
@@ -124,7 +85,8 @@ export async function qa({ prNumber }) {
     if (!feature || seen.has(feature.number)) continue;
     seen.add(feature.number);
     try {
-      const moved = await setQA(projectToken, project, etapaField, statusField, feature.node_id);
+      // Avança para "🧪 QA" e reinicia o Status em "Todo" (nunca retrocede).
+      const moved = await advanceToStage(projectToken, project, etapaField, statusField, feature.node_id, QA_STAGE, TODO_STATUS);
       if (moved) {
         updated.push(`#${feature.number} ${feature.title}`);
         console.log(`Feature #${feature.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);

package/src/commands/story.mjs

@@ -0,0 +1,128 @@
+// Gerencia uma Story no board: review (Etapa "👀 Code Review" + Status "Todo").
+//
+// Comando LOCAL — rodado pelo dev no terminal. owner/repo vêm da env
+// GITHUB_REPOSITORY quando existir, senão do .spec-wave.json (gravado pelo init).
+//
+// Regra do board (ver config.mjs): a Etapa nunca retrocede — se a Story já
+// estiver em Code Review ou adiante, o comando apenas informa a Etapa atual.
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue } from '../api/github-rest.mjs';
+import { addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { CONFIG_FILE, STAGE_CODE_REVIEW, PROGRESS_TODO } from '../config.mjs';
+
+// Resolve owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
+// fallback no .spec-wave.json — comandos locais rodam sem essa env.
+function resolveRepoContext() {
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  let cfg = {};
+  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
+  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
+  return { owner: envOwner || cfg.owner, repo: envRepo || cfg.repo };
+}
+
+export async function story({ action, issue: issueArg }) {
+  if (action !== 'review') {
+    p.log.error(
+      `Ação desconhecida: "${action}".\n` +
+      'Uso: spec-wave story review <número> — ex.: spec-wave story review 12'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { owner, repo } = resolveRepoContext();
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`) ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(`spec-wave story review #${issueNumber}`));
+
+  // 1. Lê a issue e valida o tipo.
+  let issue;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch (err) {
+    p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const type = detectIssueType(issue);
+  if (type !== 'Story') {
+    p.log.error(
+      `\`spec-wave story\` só aceita issues do tipo Story. ` +
+      `Issue #${issueNumber} é do tipo ${type || 'desconhecido'} (${issue.title}).`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Project do .spec-wave.json — sem ele não há board para atualizar.
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) {
+    p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);
+    process.exitCode = 1;
+    return;
+  }
+  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+  const statusField = await resolveField(token, project, 'Status').catch(() => null);
+
+  // 3. Avança para Code Review (Status reinicia em Todo ao trocar de etapa).
+  let moved;
+  try {
+    moved = await advanceToStage(token, project, etapaField, statusField, issue.node_id, STAGE_CODE_REVIEW, PROGRESS_TODO);
+  } catch (err) {
+    p.log.error(`Falha ao atualizar o board: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (moved) {
+    p.log.success(`Story #${issueNumber} → Etapa ${chalk.bold(STAGE_CODE_REVIEW)} / Status ${chalk.bold(PROGRESS_TODO)}.`);
+    p.outro(`${chalk.green('✓')} Story #${issueNumber} pronta para revisão.`);
+    return;
+  }
+
+  // false = a Story já está em Code Review ou em etapa posterior — e a Etapa
+  // NUNCA retrocede. Lê a Etapa atual só para informar o usuário.
+  let current = null;
+  if (etapaField?.id) {
+    try {
+      const itemId = await addProjectItem(token, project.id, issue.node_id);
+      current = await getItemSingleSelectValue(token, itemId, etapaField.id);
+    } catch {
+      // sem leitura da Etapa — segue com o aviso genérico
+    }
+  }
+  p.log.info(
+    `Story #${issueNumber} não foi movida: a Etapa nunca retrocede, e ela já está em ` +
+    `${chalk.bold(current || `"${STAGE_CODE_REVIEW}" ou etapa posterior`)}.`
+  );
+  p.outro('Nada a fazer.');
+}