@spec-wave/cli 0.24.0 → 0.26.0

package/README.md

@@ -113,6 +113,24 @@ Arquivo em `.github/config/tech_context.yml` que descreve a stack tecnológica d
 
 ---
 
+## Modo de execução: GitHub Actions ou local
+
+Todo passo do fluxo roda nos dois lugares — os workflows só instalam a CLI e
+chamam um comando. Para conduzir tudo sem consumir minutos de Actions:
+
+```bash
+npx @spec-wave/cli@latest mode local     # desarma os workflows (variável SPEC_WAVE_EXECUTION)
+npx @spec-wave/cli@latest run <issue>    # executa aqui o passo que a label dispararia
+npx @spec-wave/cli@latest mode actions   # volta ao CI
+```
+
+Com a variável setada, cada job é pulado e o run aparece como *skipped* — job que
+não roda não é faturado. `run <issue> --dry-run` explica o próximo passo (e o
+porquê) sem executar nada. Detalhes em
+[`packages/spec-wave/README.md`](packages/spec-wave/README.md#modo-de-execução-actions-ou-local).
+
+---
+
 ## Instalação da CLI
 
 Não é necessário instalar globalmente — use `npx`:
@@ -130,6 +148,24 @@ spec-wave --help
 
 ---
 
+## Modo de execução: GitHub Actions ou local
+
+Todo passo do fluxo roda nos dois lugares — os workflows só instalam a CLI e
+chamam um comando. Para conduzir tudo sem consumir minutos de Actions:
+
+```bash
+npx @spec-wave/cli@latest mode local     # desarma os workflows (variável SPEC_WAVE_EXECUTION)
+npx @spec-wave/cli@latest run <issue>    # executa aqui o passo que a label dispararia
+npx @spec-wave/cli@latest mode actions   # volta ao CI
+```
+
+Com a variável setada, cada job é pulado e o run aparece como *skipped* — job que
+não roda não é faturado. `run <issue> --dry-run` explica o próximo passo (e o
+porquê) sem executar nada. Detalhes em
+[`packages/spec-wave/README.md`](packages/spec-wave/README.md#modo-de-execução-actions-ou-local).
+
+---
+
 ## Instalação da Skill
 
 A skill permite usar o fluxo diretamente no seu agente via `/spec-wave`.
@@ -438,6 +474,54 @@ job falha por indisponibilidade, não por erro de configuração.
 
 ---
 
+## Modo de execução: Actions ou local
+
+Os workflows nunca fizeram o trabalho — eles instalam a CLI e chamam um comando.
+Por isso o fluxo inteiro roda igual na sua máquina, e dá para **desligar o CI**
+quando o que incomoda é o consumo de minutos.
+
+```bash
+npx @spec-wave/cli@latest mode                 # estado atual
+npx @spec-wave/cli@latest mode local           # desarma os workflows
+npx @spec-wave/cli@latest run <issue> --dry-run  # explica o próximo passo
+npx @spec-wave/cli@latest run <issue>          # executa aqui
+npx @spec-wave/cli@latest mode actions         # volta ao CI
+```
+
+`mode` escreve os **dois** lados do interruptor: `execution.mode` no
+`.spec-wave.json` (o que a CLI e as skills leem) e a variável de repositório
+`SPEC_WAVE_EXECUTION` (o que o `if:` de cada job avalia). Com ela setada, o run
+aparece como *skipped* — **job que não roda não é faturado**. A variável exige
+admin no repositório; sem permissão o comando avisa em vez de fingir que aplicou.
+
+`run <issue>` executa o passo que a label dispararia, decidido pelo estado da
+issue: documentos que existem + labels presentes.
+
+| Estado | Passo |
+|---|---|
+| Feature sem `spec.md` | `generate-spec` |
+| spec pronta, sem `plan.md` | `generate-plan` (crítica embutida) |
+| sem `spec-wave:plan-approved` | `validate` |
+| validada, sem `decomposition.md` | `decompose` (rascunho) |
+| `spec-wave:decompose-ready` | `decompose-apply` — exige `--apply` |
+| Bug | `generate-bug` → `validate` → triagem (humana) |
+
+`run --pr <n>` cobre o lado do PR: `code-review` e, havendo review aprovada,
+também `qa`.
+
+Ele **se recusa** a rodar (saindo com código 2) quando há label de gatilho
+pendente na issue — Action em voo, e rodar por cima duplicaria o documento —,
+quando um portão humano da crítica está aplicado (`needs-human`,
+`critique-failed`), quando o documento existe no repositório mas não no seu
+clone (`git pull` primeiro) e quando o passo cria issues sem confirmação
+explícita. `--dry-run` mostra a decisão sem executar nada; `--force`, `--yes`,
+`--apply` e `--step` cobrem os casos em que você sabe o que está fazendo.
+
+O `doctor` tem um check para o par config × variável: divergir é o estado
+perigoso — é achar que desligou o CI e continuar pagando por ele.
+
+---
+
 ## Licença
 
 MIT

package/bin/spec-wave.mjs

@@ -1,345 +1,8 @@
 #!/usr/bin/env node
 
-import { program } from 'commander';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-import { readFileSync } from 'node:fs';
+// Ponto de entrada: a montagem do programa vive em ../src/cli.mjs para que ela
+// possa ser importada (doc gerada, testes de superfície) sem executar a CLI.
 
-const __dir = path.dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(path.join(__dir, '..', 'package.json'), 'utf-8'));
+import { buildProgram } from '../src/cli.mjs';
 
-program
-  .name('spec-wave')
-  .description('Setup spec-driven GitHub workflow with Projects v2')
-  .version(pkg.version)
-  // Conta do `gh` a usar nesta execução. Existe porque um GH_TOKEN exportado no
-  // shell (um `.envrc` na raiz de um diretório de projetos, por exemplo) vale
-  // para repositórios de QUALQUER org abaixo dele — e o GraphQL do GitHub
-  // mascara o 403 resultante como "Could not resolve to a Repository".
-  .option('--account <login>', 'Conta do gh a usar (vence GITHUB_TOKEN/GH_TOKEN fora do CI)')
-  .hook('preAction', async (thisCommand) => {
-    const { account } = thisCommand.opts();
-    if (account) {
-      const { setAccountOverride } = await import('../src/api/auth.mjs');
-      setAccountOverride(account);
-    }
-  });
-
-program
-  .command('init')
-  .description('Configura spec-wave em um repositório GitHub')
-  .option('--dry-run', 'Simula a configuração sem fazer alterações')
-  .option('--repo <owner/repo>', 'Repositório GitHub (ignora o wizard interativo)')
-  .option('--project-title <title>', 'Nome do GitHub Project (padrão: "<repo> — Spec Wave")')
-  .option('--skip-project', 'Pula a criação do GitHub Project (use se já foi criado)')
-  .option('--skip-labels', 'Pula a criação das labels')
-  .option('--skip-files', 'Pula a criação dos arquivos de workflow')
-  .option('--provider <provider>', 'Provider de IA dos workflows: anthropic ou openrouter')
-  .option('--model <model>', 'Modelo de IA usado pelos workflows (ex.: anthropic/claude-3.7-sonnet)')
-  .action(async (options) => {
-    const { init } = await import('../src/commands/init.mjs');
-    await init(options);
-  });
-
-program
-  .command('info')
-  .description('Mostra se o repositório atual foi inicializado e os dados do .spec-wave.json')
-  .option('--json', 'Saída em JSON (para uso programático)')
-  .action(async (options) => {
-    const { info } = await import('../src/commands/info.mjs');
-    await info(options);
-  });
-
-program
-  .command('refresh')
-  .description('Atualiza o .spec-wave.json local com os dados atuais do GitHub Project')
-  .option('--config', 'Re-consulta o Project e reescreve o .spec-wave.json')
-  .option('--stages', 'Acrescenta ao campo "Etapa" as colunas canônicas que faltam (nunca remove)')
-  .option('--dry-run', 'Com --stages: mostra o que seria enviado e não escreve nada')
-  .option('--yes', 'Com --stages: não pede confirmação')
-  .action(async (options) => {
-    const { refresh } = await import('../src/commands/refresh.mjs');
-    await refresh(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('issue')
-  .description('Cria um work item (initiative/epic/feature/story/task...), opcionalmente como sub-issue, e adiciona ao board')
-  .requiredOption('--title <title>', 'Título (sem o prefixo de tipo, ex.: [FEATURE])')
-  .option('--type <type>', 'Tipo: initiative, epic, feature, story, task, bug, spike ou rfc', 'feature')
-  .option('--parent <n>', 'Número da issue pai (cria como sub-issue dela)')
-  .option('--body <text>', 'Descrição')
-  .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3')
-  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
-  .action(async (options) => {
-    const { issue } = await import('../src/commands/issue.mjs');
-    await issue(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('initiative')
-  .description('Atalho de `issue --type initiative` (nó raiz que agrupa Epics)')
-  .requiredOption('--title <title>', 'Título da initiative (sem o prefixo [INITIATIVE])')
-  .option('--body <text>', 'Descrição da initiative')
-  .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3 (adiciona label)')
-  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
-  .action(async (options) => {
-    const { initiative } = await import('../src/commands/initiative.mjs');
-    await initiative(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('feature')
-  .description('Atalho de `issue --type feature`')
-  .requiredOption('--title <title>', 'Título da feature (sem o prefixo [FEATURE])')
-  .option('--parent <n>', 'Número da Epic pai (cria como sub-issue dela)')
-  .option('--body <text>', 'Descrição da feature')
-  .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3 (adiciona label)')
-  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
-  .action(async (options) => {
-    const { feature } = await import('../src/commands/feature.mjs');
-    await feature(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('bug')
-  .description('Cria um Bug (atalho de `issue --type bug`) — nasce em 🐞 Triagem, ou ✅ Ready se P0')
-  .requiredOption('--title <title>', 'Título (sem o prefixo [BUG])')
-  .option('--parent <n>', 'Feature ou Story afetada (cria como sub-issue dela)')
-  .option('--body <text>', 'Descrição: passos, esperado e obtido')
-  .option('--priority <p>', 'Severidade: P0, P1, P2 ou P3')
-  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
-  .action(async (options) => {
-    const { bug } = await import('../src/commands/bug.mjs');
-    await bug(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('triage')
-  .description('Tria um Bug: accept (→ ✅ Ready), reject (fecha) ou duplicate (fecha)')
-  .argument('<action>', 'accept | reject | duplicate')
-  .argument('<issue>', 'Número da issue do Bug')
-  .option('--reason <texto>', 'Motivo da rejeição (obrigatório em reject)')
-  .option('--of <n>', 'Número da issue original (obrigatório em duplicate)')
-  .option('--severity <p>', 'Reclassifica a severidade ao aceitar: P0–P3')
-  .action(async (action, issue, options) => {
-    const { triage } = await import('../src/commands/triage.mjs');
-    await triage({ action, issue, ...options })
-      .catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('update')
-  .description('Detecta o que está desatualizado (skill, .spec-wave.json, workflows/labels do repo) e atualiza só o que mudou')
-  .option('--global', 'Verifica a skill no escopo do usuário (padrão: projeto)')
-  .option('--skip-skill', 'Não verifica/atualiza a skill instalada')
-  .option('--skip-config', 'Não verifica/atualiza o .spec-wave.json local')
-  .option('--skip-repo', 'Não verifica/atualiza workflows e labels do repo')
-  .option('--branch [nome]', 'Envia os arquivos do repo como Pull Request numa branch, em um único commit (sem valor: spec-wave/update-v<versão>)')
-  .option('--config-in-pr', 'Força incluir o .spec-wave.json no Pull Request')
-  .option('--no-config-in-pr', 'Força manter o .spec-wave.json fora do Pull Request')
-  .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
-  .option('--yes', 'Aplica sem pedir confirmação')
-  .action(async (options) => {
-    const { update } = await import('../src/commands/update.mjs');
-    await update(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('install-skill')
-  .description('Instala a skill spec-wave no(s) agente(s) detectado(s): Claude Code, Codex, Cursor, opencode, Cline, Kilo, Antigravity, AGENTS.md')
-  .option('--agent <names>', 'Agente(s) alvo, separados por vírgula (pula a detecção)')
-  .option('--all', 'Instala em todos os agentes detectados')
-  .option('--global', 'Instala no escopo do usuário (padrão: projeto)')
-  .option('--dry-run', 'Mostra o que seria instalado sem gravar')
-  .option('--force', 'Sobrescreve arquivos existentes sem confirmar')
-  .option('--yes', 'Modo não-interativo')
-  .action(async (options) => {
-    const { installSkill } = await import('../src/commands/install-skill.mjs');
-    await installSkill(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('uninstall')
-  .description('Remove labels, arquivos .github e o .spec-wave.json (mantém o GitHub Project)')
-  .option('--repo <owner/repo>', 'Repositório (padrão: lê do .spec-wave.json)')
-  .option('--skip-labels', 'Não remove as labels')
-  .option('--skip-files', 'Não remove os arquivos .github')
-  .option('--keep-config', 'Mantém o .spec-wave.json local')
-  .option('--dry-run', 'Mostra o que seria removido sem alterar nada')
-  .option('--yes', 'Não pede confirmação')
-  .action(async (options) => {
-    const { uninstall } = await import('../src/commands/uninstall.mjs');
-    await uninstall(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('generate-plan')
-  .description('Gera plan.md para uma Feature — roda no GitHub Action ou localmente')
-  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .action(async (options) => {
-    const { generatePlan } = await import('../src/commands/generate-plan.mjs');
-    await generatePlan(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('critique')
-  .description('Critica um documento COMO ESTÁ, sem regerar — para depois de corrigi-lo à mão')
-  .option('--issue-number <n>', 'Número da issue: critica o plan.md dela e comenta (fluxo canônico)')
-  .option('--file <caminho>', 'Critica ESTE arquivo e imprime o resultado — sem issue, sem label, sem contar tentativa')
-  .option('--kind <tipo>', 'plan | spec | stories | bug (default: inferido do nome do arquivo)')
-  .option('--fail-on-grave', 'Sai com código 1 se houver finding grave (útil em script)')
-  .action(async (options) => {
-    const { critique } = await import('../src/commands/generate-plan.mjs');
-    await critique(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('generate-spec')
-  .description('Gera spec.md para uma Feature — roda no GitHub Action ou localmente')
-  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .action(async (options) => {
-    const { generateSpec } = await import('../src/commands/generate-spec.mjs');
-    await generateSpec(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('generate-bug')
-  .description('Gera bug.md para um Bug (usado pelo GitHub Action)')
-  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .action(async (options) => {
-    const { generateBug } = await import('../src/commands/generate-bug.mjs');
-    await generateBug(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('validate')
-  .description('Valida os documentos de uma issue: spec.md+plan.md de Feature, bug.md de Bug (usado pelo GitHub Action)')
-  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .action(async (options) => {
-    const { validate } = await import('../src/commands/validate.mjs');
-    await validate(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('decompose')
-  .description('Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado — roda no Action ou localmente')
-  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .option('--apply', 'Aplica o decomposition.md já revisado: cria as issues (sem esta flag, apenas gera/critica o rascunho)')
-  .action(async (options) => {
-    const { decompose } = await import('../src/commands/decompose.mjs');
-    await decompose(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('code-review')
-  .description('Move Feature para Code Review ao abrir um PR (usado pelo GitHub Action)')
-  .requiredOption('--pr-number <n>', 'Número do Pull Request')
-  .option('--resolve-only', 'Só descobre a Feature-alvo e imprime feature=<n>, sem tocar no board')
-  .action(async (options) => {
-    const { codeReview } = await import('../src/commands/code-review.mjs');
-    await codeReview(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('qa')
-  .description('Move Feature para QA ao aprovar um PR (usado pelo GitHub Action)')
-  .requiredOption('--pr-number <n>', 'Número do Pull Request')
-  .action(async (options) => {
-    const { qa } = await import('../src/commands/qa.mjs');
-    await qa(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('implement')
-  .description('Aciona o spec-kit implement para uma Feature (Stories pendentes em ordem de dependência), uma Story (todas as tasks) ou uma Task')
-  .argument('<issue>', 'Número da issue (Feature, Story ou Task), ex.: 12 ou #12')
-  .option('--feature-dir <path>', 'Caminho do docs/features/<slug> (sobrescreve a resolução automática)')
-  .option('--dry-run', 'Monta o contexto e imprime o comando sem executar o spec-kit')
-  .action(async (issue, options) => {
-    const { implement } = await import('../src/commands/implement.mjs');
-    await implement({ issue, ...options }).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('order')
-  .description('Ordena as Stories pelas dependências (topológica). Sem argumento, o mapa de todas as Features com trabalho')
-  .argument('[feature]', 'Número da issue da Feature, ex.: 12 ou #12. Omitido: todas as Features abertas fora de 🎉 Done')
-  .action(async (feature) => {
-    const { order } = await import('../src/commands/order.mjs');
-    await order({ feature }).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('task')
-  .description('Gerencia uma Task no board: start (Status "In Progress") ou done (Done)')
-  .argument('<action>', 'Ação: start ou done')
-  .argument('<n>', 'Número da issue da Task, ex.: 12 ou #12')
-  .action(async (action, n) => {
-    const { task } = await import('../src/commands/task.mjs');
-    await task({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('move')
-  .description('Move qualquer item do board (Feature, Story, Task, Bug, RFC) para uma Etapa — a Etapa nunca retrocede')
-  .argument('<n>', 'Número da issue, ex.: 8 ou #8')
-  .argument('<etapa>', 'Etapa de destino, com ou sem emoji, ex.: "code review", "Homologação", "🎉 Done"')
-  .option('--status <valor>', 'Valor do campo Status no destino: Todo, In Progress ou Done (default: Todo)')
-  .action(async (n, etapa, options) => {
-    const { move } = await import('../src/commands/move.mjs');
-    await move({ issue: n, stage: etapa, ...options })
-      .catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('repair-stage')
-  .description('Corrige a Etapa de itens que a automação errou — inclusive retrocedendo. Exige --yes e --reason, e registra o reparo na issue')
-  .argument('<issues>', 'Número(s) da(s) issue(s), ex.: 529 ou 529,530,531')
-  .argument('<etapa>', 'Etapa correta, com ou sem emoji, ex.: "ready", "✅ Ready"')
-  .option('--reason <motivo>', 'Por que o reparo é necessário (vai para o comentário de auditoria)')
-  .option('--status <valor>', 'Também corrige o Status: Todo, In Progress ou Done (default: não mexe)')
-  .option('--yes', 'Confirma o reparo (obrigatório)')
-  .option('--dry-run', 'Mostra o que seria reparado sem alterar nada')
-  .action(async (issues, etapa, options) => {
-    const { repairStage } = await import('../src/commands/repair-stage.mjs');
-    await repairStage(issues, etapa, options)
-      .catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('story')
-  .description('Gerencia uma Story no board: review (move para Code Review)')
-  .argument('<action>', 'Ação: review')
-  .argument('<n>', 'Número da issue da Story, ex.: 12 ou #12')
-  .action(async (action, n) => {
-    const { story } = await import('../src/commands/story.mjs');
-    await story({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('dev-agent')
-  .description('Instala (--install/--build) ou executa (--run) o spec-wave-agent nesta máquina')
-  .option('--install', 'Baixa o binário da release, gera a config e (com --service) o serviço')
-  .option('--build', 'Clona o repo do agente e compila com cargo (alternativa ao --install)')
-  .option('--run', 'Executa o agente em foreground (Ctrl+C encerra com checkpoint)')
-  .option('--service', 'No --install/--build: também instala e habilita systemd/launchd')
-  .option('--tag <tag>', 'Release (--install) ou branch/tag (--build); padrão: última release / main')
-  .option('--debug', 'No --run: RUST_LOG=debug')
-  .option('--dry-run', 'Mostra o que seria instalado sem gravar')
-  .option('--force', 'Reinstala o binário e regrava a config')
-  .option('--yes', 'Modo não-interativo')
-  .action(async (options) => {
-    const { devAgent } = await import('../src/commands/dev-agent.mjs');
-    await devAgent(options).catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program
-  .command('doctor')
-  .description('Diagnostica a configuração do spec-wave no repositório atual')
-  .action(async () => {
-    const { doctor } = await import('../src/commands/doctor.mjs');
-    await doctor().catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program.parse();
+buildProgram().parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-rest.mjs

@@ -445,7 +445,9 @@ export async function getPR(token, owner, repo, prNumber) {
 // `ref` é opcional (compatível com os chamadores de 4 argumentos): o modo PR do
 // `update` precisa ler o .spec-wave.json na BASE, não no que a API escolher.
 export async function getFileContent(token, owner, repo, path, ref) {
-  const octokit = makeOctokit(token);
+  // Quiet: 404 é resultado esperado aqui (o arquivo pode não existir), e a linha
+  // `GET ... - 404` no stderr parecia falha no meio da saída do `run`.
+  const octokit = makeQuietOctokit(token);
   try {
     const res = await octokit.rest.repos.getContent({
       owner, repo, path, ...(ref ? { ref } : {}),
@@ -456,3 +458,63 @@ export async function getFileContent(token, owner, repo, path, ref) {
     throw err;
   }
 }
+
+export async function listPullRequestReviews(token, owner, repo, prNumber) {
+  const octokit = makeOctokit(token);
+  return await octokit.paginate(octokit.rest.pulls.listReviews, {
+    owner, repo, pull_number: prNumber, per_page: 100,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Variables do Actions — a chave que desarma os workflows.
+//
+// O `if:` de cada job consulta `vars.SPEC_WAVE_EXECUTION`, e é aqui que a CLI
+// escreve esse valor. Exigem permissão de administração no repositório: um 403
+// não é falha do comando, é informação para o usuário (e o `doctor` a repete).
+// ---------------------------------------------------------------------------
+
+/** Valor da variável, ou null se ela não existe. */
+export async function getRepoVariable(token, owner, repo, name) {
+  const octokit = makeQuietOctokit(token);
+  try {
+    const res = await octokit.request('GET /repos/{owner}/{repo}/actions/variables/{name}', {
+      owner, repo, name,
+    });
+    return res.data?.value ?? null;
+  } catch (err) {
+    if (err.status === 404) return null;
+    throw err;
+  }
+}
+
+/** Cria ou atualiza a variável. Devolve 'created' | 'updated'. */
+export async function setRepoVariable(token, owner, repo, name, value) {
+  const octokit = makeQuietOctokit(token);
+  try {
+    await octokit.request('POST /repos/{owner}/{repo}/actions/variables', { owner, repo, name, value });
+    return 'created';
+  } catch (err) {
+    // 409 = já existe. Criar-ou-atualizar em duas chamadas é o contrato da API:
+    // não há PUT idempotente para variables.
+    if (err.status !== 409) throw err;
+    await octokit.request('PATCH /repos/{owner}/{repo}/actions/variables/{name}', {
+      owner, repo, name, value,
+    });
+    return 'updated';
+  }
+}
+
+/** Remove a variável. Ausente já é o estado desejado: 404 é no-op. */
+export async function deleteRepoVariable(token, owner, repo, name) {
+  const octokit = makeQuietOctokit(token);
+  try {
+    await octokit.request('DELETE /repos/{owner}/{repo}/actions/variables/{name}', {
+      owner, repo, name,
+    });
+    return true;
+  } catch (err) {
+    if (err.status === 404) return false;
+    throw err;
+  }
+}