@spec-wave/cli 0.24.0 → 0.26.0

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

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

@@ -13,6 +13,7 @@ import {
   tokenMismatchWarning, parseActiveAccount,
 } from '../api/auth.mjs';
 import { getProjectSnapshot, listSubIssues } from '../api/github-graphql.mjs';
+import { getRepoVariable } from '../api/github-rest.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, AI_PROVIDERS, STATUS_OPTIONS,
   RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
@@ -20,6 +21,8 @@ import {
   modelLabels,
 } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
+import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
+import { unguardedWorkflows } from './mode.mjs';
 import {
   DEFAULT_MAX_TOKENS, supportsStrictSchema, resolveAiConfig,
 } from '../lib/claude.mjs';
@@ -936,6 +939,34 @@ export function checkSpecKit(ctx) {
   };
 }
 
+// Modo de execução: o config e a variável do repositório precisam concordar.
+// Discordar não é detalhe — é o usuário achando que desligou os workflows e
+// continuando a pagar minutos (ou o contrário: tudo pulado e nada rodando).
+async function checkExecutionMode(ctx) {
+  const name = 'Modo de execução (Actions × local)';
+  const configured = configuredMode(ctx.cfg);
+
+  let variable; // undefined = não verificável
+  if (ctx.token && ctx.cfg?.owner && ctx.cfg?.repo) {
+    try {
+      variable = await getRepoVariable(ctx.token, ctx.cfg.owner, ctx.cfg.repo, EXECUTION_VARIABLE);
+    } catch (err) {
+      variable = undefined;
+      if (err.status !== 403 && err.status !== 404) {
+        return { name, status: 'warn', detail: `Variável não verificável agora: ${err.message}` };
+      }
+    }
+  }
+
+  const estado = describeModeState({
+    configured,
+    variable,
+    unguardedWorkflows: unguardedWorkflows(ctx.root || ctx.cwd),
+  });
+  const status = estado.status === 'problem' ? 'fail' : estado.status;
+  return { name, status, detail: [estado.summary, ...estado.notes, ...estado.fixes].join('\n') };
+}
+
 async function checkWorkflows(ctx) {
   const name = 'Workflows do Actions';
   // Ancorado na raiz do projeto, não no cwd: rodar o doctor de um subdiretório
@@ -1037,6 +1068,7 @@ export async function doctor() {
     checkDecompositions,
     checkSpecKit,
     checkWorkflows,
+    checkExecutionMode,
   ];
   const results = [];
   const spinner = p.spinner();

package/src/commands/generate-bug.mjs

@@ -15,11 +15,11 @@ import {
 import { generateDocument } from '../lib/claude.mjs';
 import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
-import { loadConfig } from '../lib/project-root.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
-import { commitGenerated, executionMode } from '../lib/flow-run.mjs';
+import { commitGenerated, resolveFlowContext } from '../lib/flow-run.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 import {
   runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
 } from '../lib/critique.mjs';
@@ -48,18 +48,12 @@ function isSpecWaveComment(body) {
 
 export async function generateBug({ issueNumber }) {
   const token = await resolveToken();
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const { root } = loadConfig();
+  // Mesmo contexto dos outros geradores: GITHUB_REPOSITORY quando existe, o
+  // `.spec-wave.json` quando não. Este comando exigia a env crua e morria fora
+  // do runner mandando exportá-la — dentro de um repo que já sabe seu owner/repo.
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-bug' });
   const n = parseInt(issueNumber, 10);
 
-  if (!owner || !repo) {
-    throw new Error(
-      'GITHUB_REPOSITORY env var não definida.\n' +
-      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
-      '  GITHUB_REPOSITORY=owner/repo spec-wave generate-bug --issue-number 1'
-    );
-  }
-
   console.log(`Buscando issue #${n}...`);
   const issue = await getIssue(token, owner, repo, n);
 
@@ -126,7 +120,7 @@ export async function generateBug({ issueNumber }) {
       filePath: fileAbs,
       content,
       message: `docs: generate bug.md for ${slug} [spec-wave]`,
-      mode: executionMode(),
+      mode,
     });
     if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
@@ -142,7 +136,7 @@ export async function generateBug({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, n,
       '🐞 **bug.md gerado automaticamente!**\n\n' +
-      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root, config })})\n\n` +
       'Revise a **causa raiz** e o **teste de regressão** — são as duas seções que decidem se ' +
       'a correção ataca o defeito ou o sintoma. Quando estiver pronto, valide com:\n' +
       `\`\`\`\ngh issue edit ${n} --add-label "spec-wave:ready"\n\`\`\`` +

package/src/commands/generate-plan.mjs

@@ -20,6 +20,7 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { resolveFromRoot } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 
@@ -213,7 +214,7 @@ export async function generatePlan({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **plan.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root, config })})\n\n` +
       `Revise o plano e, quando estiver pronto, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\`` +
       formatLintWarning(lintFindings)

package/src/commands/generate-spec.mjs

@@ -7,6 +7,7 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { resolveFromRoot } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
@@ -110,7 +111,7 @@ export async function generateSpec({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **spec.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root })})\n\n` +
       `Revise a especificação e, quando estiver pronto, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:plan"\n\`\`\`` +
       formatLintWarning(lintFindings)