@spec-wave/cli 0.24.0 → 0.26.0

package/src/commands/mode.mjs

@@ -0,0 +1,180 @@
+// Alterna entre rodar o fluxo no GitHub Actions e rodar nesta máquina.
+//
+// O comando escreve os DOIS lados do interruptor — o `.spec-wave.json`, que a
+// CLI e a skill leem, e a variável de repositório, que o `if:` de cada job
+// avalia. Escrever só um deles é o defeito que o comando existe para evitar:
+// config em "local" com a variável ausente significa workflow disparando e
+// minuto sendo cobrado enquanto o usuário acha que desligou.
+//
+// A variável exige permissão de administração. Sem ela o comando NÃO finge que
+// deu certo: grava o config, diz o que falta e aponta a alternativa manual.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import { getRepoVariable, setRepoVariable, deleteRepoVariable } from '../api/github-rest.mjs';
+import { CONFIG_FILE, WORKFLOW_FILES } from '../config.mjs';
+import { updateConfig } from '../lib/config-file.mjs';
+import {
+  EXECUTION_MODES, EXECUTION_VARIABLE, EXECUTION_GUARD,
+  configuredMode, variableValueFor, describeModeState, shouldWriteVariable,
+} from '../lib/execution-mode.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+
+/**
+ * Workflows instalados que NÃO carregam a guarda (função quase pura — só lê o fs).
+ *
+ * @param {string|null} root
+ * @returns {string[]}
+ */
+export function unguardedWorkflows(root) {
+  const dir = path.join(root || process.cwd(), '.github', 'workflows');
+  if (!existsSync(dir)) return [];
+  const presentes = new Set(readdirSync(dir));
+  return WORKFLOW_FILES
+    .filter(file => presentes.has(file))
+    .filter(file => !readFileSync(path.join(dir, file), 'utf-8').includes(EXECUTION_GUARD));
+}
+
+// A variável só é legível por quem administra o repo. 403 não é falha: é "não
+// verificável", e quem chama distingue isso de "não existe" (null).
+async function readVariable(token, owner, repo) {
+  try {
+    return await getRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+  } catch (err) {
+    if (err.status === 403 || err.status === 404) return undefined;
+    throw err;
+  }
+}
+
+export async function mode({ target, dryRun = false } = {}) {
+  p.intro(chalk.bold('spec-wave mode'));
+
+  const { config, root, configPath } = loadConfig();
+  if (!config) {
+    p.log.error(`${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` antes.`);
+    process.exit(1);
+  }
+
+  const alvo = target ? String(target).toLowerCase() : null;
+  if (alvo && !EXECUTION_MODES.includes(alvo)) {
+    p.log.error(`Modo inválido: ${alvo}. Use um de: ${EXECUTION_MODES.join(', ')}.`);
+    process.exit(1);
+  }
+
+  const atual = configuredMode(config);
+  const owner = config.owner;
+  const repo = config.repo;
+
+  let token = null;
+  let variavel;
+  if (owner && repo) {
+    try {
+      token = await resolveToken();
+      variavel = await readVariable(token, owner, repo);
+    } catch (err) {
+      p.log.warn(`Não foi possível consultar a variável do repositório: ${err.message}`);
+      variavel = undefined;
+    }
+  }
+
+  // Sem argumento: só relatório.
+  if (!alvo) {
+    const estado = describeModeState({
+      configured: atual, variable: variavel, unguardedWorkflows: unguardedWorkflows(root),
+    });
+    p.log.info(estado.summary);
+    for (const nota of estado.notes) p.log.message(`• ${nota}`);
+    for (const fix of estado.fixes) p.log.warn(fix);
+    p.outro(
+      atual === 'local'
+        ? `Próximo passo de uma issue: ${chalk.cyan('spec-wave run <issue>')}`
+        : `Para desligar o CI: ${chalk.cyan('spec-wave mode local')}`
+    );
+    return { mode: atual, variable: variavel, changed: false };
+  }
+
+  const esperado = variableValueFor(alvo);
+  const mudaConfig = atual !== alvo;
+  // `undefined` é "não deu para LER" (403 — a variável exige admin), e não
+  // "está como deveria". Tratar os dois iguais fazia o comando pular a escrita
+  // e ainda assim anunciar que config e variável coincidiam: o usuário saía
+  // achando que desligou o CI, com os workflows armados e o minuto sendo
+  // cobrado — exatamente o meio-caminho que este comando existe para evitar.
+  //
+  // Não conseguir ler quase sempre significa não conseguir escrever. Tentar e
+  // falhar com a mensagem certa é honesto; não tentar e dizer "coincidem" não.
+  const mudaVariavel = shouldWriteVariable({ variable: variavel, expected: esperado });
+
+  if (!mudaConfig && !mudaVariavel) {
+    p.log.success(`Já está em ${chalk.bold(alvo)} — config e variável do repositório coincidem.`);
+    p.outro('Nada a fazer.');
+    return { mode: alvo, variable: variavel, changed: false, variableApplied: true };
+  }
+
+  if (dryRun) {
+    if (mudaConfig) p.log.info(`${CONFIG_FILE}: execution.mode ${atual} → ${alvo}`);
+    if (mudaVariavel) {
+      const atualDaVariavel = variavel === undefined
+        ? 'valor atual desconhecido — sem permissão para ler'
+        : `valor atual: ${variavel === null ? 'ausente' : variavel}`;
+      p.log.info(esperado === null
+        ? `Variável ${EXECUTION_VARIABLE}: remover (${atualDaVariavel})`
+        : `Variável ${EXECUTION_VARIABLE}: definir como "${esperado}" (${atualDaVariavel})`);
+    }
+    p.outro('Dry-run: nada foi alterado.');
+    return { mode: atual, variable: variavel, changed: false };
+  }
+
+  if (mudaConfig) {
+    const { changed } = updateConfig(cfg => {
+      cfg.execution = { ...(cfg.execution || {}), mode: alvo };
+    }, { cwd: root || process.cwd() });
+    if (changed) p.log.success(`${CONFIG_FILE} atualizado: execution.mode = ${alvo}`);
+  }
+
+  let variavelOk = true;
+  if (token && owner && repo) {
+    try {
+      if (esperado === null) {
+        const removida = await deleteRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+        p.log.success(removida
+          ? `Variável ${EXECUTION_VARIABLE} removida — os workflows voltam a disparar.`
+          : `Variável ${EXECUTION_VARIABLE} já não existia.`);
+      } else {
+        await setRepoVariable(token, owner, repo, EXECUTION_VARIABLE, esperado);
+        p.log.success(`Variável ${EXECUTION_VARIABLE}=${esperado} — os jobs passam a ser pulados (0 minutos).`);
+      }
+    } catch (err) {
+      variavelOk = false;
+      p.log.error(
+        `Não foi possível escrever a variável ${EXECUTION_VARIABLE} (${err.status || ''} ${err.message}).\n` +
+        'Ela exige administração no repositório — peça a um admin, ou defina em ' +
+        'Settings → Secrets and variables → Actions → Variables.'
+      );
+    }
+  } else {
+    variavelOk = false;
+    p.log.warn(`Sem owner/repo ou token: só o ${CONFIG_FILE} foi atualizado.`);
+  }
+
+  const semGuarda = unguardedWorkflows(root);
+  if (alvo === 'local' && semGuarda.length > 0) {
+    p.log.warn(
+      `Estes workflows instalados ainda não têm a guarda \`${EXECUTION_GUARD}\` e vão rodar mesmo assim: ` +
+      `${semGuarda.join(', ')}. Rode \`npx @spec-wave/cli@latest update\`.`
+    );
+  }
+
+  p.log.message(chalk.dim(`Commite o ${configPath ? path.basename(configPath) : CONFIG_FILE} — quem clona o repo lê a versão versionada.`));
+  p.outro(
+    alvo === 'local'
+      ? `Modo local. Conduza o fluxo com ${chalk.cyan('spec-wave run <issue>')}.`
+      : 'Modo actions. As labels de gatilho voltam a disparar os workflows.'
+  );
+  return { mode: alvo, variable: esperado, changed: true, variableApplied: variavelOk };
+}

