@spec-wave/cli 0.23.0 → 0.25.0

package/README.md

@@ -108,11 +108,29 @@ Arquivo em `.github/config/tech_context.yml` que descreve a stack tecnológica d
   ```bash
   gh auth refresh --scopes project,repo,workflow
   ```
-- Secret no repositório: `ANTHROPIC_API_KEY` ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
+- Secret no repositório, conforme o provider: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max) ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
 - Para repositórios em organizações: criar PAT com escopo `project` e adicionar como secret `GH_PROJECT_TOKEN`
 
 ---
 
+## 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`.
@@ -191,10 +227,10 @@ npx @spec-wave/cli@latest init --repo acme/loja --project-title "Loja — Spec W
 O `init` cria:
 - GitHub Project v2 com 12 colunas Kanban e campos personalizados (Work Item Type, Priority, Story Points, Area)
 - 20+ labels de tipo, prioridade e gatilho
-- 6 GitHub Actions workflows em `.github/workflows/`
+- 8 GitHub Actions workflows em `.github/workflows/`
 - `.spec-wave.json` com os IDs do Project
 
-Adicionar o secret de IA no GitHub: **Settings → Secrets → Actions → `ANTHROPIC_API_KEY`**.
+Adicionar o secret de IA no GitHub: **Settings → Secrets → Actions** — `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` ou `OPENROUTER_API_KEY`, conforme o provider escolhido no `init`.
 
 ---
 
@@ -408,14 +444,82 @@ Isso atualiza apenas os arquivos de workflow sem recriar o Project ou as labels.
 
 | Provider | Secret | Modelo padrão |
 |----------|--------|---------------|
-| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
-| OpenRouter | `OPENROUTER_API_KEY` | `anthropic/claude-3.7-sonnet` |
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
+| `claude-oauth` | `CLAUDE_CODE_OAUTH_TOKEN` | `claude-sonnet-4-6` |
+| `openrouter` | `OPENROUTER_API_KEY` | `anthropic/claude-3.7-sonnet` |
 
 Configurar no `init`:
 ```bash
 npx @spec-wave/cli@latest init --repo owner/repo --provider openrouter --model anthropic/claude-3.7-sonnet
 ```
 
+### `claude-oauth` — rodar tudo pela assinatura Claude Pro/Max
+
+Mesmo motor do provider `anthropic`, credencial diferente: em vez de uma chave
+de API cobrada por token, o token da sua assinatura. Os cinco workflows de IA
+(spec, plan, bug, decompose, critique) rodam assim, inclusive nos GitHub Actions
+— o binário do Claude Code vem embarcado na CLI, então o runner não precisa de
+nada além do `setup-node` que os workflows já fazem.
+
+```bash
+claude setup-token          # gere o token (escopo só de inferência)
+# cole o valor em Settings → Secrets → Actions → CLAUDE_CODE_OAUTH_TOKEN
+
+npx @spec-wave/cli@latest init --repo owner/repo --provider claude-oauth
+# ou, num repo já configurado, troque "provider" no .spec-wave.json e rode `update`
+```
+
+O consumo passa a sair do limite do seu plano — sob rate limit da assinatura o
+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

package/bin/spec-wave.mjs

@@ -128,6 +128,35 @@ program
       .catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('run')
