@spec-wave/cli 0.24.0 → 0.25.0

package/README.md

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

package/bin/spec-wave.mjs

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

package/package.json

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

package/src/api/github-rest.mjs

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

package/src/commands/decompose.mjs

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

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)

package/src/commands/mode.mjs

@@ -0,0 +1,169 @@
+// Alterna entre rodar o fluxo no GitHub Actions e rodar nesta máquina.
+//
+// O comando escreve os DOIS lados do interruptor — o `.spec-wave.json`, que a
+// CLI e a skill leem, e a variável de repositório, que o `if:` de cada job
+// avalia. Escrever só um deles é o defeito que o comando existe para evitar:
+// config em "local" com a variável ausente significa workflow disparando e
+// minuto sendo cobrado enquanto o usuário acha que desligou.
+//
+// A variável exige permissão de administração. Sem ela o comando NÃO finge que
+// deu certo: grava o config, diz o que falta e aponta a alternativa manual.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import { getRepoVariable, setRepoVariable, deleteRepoVariable } from '../api/github-rest.mjs';
+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,
+} from '../lib/execution-mode.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+
+/**
+ * Workflows instalados que NÃO carregam a guarda (função quase pura — só lê o fs).
+ *
+ * @param {string|null} root
+ * @returns {string[]}
+ */
+export function unguardedWorkflows(root) {
+  const dir = path.join(root || process.cwd(), '.github', 'workflows');
+  if (!existsSync(dir)) return [];
+  const presentes = new Set(readdirSync(dir));
+  return WORKFLOW_FILES
+    .filter(file => presentes.has(file))
+    .filter(file => !readFileSync(path.join(dir, file), 'utf-8').includes(EXECUTION_GUARD));
+}
+
+// A variável só é legível por quem administra o repo. 403 não é falha: é "não
+// verificável", e quem chama distingue isso de "não existe" (null).
+async function readVariable(token, owner, repo) {
+  try {
+    return await getRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+  } catch (err) {
+    if (err.status === 403 || err.status === 404) return undefined;
+    throw err;
+  }
+}
+
+export async function mode({ target, dryRun = false } = {}) {
+  p.intro(chalk.bold('spec-wave mode'));
+
+  const { config, root, configPath } = loadConfig();
+  if (!config) {
+    p.log.error(`${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` antes.`);
+    process.exit(1);
+  }
+
+  const alvo = target ? String(target).toLowerCase() : null;
+  if (alvo && !EXECUTION_MODES.includes(alvo)) {
+    p.log.error(`Modo inválido: ${alvo}. Use um de: ${EXECUTION_MODES.join(', ')}.`);
+    process.exit(1);
+  }
+
+  const atual = configuredMode(config);
+  const owner = config.owner;
+  const repo = config.repo;
+
+  let token = null;
+  let variavel;
+  if (owner && repo) {
+    try {
+      token = await resolveToken();
+      variavel = await readVariable(token, owner, repo);
+    } catch (err) {
+      p.log.warn(`Não foi possível consultar a variável do repositório: ${err.message}`);
+      variavel = undefined;
+    }
+  }
+
+  // Sem argumento: só relatório.
+  if (!alvo) {
+    const estado = describeModeState({
+      configured: atual, variable: variavel, unguardedWorkflows: unguardedWorkflows(root),
+    });
+    p.log.info(estado.summary);
+    for (const nota of estado.notes) p.log.message(`• ${nota}`);
+    for (const fix of estado.fixes) p.log.warn(fix);
+    p.outro(
+      atual === 'local'
+        ? `Próximo passo de uma issue: ${chalk.cyan('spec-wave run <issue>')}`
+        : `Para desligar o CI: ${chalk.cyan('spec-wave mode local')}`
+    );
+    return { mode: atual, variable: variavel, changed: false };
+  }
+
+  const esperado = variableValueFor(alvo);
+  const mudaConfig = atual !== alvo;
+  const mudaVariavel = variavel !== undefined && variavel !== 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 };
+  }
+
+  if (dryRun) {
+    if (mudaConfig) p.log.info(`${CONFIG_FILE}: execution.mode ${atual} → ${alvo}`);
+    if (mudaVariavel) {
+      p.log.info(esperado === null
+        ? `Variável ${EXECUTION_VARIABLE}: remover (valor atual: ${variavel})`
+        : `Variável ${EXECUTION_VARIABLE}: definir como "${esperado}"`);
+    }
+    p.outro('Dry-run: nada foi alterado.');
+    return { mode: atual, variable: variavel, changed: false };
+  }
+
+  if (mudaConfig) {
+    const { changed } = updateConfig(cfg => {
+      cfg.execution = { ...(cfg.execution || {}), mode: alvo };
+    }, { cwd: root || process.cwd() });
+    if (changed) p.log.success(`${CONFIG_FILE} atualizado: execution.mode = ${alvo}`);
+  }
+
+  let variavelOk = true;
+  if (token && owner && repo) {
+    try {
+      if (esperado === null) {
+        const removida = await deleteRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+        p.log.success(removida
+          ? `Variável ${EXECUTION_VARIABLE} removida — os workflows voltam a disparar.`
+          : `Variável ${EXECUTION_VARIABLE} já não existia.`);
+      } else {
+        await setRepoVariable(token, owner, repo, EXECUTION_VARIABLE, esperado);
+        p.log.success(`Variável ${EXECUTION_VARIABLE}=${esperado} — os jobs passam a ser pulados (0 minutos).`);
+      }
+    } catch (err) {
+      variavelOk = false;
+      p.log.error(
+        `Não foi possível escrever a variável ${EXECUTION_VARIABLE} (${err.status || ''} ${err.message}).\n` +
+        'Ela exige administração no repositório — peça a um admin, ou defina em ' +
+        'Settings → Secrets and variables → Actions → Variables.'
+      );
+    }
+  } else {
+    variavelOk = false;
+    p.log.warn(`Sem owner/repo ou token: só o ${CONFIG_FILE} foi atualizado.`);
+  }
+
+  const semGuarda = unguardedWorkflows(root);
+  if (alvo === 'local' && semGuarda.length > 0) {
+    p.log.warn(
+      `Estes workflows instalados ainda não têm a guarda \`${EXECUTION_GUARD}\` e vão rodar mesmo assim: ` +
+      `${semGuarda.join(', ')}. Rode \`npx @spec-wave/cli@latest update\`.`
+    );
+  }
+
+  p.log.message(chalk.dim(`Commite o ${configPath ? path.basename(configPath) : CONFIG_FILE} — quem clona o repo lê a versão versionada.`));
+  p.outro(
+    alvo === 'local'
+      ? `Modo local. Conduza o fluxo com ${chalk.cyan('spec-wave run <issue>')}.`
+      : 'Modo actions. As labels de gatilho voltam a disparar os workflows.'
+  );
+  return { mode: alvo, variable: esperado, changed: true, variableApplied: variavelOk };
+}