@spec-wave/cli 0.25.0 → 0.26.0

package/bin/spec-wave.mjs

@@ -1,378 +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('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')
-  .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 — 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');
-    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');
-    // 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
-  .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.25.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/cli.mjs

@@ -0,0 +1,400 @@
+// Superfície da CLI: monta o programa do Commander e o devolve SEM executá-lo.
+//
+// Vive aqui, e não no `bin/`, porque o `bin/` executa (`parse()`) — importá-lo
+// para introspecção dispararia a CLI. Com a montagem separada, o gerador da
+// documentação (`apps/docs/scripts/generate-reference.mjs`) e os testes leem
+// `program.commands` diretamente, em vez de parsear o texto do `--help`.
+
+import { Command } from 'commander';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dir, '..', 'package.json'), 'utf-8'));
+
+/**
+ * Monta o programa do Commander com todos os comandos (função sem efeito).
+ *
+ * NÃO chama `.parse()` — quem executa é o `bin/spec-wave.mjs`.
+ *
+ * @returns {Command}
+ */
+export function buildProgram() {
+  const program = new Command();
+
+  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('./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('./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('./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('./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('./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('./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('./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('./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('./commands/triage.mjs');
+      await triage({ action, issue, ...options })
+        .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('./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('./commands/mode.mjs');
+      const result = await mode({ target, ...options })
+        .catch(err => { console.error(err.message); process.exit(1); });
+      // Escrever só o config é meio-interruptor: a CLI passa a agir como local
+      // e os workflows continuam disparando. O comando já avisa em vermelho,
+      // mas sair 0 fazia qualquer script (ou agente) que o encadeasse ler
+      // sucesso — e seguir em frente achando que o CI estava desligado.
+      if (result?.variableApplied === false) 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('./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('./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('./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('./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('./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('./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 — roda no GitHub Action ou localmente')
+    .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+    .action(async (options) => {
+      const { generateBug } = await import('./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('./commands/validate.mjs');
+      // 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
+    .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('./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('./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('./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('./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('./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('./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('./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('./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('./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('./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('./commands/doctor.mjs');
+      await doctor().catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  return program;
+}

package/src/commands/decompose.mjs

@@ -157,16 +157,27 @@ const CHILD_PREFIX = { Feature: '[STORY]', RFC: '[TASK]' };
 /**
  * Modo do run (função PURA — testável).
  *
- * A flag `--apply` vem do workflow, onde a label que disparou é a fonte de
- * verdade. O fallback por label cobre a execução manual e o retry de runner.
+ * TRI-ESTADO, e a distinção é o que impede um estrago: `apply` pode ser `true`
+ * (aplique), `false` (NÃO aplique) ou `undefined` (ninguém decidiu — use a
+ * label). Só o `undefined` cai no fallback por label, que é o caminho do
+ * workflow (onde a label que disparou é a fonte de verdade) e do retry de
+ * runner.
+ *
+ * Antes, o default `apply = false` colapsava "não aplique" em "ninguém
+ * decidiu": o `run` despachava o rascunho com `apply: false` e a label
+ * `spec-wave:decompose-apply` esquecida na issue por uma Action que falhou
+ * promovia a execução a aplicação. O comando anunciava "gera/re-critica o
+ * rascunho" e CRIAVA Stories e Tasks — sem passar pelo portão de confirmação
+ * do `run`, que existe exatamente para isso.
  *
  * @param {object} params
  * @param {Array<string|{name:string}>} [params.labels] labels da issue
- * @param {boolean} [params.apply] flag --apply
+ * @param {boolean} [params.apply] `true`/`false` decidem; `undefined` consulta a label
  * @returns {'draft'|'apply'}
  */
-export function resolveDecomposeMode({ labels = [], apply = false } = {}) {
-  if (apply) return 'apply';
+export function resolveDecomposeMode({ labels = [], apply } = {}) {
+  if (apply === true) return 'apply';
+  if (apply === false) return 'draft';
   return labelNames(labels).includes(LABEL_DECOMPOSE_APPLY) ? 'apply' : 'draft';
 }
 
@@ -917,7 +928,10 @@ export function renderApplyFailureComment({ trigger, message, createdItems = [],
     'Complete o que falta à mão, ou apague as issues acima antes de tentar de novo.';
 }
 
-export async function decompose({ issueNumber, apply = false }) {
+// `apply` SEM default: `undefined` significa "ninguém decidiu" e é o que faz o
+// fallback por label valer no workflow. Um default `false` aqui reintroduziria
+// o bug, porque a CLI passa `undefined` quando a flag não é usada.
+export async function decompose({ issueNumber, apply }) {
   const token = await resolveToken();
   // PROJECT_TOKEN deve ter scope "project" para atualizar GitHub Projects v2.
   // Fallback para GITHUB_TOKEN (só funciona em repos pessoais sem org restrictions).

package/src/commands/mode.mjs

@@ -21,7 +21,7 @@ import { CONFIG_FILE, WORKFLOW_FILES } from '../config.mjs';
 import { updateConfig } from '../lib/config-file.mjs';
 import {
   EXECUTION_MODES, EXECUTION_VARIABLE, EXECUTION_GUARD,
-  configuredMode, variableValueFor, describeModeState,
+  configuredMode, variableValueFor, describeModeState, shouldWriteVariable,
 } from '../lib/execution-mode.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 
@@ -100,20 +100,31 @@ export async function mode({ target, dryRun = false } = {}) {
 
   const esperado = variableValueFor(alvo);
   const mudaConfig = atual !== alvo;
-  const mudaVariavel = variavel !== undefined && variavel !== esperado;
+  // `undefined` é "não deu para LER" (403 — a variável exige admin), e não
+  // "está como deveria". Tratar os dois iguais fazia o comando pular a escrita
+  // e ainda assim anunciar que config e variável coincidiam: o usuário saía
+  // achando que desligou o CI, com os workflows armados e o minuto sendo
+  // cobrado — exatamente o meio-caminho que este comando existe para evitar.
+  //
+  // Não conseguir ler quase sempre significa não conseguir escrever. Tentar e
+  // falhar com a mensagem certa é honesto; não tentar e dizer "coincidem" não.
+  const mudaVariavel = shouldWriteVariable({ variable: variavel, expected: esperado });
 
   if (!mudaConfig && !mudaVariavel) {
     p.log.success(`Já está em ${chalk.bold(alvo)} — config e variável do repositório coincidem.`);
     p.outro('Nada a fazer.');
-    return { mode: alvo, variable: variavel, changed: false };
+    return { mode: alvo, variable: variavel, changed: false, variableApplied: true };
   }
 
   if (dryRun) {
     if (mudaConfig) p.log.info(`${CONFIG_FILE}: execution.mode ${atual} → ${alvo}`);
     if (mudaVariavel) {
+      const atualDaVariavel = variavel === undefined
+        ? 'valor atual desconhecido — sem permissão para ler'
+        : `valor atual: ${variavel === null ? 'ausente' : variavel}`;
       p.log.info(esperado === null
-        ? `Variável ${EXECUTION_VARIABLE}: remover (valor atual: ${variavel})`
-        : `Variável ${EXECUTION_VARIABLE}: definir como "${esperado}"`);
+        ? `Variável ${EXECUTION_VARIABLE}: remover (${atualDaVariavel})`
+        : `Variável ${EXECUTION_VARIABLE}: definir como "${esperado}" (${atualDaVariavel})`);
     }
     p.outro('Dry-run: nada foi alterado.');
     return { mode: atual, variable: variavel, changed: false };

package/src/commands/run.mjs

@@ -26,7 +26,7 @@ import { existsOnRemote } from '../lib/doc-availability.mjs';
 import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
 import { isActionsRun, resolveFlowContext } from '../lib/flow-run.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { nextStep, resolveForcedStep, STEPS } from '../lib/next-step.mjs';
+import { nextStep, resolveForcedStep, stepDocs, docsForType, STEPS } from '../lib/next-step.mjs';
 import { nextPrStep, reviewVerdict } from '../lib/pr-step.mjs';
 import { configuredMode } from '../lib/execution-mode.mjs';
 import { labelNames } from '../config.mjs';
@@ -41,8 +41,44 @@ const LOCK_STALE_MS = 30 * 60 * 1000;
 // comentário de uso. Fica em .git/ porque já é ignorado e é por clone.
 // ---------------------------------------------------------------------------
 
-function lockPath(root, key) {
-  return path.join(root || process.cwd(), '.git', 'spec-wave', `run-${key}.lock`);
+/**
+ * Diretório .git COMPARTILHADO do clone (função com I/O, isolada para teste).
+ *
+ * Montar `<root>/.git` à mão assume que `.git` é um diretório — e num git
+ * worktree ele é um ARQUIVO com `gitdir: <caminho real>`. O `mkdirSync` do
+ * acquireLock estourava ENOTDIR ali, derrubando TODO `spec-wave run` de dentro
+ * de um worktree, inclusive `--dry-run`, antes de qualquer trabalho.
+ *
+ * `--git-common-dir` e não `--git-dir`: num worktree o `--git-dir` é
+ * `.git/worktrees/<nome>`, o que tornaria o lock por WORKTREE. Dois `run` na
+ * mesma issue em worktrees diferentes rodariam em paralelo commitando na mesma
+ * branch — exatamente o que este lock existe para impedir. O comum preserva o
+ * "é por clone" que o comentário acima declara.
+ *
+ * O caminho devolvido é RELATIVO ao cwd quando se está no clone principal
+ * (`.git` na raiz, `../../.git` num subdiretório) e absoluto de dentro de um
+ * worktree — daí o `path.resolve`. Sem ele, rodar de um subdiretório criaria um
+ * `.git/` novo ali dentro, que é um estrago pior e mais silencioso que o ENOTDIR.
+ *
+ * @param {string} [root] raiz do projeto (a do .spec-wave.json)
+ * @returns {string} caminho absoluto do diretório .git compartilhado
+ */
+export function gitCommonDir(root) {
+  const cwd = root || process.cwd();
+  try {
+    const out = execSync('git rev-parse --git-common-dir', {
+      cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (out) return path.resolve(cwd, out);
+  } catch {
+    // Fora de um repositório git: cai no palpite antigo. O `run` vai falhar
+    // adiante de qualquer forma (ele commita e faz push), e com mensagem melhor.
+  }
+  return path.join(cwd, '.git');
+}
+
+export function lockPath(root, key) {
+  return path.join(gitCommonDir(root), 'spec-wave', `run-${key}.lock`);
 }
 
 function acquireLock(root, key) {
@@ -126,12 +162,34 @@ function localDocStates(issue, type, root) {
  * clone. É a diferença entre "ainda não foi gerado" e "foi gerado e você não
  * puxou" — a segunda leva a sobrescrever trabalho publicado.
  */
-async function probeRemote({ decision, docs, docPaths, token, owner, repo }) {
-  const step = STEPS[decision.action];
-  if (!step) return docs;
-  const alvos = [step.writes, ...step.reads]
-    .filter(Boolean)
-    .filter(doc => docs[doc] === 'missing');
+/**
+ * Documentos que vale sondar no remoto antes de acreditar na decisão (PURA).
+ *
+ * O G5 ("as labels afirmam um documento que não existe aqui") diz, com todas as
+ * letras, que o arquivo *não está no clone nem no remoto* — e manda renomear o
+ * diretório ou REGERAR. Enquanto a sonda só rodava para decisão não-bloqueada,
+ * essa frase era afirmada sem nunca ter perguntado ao remoto: num clone que
+ * está apenas atrás, o conselho levava a regerar por cima de um documento
+ * publicado, gastando uma chamada de IA para destruir o artefato bom. A
+ * correção certa era `git pull`.
+ *
+ * Nesse caso o passo é `none` e não há `writes`/`reads` de onde tirar a lista —
+ * sondamos os documentos do tipo.
+ *
+ * @param {{action: string, blocked: object|null}} decision
+ * @param {string|null} type
+ * @returns {string[]}
+ */
+export function docsToProbe(decision, type) {
+  if (decision.blocked?.code === 'inconsistent-state') return docsForType(type);
+  if (decision.blocked || !STEPS[decision.action]) return [];
+  // stepDocs e não `[writes, ...reads]`: `validate` e `decompose` leem
+  // documentos diferentes conforme o tipo, e sondar a lista errada devolve um
+  // `docs` que o G6 aprova por engano.
+  return stepDocs(decision.action, type);
+}
+
+async function probeRemote({ alvos, docs, docPaths, token, owner, repo }) {
   if (alvos.length === 0) return docs;
 
   const atualizado = { ...docs };
@@ -180,6 +238,32 @@ function parityWarnings(issue, type) {
 // Despacho
 // ---------------------------------------------------------------------------
 
+/**
+ * Saída de `--json` (função PURA — devolve o texto, não imprime).
+ *
+ * UM documento, sempre. A impressão morava dentro do laço de passos, então
+ * `--max-steps N` emitia N documentos JSON concatenados — saída que nenhum
+ * parser aceita, numa flag que a skill anuncia justamente para ramificar
+ * programaticamente.
+ *
+ * O desfecho fica no TOPO, e não só dentro de `steps`: é o que quase todo
+ * consumidor lê, e é exatamente o formato que a execução de um passo só já
+ * produzia. Assim a correção não quebra quem já lia `.action`.
+ *
+ * @param {object} params
+ * @param {string|number} params.issueNumber
+ * @param {string|null} params.type
+ * @param {object|null} params.ultimaDecisao
+ * @param {object[]} [params.passos]
+ * @returns {string} JSON indentado
+ */
+export function renderRunJson({ issueNumber, type, ultimaDecisao, passos = [] }) {
+  return JSON.stringify(
+    { issue: Number(issueNumber), type: type ?? null, ...ultimaDecisao, steps: passos },
+    null, 2,
+  );
+}
+
 async function dispatch(action, { issueNumber }) {
   switch (action) {
     case 'generate-spec': {
@@ -315,6 +399,9 @@ export async function run(issueArg, options = {}) {
   const exitCodeAntes = process.exitCode;
   try {
     let ultimaDecisao = null;
+    // `--json` acumula e imprime UMA vez no fim (ver renderRunJson).
+    const passos = [];
+    let ultimoTipo = null;
 
     for (let i = 0; i < teto; i++) {
       const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
@@ -342,9 +429,12 @@ export async function run(issueArg, options = {}) {
       };
 
       let decision = nextStep({ ...entrada, docs });
-      if (remoteCheck && decision.action !== 'none' && !decision.blocked) {
-        const docsRemotos = await probeRemote({ decision, docs, docPaths, token, owner, repo });
-        decision = nextStep({ ...entrada, docs: docsRemotos });
+      if (remoteCheck) {
+        const alvos = docsToProbe(decision, type).filter(doc => docs[doc] === 'missing');
+        if (alvos.length > 0) {
+          const docsRemotos = await probeRemote({ alvos, docs, docPaths, token, owner, repo });
+          decision = nextStep({ ...entrada, docs: docsRemotos });
+        }
       }
       ultimaDecisao = decision;
 
@@ -357,7 +447,8 @@ export async function run(issueArg, options = {}) {
         );
       }
 
-      if (json) console.log(JSON.stringify({ issue: Number(issueNumber), type, ...decision }, null, 2));
+      ultimoTipo = type;
+      if (json) passos.push(decision);
       else reportDecision(decision, { issueNumber, type, title: issue.title, warnings: parityWarnings(issue, type) });
 
       if (decision.blocked) { process.exitCode = 2; break; }
@@ -389,6 +480,10 @@ export async function run(issueArg, options = {}) {
       }
     }
 
+    if (json) {
+      console.log(renderRunJson({ issueNumber, type: ultimoTipo, ultimaDecisao, passos }));
+    }
+
     return ultimaDecisao;
   } finally {
     releaseLock(lock);

package/src/lib/execution-mode.mjs

@@ -49,6 +49,28 @@ export function variableValueFor(mode) {
   return mode === 'local' ? 'local' : null;
 }
 
+/**
+ * A variável do repositório precisa ser escrita? (função PURA)
+ *
+ * Três estados entram, não dois: `string` (valor lido), `null` (lida, e não
+ * existe) e `undefined` (NÃO deu para ler — 403, a variável exige admin).
+ *
+ * `undefined` conta como "precisa escrever". Tratá-lo como "já está certo"
+ * fazia o comando pular a escrita e ainda anunciar que config e variável
+ * coincidiam — o usuário saía achando que desligou o CI, com os workflows
+ * armados. Não conseguir ler quase sempre significa não conseguir escrever;
+ * tentar e falhar com a mensagem certa é honesto, não tentar e declarar
+ * sucesso não é.
+ *
+ * @param {object} params
+ * @param {string|null|undefined} params.variable valor remoto
+ * @param {string|null} params.expected valor que o modo-alvo exige (null = ausente)
+ * @returns {boolean}
+ */
+export function shouldWriteVariable({ variable, expected }) {
+  return variable !== expected;
+}
+
 /**
  * Diagnóstico do modo de execução (função PURA).
  *

package/src/lib/next-step.mjs

@@ -44,11 +44,21 @@ export const STEPS = {
     types: ['Feature'], creates: false, ai: true,
   },
   validate: {
+    // `reads` DEPENDE DO TIPO: a validação de Feature abre spec.md e plan.md, a
+    // de Bug abre bug.md. Declarar `[]` aqui desarmava o G6 justamente para o
+    // passo que só lê do disco — um clone atrasado reprovava uma Feature cujo
+    // plan.md existia no remoto, removia `spec-wave:ready` e comentava a falha
+    // na issue. Dano a estado COMPARTILHADO por uma condição puramente local.
     trigger: LABEL_READY, cli: 'validate', writes: null, reads: [],
+    readsByType: { Feature: ['spec', 'plan'], Bug: ['bug'] },
     types: ['Feature', 'Bug'], creates: false, ai: false,
   },
   decompose: {
+    // O rascunho de Feature é montado a partir de spec.md + plan.md; o de RFC
+    // não usa nenhum dos dois. Com `[]` e o plan só no remoto, o decompose
+    // gerava o rascunho com o plano VAZIO — sem erro, só pior.
     trigger: LABEL_DECOMPOSE, cli: 'decompose', writes: 'decomposition', reads: [],
+    readsByType: { Feature: ['spec', 'plan'], RFC: [] },
     types: ['Feature', 'RFC'], creates: false, ai: true,
   },
   'decompose-apply': {
@@ -71,13 +81,60 @@ export const STEPS = {
   },
 };
 
+/**
+ * Documentos que um passo LÊ, para um tipo de item (função PURA).
+ *
+ * Existe porque dois passos leem coisas diferentes conforme o tipo — `validate`
+ * abre spec+plan numa Feature e bug.md num Bug — e o G6 precisa da lista CERTA:
+ * ele é o que impede o passo de rodar contra um clone atrasado. Uma lista
+ * subdeclarada não causa erro visível, causa o passo rodando com o arquivo
+ * errado (ou ausente), que é o modo de falha caro.
+ *
+ * @param {string} action nome da ação em STEPS
+ * @param {string|null} [type] tipo do work item
+ * @returns {string[]} documentos lidos
+ */
+export function stepReads(action, type) {
+  const step = STEPS[action];
+  if (!step) return [];
+  return step.readsByType?.[type] ?? step.reads;
+}
+
+/**
+ * Documentos que um passo TOCA (lê ou escreve), para um tipo (função PURA).
+ *
+ * É a lista que o G6, o aviso de "não deu para consultar o remoto" e a sonda do
+ * `run` precisam — os três erravam junto quando `reads` estava subdeclarado.
+ *
+ * @param {string} action
+ * @param {string|null} [type]
+ * @returns {string[]}
+ */
+export function stepDocs(action, type) {
+  return [STEPS[action]?.writes, ...stepReads(action, type)].filter(Boolean);
+}
+
+/**
+ * Documentos que um tipo usa (função PURA).
+ *
+ * O `run` precisa disto para sondar o remoto quando a decisão veio BLOQUEADA e
+ * o passo é `none` — aí não há `writes`/`reads` de onde tirar a lista, e é
+ * justamente o caso em que o G5 afirma "não está no clone nem no remoto".
+ *
+ * @param {string|null} [type]
+ * @returns {string[]}
+ */
+export function docsForType(type) {
+  return DOCS_BY_TYPE[type] || [];
+}
+
 /** Tipos que o `run` sabe conduzir. Story/Task/Epic/Spike não têm passo de documento. */
 export const RUNNABLE_TYPES = ['Feature', 'Bug', 'RFC'];
 
 const TRIGGERS = Object.values(STEPS).map(s => s.trigger).filter(Boolean);
 
 /** Documentos que cada tipo usa, na ordem em que o fluxo os produz. */
-const DOCS_BY_TYPE = {
+export const DOCS_BY_TYPE = {
   Feature: ['spec', 'plan', 'decomposition'],
   RFC: ['decomposition'],
   Bug: ['bug'],
@@ -244,7 +301,7 @@ export function nextStep({
 
   // G6 — documento que o passo lê ou escreve existe só no remoto. Gerar por cima
   // levaria o `pull --rebase` do commit a brigar com o documento bom.
-  for (const doc of [step.writes, ...step.reads].filter(Boolean)) {
+  for (const doc of stepDocs(action, type)) {
     if (docState(docs, doc) === 'remote') {
       return decided(action, `\`${pathOf(doc)}\` existe no repositório mas não no seu clone.`, params,
         block('stale-checkout',
@@ -285,8 +342,7 @@ export function nextStep({
         'Confirme com `--yes` se é isso mesmo.'));
   }
 
-  const incertos = [step.writes, ...step.reads]
-    .filter(Boolean)
+  const incertos = stepDocs(action, type)
     .filter(doc => docState(docs, doc) === 'unknown');
   const aviso = incertos.length > 0
     ? ` (não foi possível consultar o remoto por ${incertos.map(pathOf).join(', ')} — ` +

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

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.25.0",
+  "version": "0.26.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/run/SKILL.md

@@ -26,7 +26,7 @@ npx @spec-wave/cli@latest mode actions    # volta tudo para o CI
    npx @spec-wave/cli@latest run <issue> --dry-run
    ```
 2. Mostre ao usuário o passo, o motivo e o comando que rodaria. **Só então** execute sem a flag.
-3. `--json` devolve a mesma decisão em JSON, quando você precisar ramificar programaticamente.
+3. `--json` devolve a decisão em JSON, quando você precisar ramificar programaticamente. É **um** documento: o desfecho no topo (`action`, `command`, `blocked`) e a sequência inteira em `steps` — útil com `--max-steps`.
 
 ## O que o `run` decide sozinho