+  .description('Executa LOCALMENTE o próximo passo do fluxo (o que a label dispararia no Actions)')
+  .argument('[issue]', 'Número da issue (Feature, Bug ou RFC)')
+  .option('--pr <n>', 'Modo PR: decide entre code-review e qa pelo estado das reviews')
+  .option('--dry-run', 'Decide e explica sem executar nada')
+  .option('--yes', 'Confirma o passo que exige confirmação')
+  .option('--apply', 'Autoriza especificamente o decompose-apply (erra se o passo pendente for outro)')
+  .option('--step <nome>', 'Força um passo: spec | plan | critique | validate | decompose | decompose-apply | bug')
+  .option('--max-steps <n>', 'Encadeia até N passos (padrão: 1)', '1')
+  .option('--force', 'Ignora o portão de label de gatilho pendente')
+  .option('--no-remote-check', 'Não consulta o remoto pelos documentos ausentes (offline)')
+  .option('--only <passo>', 'No modo --pr: roda só code-review ou só qa')
+  .option('--json', 'Imprime a decisão em JSON')
+  .action(async (issue, options) => {
+    const { run } = await import('../src/commands/run.mjs');
+    await run(issue, options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
+program
+  .command('mode')
+  .description('Mostra ou alterna o modo de execução: `actions` (workflows) ou `local` (esta máquina)')
+  .argument('[modo]', 'actions | local (sem argumento: só mostra o estado)')
+  .option('--dry-run', 'Mostra o que mudaria sem alterar nada')
+  .action(async (target, options) => {
+    const { mode } = await import('../src/commands/mode.mjs');
+    await mode({ target, ...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')
@@ -205,7 +234,7 @@ program
 
 program
   .command('generate-bug')
-  .description('Gera bug.md para um Bug (usado pelo GitHub Action)')
+  .description('Gera bug.md para um Bug — roda no GitHub Action ou localmente')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
   .action(async (options) => {
     const { generateBug } = await import('../src/commands/generate-bug.mjs');
@@ -218,7 +247,11 @@ program
   .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); });
+    // A reprova é um desfecho esperado do comando, não uma exceção — mas o exit
+    // code precisa continuar 1 para o job do Actions ficar vermelho.
+    const result = await validate(options)
+      .catch(err => { console.error(err.message); process.exit(1); });
+    if (result?.ok === false) process.exit(1);
   });
 
 program

package/package.json

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

package/src/agent/anthropic-agent.mjs

@@ -6,10 +6,10 @@
 // e da execução das tools. Por isso não há dependência direta de
 // `@anthropic-ai/sdk` aqui — não reintroduza uma.
 //
-// Consequência operacional que vale lembrar: nos GitHub Actions do spec-wave o
-// runner tem `setup-node` e mais nada. Sem o Claude Code instalado, este
-// backend NÃO roda lá — os workflows usam o OpenRouter, que é `fetch` puro.
-// Este backend serve execução local, onde o Claude Code já existe.
+// Consequência operacional que vale lembrar: o binário vem EMBARCADO no SDK
+// (dependência opcional por plataforma), então `npm install -g @spec-wave/cli`
+// basta — inclusive no runner do GitHub Actions, que só tem `setup-node`. Quem
+// confere isso antes da primeira chamada é `assertBackendRunnable` em index.mjs.
 //
 // Tudo que o processo pai aprende chega por dois canais, e os dois viram
 // observações do Langfuse manualmente:
@@ -31,6 +31,18 @@ import { TruncatedOutputError } from './errors.mjs';
 const DEFAULT_TOOLS = ['Read', 'Glob', 'Grep'];
 const MAX_TURNS = 25;
 
+// Variáveis de credencial cujo valor vazio deve ser tratado como AUSENTE.
+const CREDENTIAL_VARS = ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'];
+
+/** Cópia do ambiente sem credenciais de valor vazio (função PURA). */
+export function withoutBlankCredentials(env) {
+  const copy = { ...env };
+  for (const key of CREDENTIAL_VARS) {
+    if (copy[key] !== undefined && String(copy[key]).trim() === '') delete copy[key];
+  }
+  return copy;
+}
+
 /** Base de comparação da allowlist: absoluto resolvido, minúsculo no win32. */
 function normalizeWritePath(p) {
   const resolved = path.resolve(p);
@@ -45,22 +57,24 @@ function normalizeWritePath(p) {
  * @returns {Promise<import('./run-types.mjs').AgentRunResult>}
  */
 export async function runAnthropicAgent(prompt, options) {
-  if (options.responseSchema) {
-    // O subprocesso não expõe tool_choice forçado, então não há como garantir
-    // a tool call única que a saída estruturada exige. Falhar aqui é melhor do
-    // que devolver texto livre que o chamador tentaria parsear "na tolerância"
-    // — foi exatamente esse caminho que rebaixava um finding grave a menor.
-    throw new Error(
-      'Saída estruturada não é suportada no backend anthropic (o subprocesso do ' +
-      'Claude Code não expõe tool_choice forçado). Use o provider openrouter para ' +
-      'ações com schema — hoje, a crítica adversarial.',
-    );
-  }
-
   const { query } = await import('@anthropic-ai/claude-agent-sdk');
 
-  const tools = options.tools ?? DEFAULT_TOOLS;
-  const toolMatcher = `^(${tools.join('|')})$`;
+  // Saída estruturada: `outputFormat` faz o CLI garantir um payload conforme o
+  // schema (ele mesmo repete o turno enquanto não bater) e devolvê-lo em
+  // `structured_output` no result. Não existe equivalente ao `strict` do
+  // OpenRouter aqui — a garantia é o loop de retry do CLI, não o tipo do
+  // endpoint; por isso `responseSchema.strict` é ignorado neste backend.
+  const schema = options.responseSchema ?? null;
+  // Com schema o modelo não explora nada: a resposta é UM payload. Misturar as
+  // duas coisas daria a saída de escape de "chamar Read de novo" em vez de
+  // fechar o contrato — mesma regra do backend openrouter.
+  //
+  // O que NÃO se copia de lá é o `maxTurns: 1`: aqui o turno extra é do próprio
+  // CLI refazendo a resposta até casar com o schema (um run que deu certo
+  // reportou 2 turnos). Apertar o teto trocaria esse retry por error_max_turns.
+  const tools = schema ? [] : (options.tools ?? DEFAULT_TOOLS);
+  // `^()$` casaria com nome vazio; sem tools, o matcher não pode casar nada.
+  const toolMatcher = tools.length > 0 ? `^(${tools.join('|')})$` : '(?!)';
   const allowedWritePaths = options.allowedWritePaths?.map(normalizeWritePath) ?? null;
   const runResult = {
     resultSubtype: null,
@@ -98,6 +112,7 @@ export async function runAnthropicAgent(prompt, options) {
       const queryOptions = {
         model: options.model,
         maxTurns: options.maxTurns ?? MAX_TURNS,
+        ...(schema ? { outputFormat: { type: 'json_schema', schema: schema.jsonSchema } } : {}),
         // `tools` restringe o que o modelo sequer VÊ; `allowedTools` é só a
         // lista de auto-aprovação sobre essa superfície. Sem `tools`, as ~31
         // tools do Claude Code aparecem e são apenas aprovadas/negadas por
@@ -123,7 +138,12 @@ export async function runAnthropicAgent(prompt, options) {
               ],
             }
           : {}),
-        env: { ...process.env },
+        // `env` SUBSTITUI o ambiente do subprocesso, então o spread é obrigatório
+        // (PATH, HOME). O saneamento existe porque `${{ secrets.X }}` de um
+        // secret inexistente injeta string VAZIA: um CLAUDE_CODE_OAUTH_TOKEN=""
+        // chegando ao CLI é ambiguidade gratuita entre "não configurado" e
+        // "configurado errado".
+        env: withoutBlankCredentials(process.env),
         // Desliga o carregamento de settings do filesystem (~/.claude,
         // .claude/settings.json) para o subprocesso não herdar hooks ou
         // permissões de fora deste `queryOptions`.
@@ -290,6 +310,7 @@ export async function runAnthropicAgent(prompt, options) {
             if (message.subtype === 'success') {
               output = message.result;
               runResult.outputText = message.result;
+              if (schema) runResult.structured = message.structured_output ?? null;
               if (!quiet && !printedAnyText && message.result.trim() !== '') {
                 console.log(`\nClaude: ${message.result}`);
               }

package/src/agent/index.mjs

@@ -1,8 +1,12 @@
-// Registro de backends: transforma um provider num runner concreto.
+// Registro de backends: transforma um backend num runner concreto.
 // Porte de `agent-cli/src/workflow/backends.ts` + `src/lib.ts`.
 //
-// É o ÚNICO módulo que sabe que os dois backends existem, então um terceiro
-// provider significa mexer só aqui.
+// É o ÚNICO módulo que sabe que os dois backends existem, então um MOTOR novo
+// significa mexer só aqui. Um provider novo que reusa um motor existente
+// (`claude-oauth` sobre o backend anthropic) não passa por este arquivo — vive
+// inteiro em config.mjs.
+
+import { createRequire } from 'node:module';
 
 import { runAnthropicAgent } from './anthropic-agent.mjs';
 import { runOpenRouterAgent } from './openrouter-agent.mjs';
@@ -12,7 +16,13 @@ export { ENV_FILE_PATTERN, createToolContext, executeTool, toolDefinitionsFor, K
 export { initTelemetry, shutdownTelemetry, telemetryConfigured } from './telemetry.mjs';
 export { runAnthropicAgent, runOpenRouterAgent };
 
-export const PROVIDERS = ['anthropic', 'openrouter'];
+// Este módulo fala em BACKEND, não em provider: quem escolhe entre `anthropic`,
+// `claude-oauth` e `openrouter` é o config, e src/lib/claude.mjs traduz essa
+// escolha para o backend antes de chegar aqui. Assim um provider novo que reusa
+// um backend existente (foi o caso do claude-oauth) não encosta em src/agent/.
+export const BACKENDS = ['anthropic', 'openrouter'];
+/** @deprecated nome antigo de BACKENDS — mantido para não quebrar importadores. */
+export const PROVIDERS = BACKENDS;
 
 const RUNNERS = {
   anthropic: runAnthropicAgent,
@@ -20,16 +30,16 @@ const RUNNERS = {
 };
 
 /**
- * Runner do provider (função PURA).
+ * Runner do backend (função PURA).
  *
- * @param {'anthropic'|'openrouter'} provider
+ * @param {'anthropic'|'openrouter'} backend
  * @returns {(prompt: string, options: object) => Promise<object>}
  */
-export function runnerFor(provider) {
-  const runner = RUNNERS[provider];
+export function runnerFor(backend) {
+  const runner = RUNNERS[backend];
   if (!runner) {
     throw new Error(
-      `Provider desconhecido: "${provider}" (esperado um de: ${PROVIDERS.join(', ')}).`,
+      `Backend desconhecido: "${backend}" (esperado um de: ${BACKENDS.join(', ')}).`,
     );
   }
   return runner;
@@ -39,20 +49,31 @@ export function runnerFor(provider) {
  * Confere credenciais ANTES de qualquer chamada de modelo — um fluxo que morre
  * no meio por falta de chave já gastou dinheiro de verdade.
  *
- * O SDK aceita chave de API OU token OAuth do Claude Code; exigir só a chave
- * rejeitaria uma assinatura que funciona.
+ * A checagem é por BACKEND, e o backend anthropic aceita qualquer uma das duas
+ * credenciais: chave de API (provider `anthropic`) ou token da assinatura
+ * (provider `claude-oauth`). Quem exige a credencial CERTA para o provider
+ * escolhido é o `doctor`, que sabe qual dos dois o repo configurou.
+ *
+ * Fora do CI o backend anthropic passa mesmo sem nada no ambiente: quem está
+ * logado no Claude Code (`claude /login`) tem a credencial guardada pelo
+ * próprio CLI, não em variável, e barrar aí rejeitaria uma sessão que
+ * funciona. No Actions não existe login interativo, então lá a ausência
+ * continua sendo erro imediato.
  *
- * @param {'anthropic'|'openrouter'} provider
+ * @param {'anthropic'|'openrouter'} backend
  * @param {object} [env]
  */
-export function assertCredentials(provider, env = process.env) {
-  if (provider === 'anthropic' && !env.ANTHROPIC_API_KEY && !env.CLAUDE_CODE_OAUTH_TOKEN) {
+export function assertCredentials(backend, env = process.env) {
+  if (
+    backend === 'anthropic' && env.GITHUB_ACTIONS === 'true' &&
+    !env.ANTHROPIC_API_KEY && !env.CLAUDE_CODE_OAUTH_TOKEN
+  ) {
     throw new Error(
       'Faltam credenciais: defina ANTHROPIC_API_KEY ou CLAUDE_CODE_OAUTH_TOKEN ' +
       '(secret do repositório, em Settings → Secrets → Actions).',
     );
   }
-  if (provider === 'openrouter' && !env.OPENROUTER_API_KEY) {
+  if (backend === 'openrouter' && !env.OPENROUTER_API_KEY) {
     throw new Error(
       'Faltam credenciais: defina OPENROUTER_API_KEY ' +
       '(secret do repositório, em Settings → Secrets → Actions).',
@@ -60,49 +81,94 @@ export function assertCredentials(provider, env = process.env) {
   }
 }
 
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * Pacotes que podem carregar o binário nativo do Claude Code nesta plataforma.
+ *
+ * No linux há duas variantes de libc e o npm instala só a que casa com o host;
+ * aceitar as duas evita um falso negativo em imagem musl (Alpine).
+ *
+ * @param {NodeJS.Platform} [platform]
+ * @param {string} [arch]
+ * @returns {string[]}
+ */
+export function nativeBinaryPackages(platform = process.platform, arch = process.arch) {
+  const base = `@anthropic-ai/claude-agent-sdk-${platform}-${arch}`;
+  return platform === 'linux' ? [base, `${base}-musl`] : [base];
+}
+
+/**
+ * O binário nativo do Claude Code está instalado?
+ *
+ * @param {(id: string) => string} [resolve] injetável para teste
+ * @returns {boolean}
+ */
+export function nativeBinaryAvailable(resolve = id => requireFromHere.resolve(id)) {
+  return nativeBinaryPackages().some(pkg => {
+    try {
+      resolve(`${pkg}/package.json`);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
 /**
- * O backend pode rodar NESTE ambiente? (função PURA)
+ * O backend pode rodar NESTE ambiente?
  *
  * O backend anthropic não chama a API: `query()` sobe o **Claude Code CLI como
- * processo filho**. Os workflows do spec-wave só têm `setup-node`, então lá o
- * subprocesso não existe — e a falha nativa é um ENOENT sem relação aparente
- * com configuração de IA. Falhar aqui, com o que ajustar, custa segundos em vez
- * de uma investigação.
+ * processo filho**. O que decide se isso funciona é a presença do binário — e
+ * ele vem EMBARCADO no `@anthropic-ai/claude-agent-sdk`, como dependência
+ * opcional por plataforma (`@anthropic-ai/claude-agent-sdk-linux-x64` e
+ * companhia). Ou seja: `npm install -g @spec-wave/cli` já o traz, inclusive no
+ * runner do GitHub Actions, que só tem `setup-node`.
+ *
+ * Isto já foi um bloqueio incondicional no Actions, escrito quando o SDK ainda
+ * exigia o Claude Code instalado à parte. Checar o binário em vez do ambiente
+ * cobre a falha de verdade — `npm install --omit=optional`, plataforma sem
+ * build publicado — e libera a assinatura (provider `claude-oauth`) no CI.
+ *
+ * Fora do alcance daqui: binário presente mas com a libc errada (musl num host
+ * glibc). Aí quem falha é o spawn, e a mensagem do próprio SDK já nomeia a causa.
  *
- * Escape hatch para quem instala o Claude Code no runner:
- * `SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1`.
+ * `SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1` segue aceito como bypass — hoje inútil,
+ * mas está em workflows de quem seguiu a orientação antiga.
  *
- * @param {'anthropic'|'openrouter'} provider
+ * @param {'anthropic'|'openrouter'} backend
  * @param {object} [env]
  */
-export function assertBackendRunnable(provider, env = process.env) {
-  if (provider !== 'anthropic') return;
-  if (env.GITHUB_ACTIONS !== 'true') return;
+export function assertBackendRunnable(backend, env = process.env) {
+  if (backend !== 'anthropic') return;
   if (env.SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI) return;
+  if (nativeBinaryAvailable()) return;
   throw new Error(
-    'O provider `anthropic` não roda no GitHub Actions: ele não chama a API — sobe o ' +
-    'Claude Code CLI como subprocesso, que não existe no runner (só há setup-node).\n\n' +
+    'O backend `anthropic` sobe o Claude Code CLI como subprocesso, e o binário nativo ' +
+    `não está instalado (procurado em: ${nativeBinaryPackages().join(', ')}).\n\n` +
     'Saídas:\n' +
-    '  1. Troque para o OpenRouter no .spec-wave.json:  "ai": { "provider": "openrouter", ' +
-    '"model": "anthropic/claude-opus-4.8" }  e adicione o secret OPENROUTER_API_KEY;\n' +
-    '  2. ou instale o Claude Code no workflow e defina SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1.\n\n' +
-    'Localmente o provider `anthropic` funciona normalmente.',
+    '  1. Reinstale o CLI SEM `--omit=optional` (o binário é uma dependência opcional ' +
+    'por plataforma do @anthropic-ai/claude-agent-sdk);\n' +
+    '  2. ou troque para o OpenRouter no .spec-wave.json:  "ai": { "provider": "openrouter", ' +
+    '"model": "anthropic/claude-opus-4.8" }  e adicione o secret OPENROUTER_API_KEY.',
   );
 }
 
 /**
- * Executa uma ação de IA no provider escolhido.
+ * Executa uma ação de IA no backend escolhido.
  *
  * É o ponto único por onde `lib/claude.mjs` fala com o motor: os dois backends
- * implementam o mesmo contrato, então quem chama nunca ramifica por provider.
+ * implementam o mesmo contrato, então quem chama nunca ramifica por backend.
+ * O campo continua se chamando `provider` por compatibilidade com o contrato do
+ * agent-cli de origem, mas o valor esperado é o BACKEND.
  *
  * @param {string} prompt conteúdo do usuário
  * @param {import('./run-types.mjs').AgentRunOptions & {provider: string}} options
  * @returns {Promise<import('./run-types.mjs').AgentRunResult>}
  */
 export async function runAgent(prompt, options) {
-  const { provider, ...rest } = options;
-  assertBackendRunnable(provider);
-  assertCredentials(provider);
-  return runnerFor(provider)(prompt, rest);
+  const { provider: backend, ...rest } = options;
+  assertBackendRunnable(backend);
+  assertCredentials(backend);
+  return runnerFor(backend)(prompt, rest);
 }

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;
+  }
+}

package/src/commands/decompose.mjs

@@ -33,7 +33,8 @@ import {
 import { recordUsage } from '../lib/usage-report.mjs';
 import { formatDependencyLine, orderStories, renderOrderComment } from '../lib/dependencies.mjs';
 import { lintLanguage } from '../lib/output-lint.mjs';
-import { slugify } from '../lib/slugify.mjs';
+import { resolveDocDir } from '../lib/doc-paths.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
@@ -222,14 +223,6 @@ export function resolveInheritedMilestone(issue) {
   return Number.isInteger(number) && number > 0 ? number : undefined;
 }
 
-// Diretório do documento por tipo. Feature usa o mesmo docs/features/<slug> da
-// spec/plan; RFC ganha o seu, já que não passa por spec/plan.
-function resolveDocDir(root, issue, type) {
-  const slug = slugify(issue.title);
-  const rel = type === 'RFC' ? `docs/rfcs/${slug}` : `docs/features/${slug}`;
-  return { slug, rel, dir: path.resolve(root || process.cwd(), rel) };
-}
-
 // Lint de idioma sobre títulos+corpos gerados; retorna aviso pronto para
 // anexar ao comentário final ('' se limpo).
 function formatItemsLintWarning(texts) {
@@ -262,7 +255,7 @@ async function draftDecomposition(ctx) {
   const { token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode, docDir, docPath, docRel } = ctx;
   const number = parseInt(issueNumber, 10);
   const kind = DECOMPOSE_TARGETS[type]; // Feature → 'stories'; RFC → 'tasks'
-  const blobUrl = `https://github.com/${owner}/${repo}/blob/main/${docRel}`;
+  const blobUrl = docBlobUrl({ owner, repo, pathRel: docRel, mode: runMode, root });
 
   const specPath = path.join(docDir, 'spec.md');
   const planPath = path.join(docDir, 'plan.md');