package/src/commands/run.mjs

@@ -0,0 +1,491 @@
+// Executa LOCALMENTE o passo que a label dispararia no GitHub Actions.
+//
+// O YAML nunca fez trabalho nenhum: ele instala a CLI e chama um comando. Este
+// comando fecha o buraco que sobra quando os workflows estão desarmados
+// (`spec-wave mode local`) — decidir QUAL comando é o próximo e chamá-lo, sem
+// aplicar label nenhuma.
+//
+// A decisão é uma função pura (`lib/next-step.mjs`), testada sem rede. Aqui só
+// mora o que é impuro: coletar o estado, segurar o lock, despachar e relatar.
+//
+// Três coisas que este comando NUNCA faz, e o porquê:
+//  • aplicar label de gatilho — dispararia o Action e a execução aconteceria duas vezes;
+//  • rodar dentro do Actions — lá o contrato é a label (`assertNotInActions`);
+//  • encadear passos sem teto — cada passo de IA custa dinheiro (`--max-steps`).
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue, getPR, getFileContent, listPullRequestReviews } from '../api/github-rest.mjs';
+import { loadProjectConfig } from '../lib/board.mjs';
+import { existsOnRemote } from '../lib/doc-availability.mjs';
+import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
+import { isActionsRun, resolveFlowContext } from '../lib/flow-run.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { nextStep, resolveForcedStep, stepDocs, docsForType, STEPS } from '../lib/next-step.mjs';
+import { nextPrStep, reviewVerdict } from '../lib/pr-step.mjs';
+import { configuredMode } from '../lib/execution-mode.mjs';
+import { labelNames } from '../config.mjs';
+
+const LOCK_STALE_MS = 30 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Lock — o substituto do `concurrency: spec-wave-item-<n>` dos workflows.
+//
+// Sem ele, dois `run` na mesma issue geram dois documentos, dois commits
+// disputando a ponta da branch e leitura-modificação-escrita concorrente do
+// comentário de uso. Fica em .git/ porque já é ignorado e é por clone.
+// ---------------------------------------------------------------------------
+
+/**
+ * Diretório .git COMPARTILHADO do clone (função com I/O, isolada para teste).
+ *
+ * Montar `<root>/.git` à mão assume que `.git` é um diretório — e num git
+ * worktree ele é um ARQUIVO com `gitdir: <caminho real>`. O `mkdirSync` do
+ * acquireLock estourava ENOTDIR ali, derrubando TODO `spec-wave run` de dentro
+ * de um worktree, inclusive `--dry-run`, antes de qualquer trabalho.
+ *
+ * `--git-common-dir` e não `--git-dir`: num worktree o `--git-dir` é
+ * `.git/worktrees/<nome>`, o que tornaria o lock por WORKTREE. Dois `run` na
+ * mesma issue em worktrees diferentes rodariam em paralelo commitando na mesma
+ * branch — exatamente o que este lock existe para impedir. O comum preserva o
+ * "é por clone" que o comentário acima declara.
+ *
+ * O caminho devolvido é RELATIVO ao cwd quando se está no clone principal
+ * (`.git` na raiz, `../../.git` num subdiretório) e absoluto de dentro de um
+ * worktree — daí o `path.resolve`. Sem ele, rodar de um subdiretório criaria um
+ * `.git/` novo ali dentro, que é um estrago pior e mais silencioso que o ENOTDIR.
+ *
+ * @param {string} [root] raiz do projeto (a do .spec-wave.json)
+ * @returns {string} caminho absoluto do diretório .git compartilhado
+ */
+export function gitCommonDir(root) {
+  const cwd = root || process.cwd();
+  try {
+    const out = execSync('git rev-parse --git-common-dir', {
+      cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (out) return path.resolve(cwd, out);
+  } catch {
+    // Fora de um repositório git: cai no palpite antigo. O `run` vai falhar
+    // adiante de qualquer forma (ele commita e faz push), e com mensagem melhor.
+  }
+  return path.join(cwd, '.git');
+}
+
+export function lockPath(root, key) {
+  return path.join(gitCommonDir(root), 'spec-wave', `run-${key}.lock`);
+}
+
+function acquireLock(root, key) {
+  const file = lockPath(root, key);
+  mkdirSync(path.dirname(file), { recursive: true });
+  const payload = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+  try {
+    writeFileSync(file, payload, { flag: 'wx' });
+    return file;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    let idade = Infinity;
+    let dono = null;
+    try {
+      dono = JSON.parse(readFileSync(file, 'utf-8'));
+      idade = Date.now() - Date.parse(dono.startedAt);
+    } catch { /* lock ilegível conta como velho */ }
+    if (idade < LOCK_STALE_MS) {
+      throw new Error(
+        `Já existe um \`spec-wave run\` para ${key} (pid ${dono?.pid ?? '?'}, desde ${dono?.startedAt ?? '?'}).\n` +
+        `Se tiver certeza de que morreu, apague ${file}.`
+      );
+    }
+    console.warn(`⚠️  Lock antigo encontrado (${file}) — assumindo processo morto e seguindo.`);
+    writeFileSync(file, payload);
+    return file;
+  }
+}
+
+function releaseLock(file) {
+  try {
+    if (file) unlinkSync(file);
+  } catch { /* já removido */ }
+}
+
+// Commits locais ainda não publicados: gerar o próximo documento por cima de um
+// anterior que ficou só no clone é execução parcial disfarçada de sucesso.
+function unpushedCommits(root) {
+  try {
+    const out = execSync('git rev-list --count @{u}..HEAD', {
+      cwd: root || process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return Number.parseInt(out, 10) || 0;
+  } catch {
+    return 0; // sem upstream configurado: não dá para afirmar nada
+  }
+}
+
+function assertNotInActions() {
+  if (!isActionsRun()) return;
+  throw new Error(
+    'O `run` é o gatilho do modo LOCAL — dentro do GitHub Actions o gatilho é a label, ' +
+    'e o workflow já chama o comando certo. Rodar os dois seria executar o passo duas vezes.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Coleta do estado
+// ---------------------------------------------------------------------------
+
+function localDocStates(issue, type, root) {
+  if (type === 'Bug') {
+    const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+    return {
+      docs: { bug: existsSync(fileAbs) ? 'local' : 'missing' },
+      docPaths: { bug: fileRel },
+    };
+  }
+  const paths = featureDocPaths(root, issue, type);
+  const docs = {};
+  const docPaths = {};
+  for (const nome of ['spec', 'plan', 'decomposition']) {
+    docs[nome] = existsSync(paths[nome].abs) ? 'local' : 'missing';
+    docPaths[nome] = paths[nome].rel;
+  }
+  return { docs, docPaths };
+}
+
+/**
+ * Sonda o remoto SÓ pelos documentos que o passo escolhido usa e que faltam no
+ * clone. É a diferença entre "ainda não foi gerado" e "foi gerado e você não
+ * puxou" — a segunda leva a sobrescrever trabalho publicado.
+ */
+/**
+ * Documentos que vale sondar no remoto antes de acreditar na decisão (PURA).
+ *
+ * O G5 ("as labels afirmam um documento que não existe aqui") diz, com todas as
+ * letras, que o arquivo *não está no clone nem no remoto* — e manda renomear o
+ * diretório ou REGERAR. Enquanto a sonda só rodava para decisão não-bloqueada,
+ * essa frase era afirmada sem nunca ter perguntado ao remoto: num clone que
+ * está apenas atrás, o conselho levava a regerar por cima de um documento
+ * publicado, gastando uma chamada de IA para destruir o artefato bom. A
+ * correção certa era `git pull`.
+ *
+ * Nesse caso o passo é `none` e não há `writes`/`reads` de onde tirar a lista —
+ * sondamos os documentos do tipo.
+ *
+ * @param {{action: string, blocked: object|null}} decision
+ * @param {string|null} type
+ * @returns {string[]}
+ */
+export function docsToProbe(decision, type) {
+  if (decision.blocked?.code === 'inconsistent-state') return docsForType(type);
+  if (decision.blocked || !STEPS[decision.action]) return [];
+  // stepDocs e não `[writes, ...reads]`: `validate` e `decompose` leem
+  // documentos diferentes conforme o tipo, e sondar a lista errada devolve um
+  // `docs` que o G6 aprova por engano.
+  return stepDocs(decision.action, type);
+}
+
+async function probeRemote({ alvos, docs, docPaths, token, owner, repo }) {
+  if (alvos.length === 0) return docs;
+
+  const atualizado = { ...docs };
+  for (const doc of alvos) {
+    const onRemote = await existsOnRemote({
+      getFileContent, token, owner, repo, pathRel: docPaths[doc],
+    });
+    if (onRemote === true) atualizado[doc] = 'remote';
+    else if (onRemote === null) atualizado[doc] = 'unknown';
+  }
+  return atualizado;
+}
+
+// ---------------------------------------------------------------------------
+// Relato
+// ---------------------------------------------------------------------------
+
+function reportDecision(decision, { issueNumber, type, title, warnings }) {
+  console.log(chalk.bold(`\nIssue #${issueNumber} · ${type || 'tipo desconhecido'} · ${title}`));
+  console.log(`Próximo passo: ${chalk.cyan(decision.action)}`);
+  console.log(`Motivo: ${decision.reason}`);
+  if (decision.command) console.log(`Comando: ${chalk.dim(decision.command)}`);
+  for (const aviso of warnings) console.warn(chalk.yellow(`⚠️  ${aviso}`));
+  if (decision.blocked) {
+    console.log(chalk.yellow(`\n⛔ ${decision.blocked.code}: ${decision.blocked.message}`));
+    console.log(`   ${decision.blocked.unblock}`);
+  }
+}
+
+// O prefixo do título é o que os workflows filtram (`contains(title, '[FEATURE]')`),
+// enquanto detectIssueType tem fallback por label: sem o aviso, uma issue rodaria
+// local e nunca rodaria no runner, e a diferença só apareceria ao voltar o modo.
+function parityWarnings(issue, type) {
+  const avisos = [];
+  const titulo = String(issue.title || '');
+  if (type && !titulo.includes(`[${type.toUpperCase()}]`)) {
+    avisos.push(
+      `O título não traz o prefixo [${type.toUpperCase()}] — o workflow correspondente NÃO ` +
+      'dispararia para esta issue no modo actions (ele filtra pelo título).'
+    );
+  }
+  return avisos;
+}
+
+// ---------------------------------------------------------------------------
+// Despacho
+// ---------------------------------------------------------------------------
+
+/**
+ * Saída de `--json` (função PURA — devolve o texto, não imprime).
+ *
+ * UM documento, sempre. A impressão morava dentro do laço de passos, então
+ * `--max-steps N` emitia N documentos JSON concatenados — saída que nenhum
+ * parser aceita, numa flag que a skill anuncia justamente para ramificar
+ * programaticamente.
+ *
+ * O desfecho fica no TOPO, e não só dentro de `steps`: é o que quase todo
+ * consumidor lê, e é exatamente o formato que a execução de um passo só já
+ * produzia. Assim a correção não quebra quem já lia `.action`.
+ *
+ * @param {object} params
+ * @param {string|number} params.issueNumber
+ * @param {string|null} params.type
+ * @param {object|null} params.ultimaDecisao
+ * @param {object[]} [params.passos]
+ * @returns {string} JSON indentado
+ */
+export function renderRunJson({ issueNumber, type, ultimaDecisao, passos = [] }) {
+  return JSON.stringify(
+    { issue: Number(issueNumber), type: type ?? null, ...ultimaDecisao, steps: passos },
+    null, 2,
+  );
+}
+
+async function dispatch(action, { issueNumber }) {
+  switch (action) {
+    case 'generate-spec': {
+      const { generateSpec } = await import('./generate-spec.mjs');
+      return await generateSpec({ issueNumber });
+    }
+    case 'generate-plan': {
+      const { generatePlan } = await import('./generate-plan.mjs');
+      return await generatePlan({ issueNumber });
+    }
+    case 'critique': {
+      const { critique } = await import('./generate-plan.mjs');
+      return await critique({ issueNumber });
+    }
+    case 'validate': {
+      const { validate } = await import('./validate.mjs');
+      return await validate({ issueNumber });
+    }
+    case 'decompose': {
+      const { decompose } = await import('./decompose.mjs');
+      return await decompose({ issueNumber, apply: false });
+    }
+    case 'decompose-apply': {
+      const { decompose } = await import('./decompose.mjs');
+      return await decompose({ issueNumber, apply: true });
+    }
+    case 'generate-bug': {
+      const { generateBug } = await import('./generate-bug.mjs');
+      return await generateBug({ issueNumber });
+    }
+    default:
+      throw new Error(`Passo sem despacho: ${action}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Modo PR
+// ---------------------------------------------------------------------------
+
+async function runForPr({ prNumber, dryRun, yes, only, json }) {
+  const { owner, repo, root } = resolveFlowContext({ command: 'run --pr' });
+  const token = await resolveToken();
+  const n = parseInt(prNumber, 10);
+
+  const pr = await getPR(token, owner, repo, n);
+  const reviews = await listPullRequestReviews(token, owner, repo, n);
+  const verdict = reviewVerdict(reviews);
+  const decision = nextPrStep({
+    state: pr.state,
+    draft: Boolean(pr.draft),
+    merged: Boolean(pr.merged_at),
+    approved: verdict.approved,
+    changesRequestedAfterApproval: verdict.changesRequestedAfterApproval,
+    only: only || null,
+  });
+
+  const { error: boardError } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (boardError) decision.warnings.push(`${boardError} — o board não será atualizado.`);
+
+  if (json) {
+    console.log(JSON.stringify({ pr: n, ...decision, approvers: verdict.approvers }, null, 2));
+  } else {
+    console.log(chalk.bold(`\nPR #${n} · ${pr.title}`));
+    console.log(`Passos: ${decision.steps.length ? chalk.cyan(decision.steps.join(' → ')) : '(nenhum)'}`);
+    console.log(`Motivo: ${decision.reason}`);
+    for (const aviso of decision.warnings) console.warn(chalk.yellow(`⚠️  ${aviso}`));
+    if (decision.blocked) console.log(chalk.yellow(`\n⛔ ${decision.blocked.code}: ${decision.blocked.message}`));
+  }
+
+  if (decision.blocked || decision.steps.length === 0) {
+    process.exitCode = decision.blocked ? 2 : 0;
+    return decision;
+  }
+  if (verdict.changesRequestedAfterApproval && !yes) {
+    console.log(chalk.yellow('\n⛔ needs-confirmation: há pedido de mudanças além da aprovação. Confirme com `--yes`.'));
+    process.exitCode = 2;
+    return decision;
+  }
+  if (dryRun) {
+    console.log(chalk.dim('\nDry-run: nada foi executado.'));
+    return decision;
+  }
+
+  const lock = acquireLock(root, `pr-${n}`);
+  try {
+    for (const step of decision.steps) {
+      console.log(chalk.bold(`\n▶ ${step} --pr-number ${n}`));
+      if (step === 'code-review') {
+        const { codeReview } = await import('./code-review.mjs');
+        await codeReview({ prNumber: String(n) });
+      } else {
+        const { qa } = await import('./qa.mjs');
+        await qa({ prNumber: String(n) });
+      }
+    }
+  } finally {
+    releaseLock(lock);
+  }
+  return decision;
+}
+
+// ---------------------------------------------------------------------------
+// Comando
+// ---------------------------------------------------------------------------
+
+export async function run(issueArg, options = {}) {
+  assertNotInActions();
+
+  const {
+    pr, dryRun = false, yes = false, apply = false, step: forced = null,
+    maxSteps = 1, force = false, remoteCheck = true, json = false, only = null,
+  } = options;
+
+  if (pr) return await runForPr({ prNumber: pr, dryRun, yes, only, json });
+
+  if (!issueArg) throw new Error('Informe o número da issue: `spec-wave run <issue>` (ou `--pr <n>`).');
+
+  const { owner, repo, root, config } = resolveFlowContext({ command: 'run' });
+  const token = await resolveToken();
+  const issueNumber = String(issueArg).replace(/^#/, '');
+  const teto = Math.max(1, parseInt(maxSteps, 10) || 1);
+
+  if (configuredMode(config) !== 'local') {
+    console.warn(chalk.yellow(
+      '⚠️  Este repositório está em modo `actions` — os workflows continuam armados e podem ' +
+      'rodar o mesmo passo. Use `spec-wave mode local` para desarmá-los.'
+    ));
+  }
+
+  const lock = acquireLock(root, issueNumber);
+  // `critiqueFile` seta process.exitCode = 1; sem preservar, um run inteiro
+  // bem-sucedido sairia com código de erro.
+  const exitCodeAntes = process.exitCode;
+  try {
+    let ultimaDecisao = null;
+    // `--json` acumula e imprime UMA vez no fim (ver renderRunJson).
+    const passos = [];
+    let ultimoTipo = null;
+
+    for (let i = 0; i < teto; i++) {
+      const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+      const type = detectIssueType(issue);
+      const { docs, docPaths } = localDocStates(issue, type, root);
+      const { error: boardError } = loadProjectConfig({ cwd: root || process.cwd() });
+
+      let forcedStep = null;
+      if (forced && i === 0) {
+        const resolvido = resolveForcedStep(forced, { type });
+        if (resolvido.error) throw new Error(resolvido.error);
+        forcedStep = resolvido.action;
+      }
+
+      const entrada = {
+        type,
+        issueNumber,
+        state: issue.state,
+        labels: labelNames(issue),
+        docPaths,
+        forcedStep,
+        confirmed: yes || apply,
+        boardReady: !boardError,
+        force,
+      };
+
+      let decision = nextStep({ ...entrada, docs });
+      if (remoteCheck) {
+        const alvos = docsToProbe(decision, type).filter(doc => docs[doc] === 'missing');
+        if (alvos.length > 0) {
+          const docsRemotos = await probeRemote({ alvos, docs, docPaths, token, owner, repo });
+          decision = nextStep({ ...entrada, docs: docsRemotos });
+        }
+      }
+      ultimaDecisao = decision;
+
+      // `--apply` é uma asserção sobre o estado esperado, não um "faça o que for":
+      // se o passo pendente virou outro, errar é melhor que sobrescrever um documento.
+      if (apply && decision.action !== 'decompose-apply' && !yes) {
+        throw new Error(
+          `--apply autoriza especificamente o \`decompose-apply\`, mas o passo pendente é ` +
+          `\`${decision.action}\`. Use --yes se era isso mesmo que você queria.`
+        );
+      }
+
+      ultimoTipo = type;
+      if (json) passos.push(decision);
+      else reportDecision(decision, { issueNumber, type, title: issue.title, warnings: parityWarnings(issue, type) });
+
+      if (decision.blocked) { process.exitCode = 2; break; }
+      if (decision.action === 'none') break;
+      if (dryRun) {
+        console.log(chalk.dim('\nDry-run: nada foi executado.'));
+        break;
+      }
+
+      console.log(chalk.bold(`\n▶ ${decision.command}\n`));
+      const resultado = await dispatch(decision.action, { issueNumber });
+      process.exitCode = exitCodeAntes;
+
+      // Reprova do validate é desfecho esperado, não exceção — mas encadear em
+      // cima dela repetiria o mesmo passo até esgotar `--max-steps`.
+      if (resultado?.ok === false) {
+        console.warn(chalk.yellow('\n⚠️  O passo terminou reprovado — corrija os problemas acima e repita.'));
+        process.exitCode = 2;
+        break;
+      }
+
+      const pendentes = unpushedCommits(root);
+      if (pendentes > 0) {
+        console.warn(chalk.yellow(
+          `\n⚠️  ${pendentes} commit(s) ainda não publicado(s). O próximo passo leria um documento ` +
+          'que só existe no seu clone — publique antes de continuar.'
+        ));
+        break;
+      }
+    }
+
+    if (json) {
+      console.log(renderRunJson({ issueNumber, type: ultimoTipo, ultimaDecisao, passos }));
+    }
+
+    return ultimaDecisao;
+  } finally {
+    releaseLock(lock);
+  }
+}