@spec-wave/cli 0.23.0 → 0.24.0

package/README.md

@@ -108,7 +108,7 @@ 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`
 
 ---
@@ -191,10 +191,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 +408,34 @@ 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.
+
 ---
 
 ## Licença

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.23.0",
+  "version": "0.24.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/commands/doctor.mjs

@@ -14,7 +14,7 @@ import {
 } from '../api/auth.mjs';
 import { getProjectSnapshot, listSubIssues } from '../api/github-graphql.mjs';
 import {
-  CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
+  CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, AI_PROVIDERS, STATUS_OPTIONS,
   RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS, recommendedModelAliases,
   modelLabels,
@@ -679,8 +679,9 @@ async function checkAi(ctx) {
       `${Object.entries(aliases).map(([a, m]) => `${a}=${m}`).join(', ')}.`
     );
     // Slug da OpenRouter tem "/" (anthropic/claude-…); id da Anthropic, não.
+    // O critério é o BACKEND: `claude-oauth` fala com a mesma API do `anthropic`.
     const wrongShape = Object.entries(aliases).filter(([, m]) => (
-      provider.value === 'openrouter' ? !String(m).includes('/') : String(m).includes('/')
+      provider.backend === 'openrouter' ? !String(m).includes('/') : String(m).includes('/')
     ));
     if (wrongShape.length > 0) {
       status = 'warn';
@@ -700,7 +701,7 @@ async function checkAi(ctx) {
 
   // Saída estruturada da crítica: sem structured output confiável, a validação
   // do schema queima os retries antes de falhar.
-  if (provider.value === 'openrouter' && !fileAi.models?.critique) {
+  if (provider.backend === 'openrouter' && !fileAi.models?.critique) {
     status = 'warn';
     notes.push(
       `Saída estruturada da crítica: o provider é openrouter e \`ai.models.critique\` não está ` +
@@ -708,21 +709,27 @@ async function checkAi(ctx) {
       'e a crítica falha na primeira execução. Aponte `ai.models.critique` para um modelo com ' +
       'saída estruturada.'
     );
+  } else if (provider.backend === 'anthropic') {
+    // No backend anthropic quem garante o schema é o próprio Claude Code
+    // (`outputFormat: json_schema`), repetindo o turno até casar — não há
+    // tool call forçado nem `strict` de endpoint para reportar.
+    notes.push(
+      `Saída estruturada da crítica: json_schema do Claude Code (${provider.value}) ` +
+      '— o CLI repete o turno até a resposta casar com o schema.'
+    );
   } else {
     notes.push(
       `Saída estruturada da crítica: tool call forçado (${provider.value}) ` +
       `· strict=${supportsStrictSchema(critiqueModel) ? 'sim' : 'não'} neste modelo.`
     );
   }
-  // O backend anthropic não chama a API — sobe o Claude Code CLI como
-  // subprocesso, que não existe no runner dos workflows (só há setup-node).
-  if (provider.value === 'anthropic') {
-    problems.push(
-      'O provider `anthropic` NÃO roda nos GitHub Actions: ele sobe o Claude Code CLI como ' +
-      'subprocesso, ausente no runner. As Actions de spec/plan/decompose vão falhar. ' +
-      'Troque para `"provider": "openrouter"` no .spec-wave.json (e adicione o secret ' +
-      'OPENROUTER_API_KEY), ou instale o Claude Code no workflow e defina ' +
-      'SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1. Localmente o anthropic funciona.'
+  // O backend anthropic sobe o Claude Code CLI como subprocesso — e o binário
+  // vem embarcado no SDK, então o runner não precisa de instalação extra.
+  if (provider.backend === 'anthropic') {
+    notes.push(
+      `Backend anthropic (${provider.value}): o Claude Code sobe como subprocesso a partir do ` +
+      'binário embarcado no @anthropic-ai/claude-agent-sdk — nada a instalar no runner além do ' +
+      'próprio CLI. Só falha se o pacote for instalado com `--omit=optional`.'
     );
   }
 
@@ -955,10 +962,19 @@ async function checkWorkflows(ctx) {
   // comportamento de pipelines já em andamento.
   const unpinned = [];
   const otherVersion = [];
+  // O secret do provider escolhido chega ao runner? A YAML é que decide: um
+  // repo configurado com um provider cujo secret o workflow não encaminha morre
+  // com "Faltam credenciais" no meio do fluxo, e o único conserto é `update`.
+  const provider = getProvider(ctx.cfg?.ai?.provider) || getProvider(DEFAULT_PROVIDER);
+  const missingSecret = [];
   for (const file of WORKFLOW_FILES) {
     const content = readFileSync(path.join(dir, file), 'utf-8');
     if (/@spec-wave\/cli@latest/.test(content)) unpinned.push(file);
     else if (!content.includes(`@spec-wave/cli@${CLI_VERSION}`)) otherVersion.push(file);
+    // Identifica os workflows de IA pelo que eles próprios declaram, em vez de
+    // manter uma segunda lista para sair de sincronia com WORKFLOW_FILES.
+    const usesAi = AI_PROVIDERS.some(pr => content.includes(`secrets.${pr.secret}`));
+    if (usesAi && !content.includes(`secrets.${provider.secret}`)) missingSecret.push(file);
   }
   const notes = [`Os ${WORKFLOW_FILES.length} workflows do spec-wave estão presentes.`];
   let status = 'ok';
@@ -976,6 +992,16 @@ async function checkWorkflows(ctx) {
       'para fazer o bump explícito.'
     );
   }
+  if (missingSecret.length > 0) {
+    status = 'fail';
+    notes.push(
+      `Não encaminham \`${provider.secret}\` (secret do provider ${provider.value}): ` +
+      `${missingSecret.join(', ')}. Esses workflows vão falhar com "Faltam credenciais" — ` +
+      'rode `npx @spec-wave/cli@latest update`.'
+    );
+  } else {
+    notes.push(`Todos encaminham \`${provider.secret}\` (provider ${provider.value}).`);
+  }
   return { name, status, detail: notes.join('\n') };
 }
 

package/src/commands/init.mjs

@@ -220,6 +220,11 @@ export async function init(options) {
       ? `  1. Commite o ${CONFIG_FILE} quando quiser (git add ${CONFIG_FILE} && git commit)\n`
       : '') +
     `  ${configWritten ? '2' : '1'}. Adicione ${providerMeta.secret} como secret no repositório (provider: ${providerMeta.label})\n` +
+    // O valor do token da assinatura não é copiável de lugar nenhum: só existe
+    // depois de rodar o comando que o gera.
+    (providerMeta.secret === 'CLAUDE_CODE_OAUTH_TOKEN'
+      ? `     ${chalk.dim('Gere o valor com: claude setup-token')}\n`
+      : '') +
     `  ${configWritten ? '3' : '2'}. Configure o board view para agrupar por "Etapa"\n` +
     `  ${configWritten ? '4' : '3'}. Crie uma Feature com o prefixo [FEATURE] no título\n` +
     `  ${configWritten ? '5' : '4'}. Use a skill spec-wave para guiar o fluxo\n\n` +

package/src/config.mjs

@@ -11,17 +11,36 @@ export const PORTAL_URL = 'https://spec-wave.astratech.net.br';
 // O provider e o modelo escolhidos no `init` são persistidos em .spec-wave.json
 // (bloco `ai`) e lidos em runtime por src/lib/claude.mjs. Cada provider declara
 // o secret do GitHub Actions de onde a chave é lida.
+//
+// `value` é o que o usuário escolhe; `backend` é QUEM executa (src/agent/).
+// Os dois não coincidem: `anthropic` e `claude-oauth` rodam no mesmo backend e
+// diferem só na credencial — chave de API por token vs. token da assinatura.
+// Separar os campos evita que cada consumidor tenha que decorar essa relação.
 export const AI_PROVIDERS = [
   {
     value: 'anthropic',
+    backend: 'anthropic',
     label: 'Anthropic (API direta)',
     hint: 'Usa o secret ANTHROPIC_API_KEY',
     secret: 'ANTHROPIC_API_KEY',
     defaultModel: 'claude-sonnet-4-6',
     modelHint: 'ex.: claude-sonnet-4-6, claude-opus-4-1',
   },
+  {
+    // Mesmo backend do `anthropic`, credencial diferente: o token da assinatura
+    // Claude Pro/Max (`claude setup-token`), com escopo só de inferência. O
+    // consumo sai do limite do plano, não de crédito por token.
+    value: 'claude-oauth',
+    backend: 'anthropic',
+    label: 'Claude (assinatura Pro/Max via OAuth)',
+    hint: 'Usa o secret CLAUDE_CODE_OAUTH_TOKEN — gere com `claude setup-token`',
+    secret: 'CLAUDE_CODE_OAUTH_TOKEN',
+    defaultModel: 'claude-sonnet-4-6',
+    modelHint: 'ex.: claude-sonnet-4-6, claude-opus-4-1',
+  },
   {
     value: 'openrouter',
+    backend: 'openrouter',
     label: 'OpenRouter (multi-modelo)',
     hint: 'Usa o secret OPENROUTER_API_KEY',
     secret: 'OPENROUTER_API_KEY',
@@ -49,10 +68,12 @@ export const MODEL_LABEL_PREFIX = 'spec-wave:model:';
 // `spec-wave:model:<apelido>` cubra "roda de novo num modelo mais forte" sem
 // obrigar cada projeto a inventar a própria nomenclatura.
 //
-// O mapa é POR PROVIDER porque o formato do id não é o mesmo: a OpenRouter usa
-// slug com "/" (anthropic/claude-opus-5) e a API da Anthropic usa o id nu
-// (claude-opus-5). Sugerir o formato errado geraria exatamente o aviso de
-// "apelido com formato incompatível" que o doctor emite na linha seguinte.
+// O mapa é POR BACKEND, não por provider, porque o que ele distingue é o
+// formato do id: a OpenRouter usa slug com "/" (anthropic/claude-opus-5) e a
+// Anthropic usa o id nu (claude-opus-5). Sugerir o formato errado geraria
+// exatamente o aviso de "apelido com formato incompatível" que o doctor emite
+// na linha seguinte. `anthropic` e `claude-oauth` compartilham o mesmo mapa
+// porque compartilham o backend.
 export const RECOMMENDED_MODEL_ALIASES = {
   openrouter: {
     opus: 'anthropic/claude-opus-5',
@@ -78,7 +99,17 @@ export const RECOMMENDED_MODEL_ALIASES = {
  * @returns {Record<string,string>}
  */
 export function recommendedModelAliases(provider) {
-  return RECOMMENDED_MODEL_ALIASES[provider] || RECOMMENDED_MODEL_ALIASES[DEFAULT_PROVIDER];
+  return RECOMMENDED_MODEL_ALIASES[providerBackend(provider)];
+}
+
+/**
+ * Backend que executa um provider (função PURA).
+ *
+ * @param {string} [value] valor de `ai.provider`
+ * @returns {'anthropic'|'openrouter'}
+ */
+export function providerBackend(value) {
+  return (getProvider(value) || getProvider(DEFAULT_PROVIDER)).backend;
 }
 
 // Quantas críticas seguidas podem reprovar a mesma issue antes de exigir revisão

package/src/lib/claude.mjs

@@ -109,6 +109,9 @@ export function resolveAiConfig({ env = {}, fileAi = {}, action, labels = [], mo
 
   return {
     provider: meta.value,
+    // Quem executa. `anthropic` e `claude-oauth` caem no mesmo backend e
+    // diferem só na credencial — src/agent/ nunca vê essa distinção.
+    backend: meta.backend,
     model: rawModel.trim(),
     modelSource,
     labelAlias,
@@ -359,7 +362,7 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
 // Extraída do generateDocument para o generateStructured usar a mesma contagem.
 function recordUsageEntry(opts, ai, { inputTokens, outputTokens, cost }) {
   if (!Array.isArray(opts.usage)) return;
-  const finalCost = cost === null && ai.provider === 'anthropic'
+  const finalCost = cost === null && ai.backend === 'anthropic'
     ? computeCost({ model: ai.model, inputTokens, outputTokens, pricing: ai.pricing })
     : cost;
   opts.usage.push({
@@ -507,7 +510,7 @@ async function generateViaEngine(
   systemPrompt, userContent, ai, { temperature, maxTokens, maxTurns, schema, strict, action, tools },
 ) {
   const result = await runAgent(userContent, {
-    provider: ai.provider,
+    provider: ai.backend,
     model: ai.model,
     systemPromptAppend: systemPrompt,
     // Sessão/usuário alimentam o agrupamento das traces no Langfuse. Sem
@@ -536,7 +539,14 @@ async function generateViaEngine(
     if (result.structured === null || result.structured === undefined) {
       const err = new Error(
         `O modelo ${ai.model} não devolveu a saída estruturada "${schema.name}" ` +
-        `(subtype=${result.resultSubtype}).`
+        `(subtype=${result.resultSubtype}).` +
+        (result.resultSubtype === 'error_max_structured_output_retries'
+          // Subtype só do backend anthropic: o CLI repetiu o turno e a saída
+          // nunca bateu com o schema. Repetir tende a resolver; se insistir, o
+          // modelo é que não dá conta do contrato.
+          ? ' O Claude Code esgotou as tentativas de casar a resposta com o schema —' +
+            ' se repetir, aponte `ai.models.critique` para um modelo mais forte.'
+          : '')
       );
       err.transient = true; // repetir a mesma requisição costuma resolver
       throw err;

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",

package/src/plugin/skills/doctor/SKILL.md

@@ -43,7 +43,7 @@ npx @spec-wave/cli@latest doctor
    - escopo faltando → o usuário roda `!gh auth refresh --scopes project,repo,workflow` (interativo, ele executa)
    - `.spec-wave.json` dessincronizado → `npx @spec-wave/cli@latest refresh --config`
    - workflows/labels divergentes → skill **update**
-   - secret de IA ausente → Settings → Secrets → Actions (`ANTHROPIC_API_KEY` ou `OPENROUTER_API_KEY`)
+   - secret de IA ausente → Settings → Secrets → Actions (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` ou `OPENROUTER_API_KEY`, conforme o provider)
    - `specKit.command` ausente → configure antes de usar a skill **implement**
 3. Trate `!` como "não deu para verificar", não como falha.
 4. Se tudo passar e o problema original persistir, aí sim investigue a superfície específica (Action, issue, board).

package/src/plugin/skills/setup/SKILL.md

@@ -58,7 +58,7 @@ Você dirige o `init` **com flags**. Nunca rode `npx @spec-wave/cli@latest init`
 
 8. **Adapte o `tech_context.yml`** — o scaffold vem com dados de exemplo e a qualidade do `plan.md` depende dele. Ofereça ajustá-lo agora; o passo a passo está na skill **plan** (`reference/tech-context.md`).
 
-9. **Secret de IA:** instrua a adicionar em Settings → Secrets → Actions a chave do provider escolhido: `ANTHROPIC_API_KEY` (Anthropic) ou `OPENROUTER_API_KEY` (OpenRouter).
+9. **Secret de IA:** instrua a adicionar em Settings → Secrets → Actions a credencial do provider escolhido: `ANTHROPIC_API_KEY` (Anthropic), `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max — gere com `claude setup-token`) ou `OPENROUTER_API_KEY` (OpenRouter).
 
 10. **Próximo passo:** criar a primeira Feature — skill **issue**.
 

package/src/templates/skill/SKILL.md

@@ -459,7 +459,7 @@ Configura o spec-wave no repositório. Você dirige o `init` com flags — **nun
    Use `--skip-project` / `--skip-labels` / `--skip-files` **apenas** para re-rodar uma fase específica que falhou antes.
 7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
 8. **Adapte o `tech_context.yml`**: o scaffold vem com dados de exemplo. Ofereça ajustá-lo à stack real do repo seguindo a seção **Tech Context** (perto do comando `/spec-wave plan`) — isso melhora muito a qualidade do `plan.md`.
-9. Instrua o usuário a adicionar a chave de IA como secret no repositório (Settings → Secrets → Actions): `ANTHROPIC_API_KEY` (Anthropic) ou `OPENROUTER_API_KEY` (OpenRouter), conforme o provider escolhido no `init`.
+9. Instrua o usuário a adicionar a credencial de IA como secret no repositório (Settings → Secrets → Actions): `ANTHROPIC_API_KEY` (Anthropic), `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max — gere com `claude setup-token`) ou `OPENROUTER_API_KEY` (OpenRouter), conforme o provider escolhido no `init`.
 
 ---
 

package/src/templates/workflows/critique.yml

@@ -51,5 +51,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           GITHUB_REPOSITORY: ${{ github.repository }}

package/src/templates/workflows/decompose.yml

@@ -76,5 +76,6 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           GITHUB_REPOSITORY: ${{ github.repository }}

package/src/templates/workflows/generate-bug.yml

@@ -56,5 +56,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           GITHUB_REPOSITORY: ${{ github.repository }}

package/src/templates/workflows/generate-plan.yml

@@ -64,5 +64,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           GITHUB_REPOSITORY: ${{ github.repository }}

package/src/templates/workflows/generate-spec.yml

@@ -64,5 +64,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
           GITHUB_REPOSITORY: ${{ github.repository }}