@spec-wave/cli 0.16.0 → 0.16.1

package/bin/spec-wave.mjs

@@ -163,7 +163,7 @@ program
 
 program
   .command('generate-plan')
-  .description('Gera plan.md para uma Feature (usado pelo GitHub Action)')
+  .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');
@@ -172,7 +172,7 @@ program
 
 program
   .command('generate-spec')
-  .description('Gera spec.md para uma Feature (usado pelo GitHub Action)')
+  .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');
@@ -199,7 +199,7 @@ program
 
 program
   .command('decompose')
-  .description('Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado (usado pelo GitHub Action)')
+  .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) => {

package/package.json

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

package/src/api/github-graphql.mjs

@@ -33,6 +33,23 @@ export async function createProject(token, ownerId, title) {
   return { projectId: project.id, projectNumber: project.number, projectUrl: project.url, statusFieldId: statusField?.id };
 }
 
+/**
+ * Reescreve as opções de um campo single-select.
+ *
+ * ⚠️ O `id` de cada opção é OBRIGATÓRIO para as que já existem. Sem ele o
+ * GitHub CRIA uma opção nova com o mesmo nome e id diferente — e todo item do
+ * board que apontava para a opção antiga fica SEM VALOR, em silêncio.
+ *
+ * Foi exatamente o que aconteceu no smoke test do RFC-004: as 11 etapas
+ * existentes foram preservadas por NOME, os ids mudaram todos, e a Feature que
+ * estava em 🎯 Priorizado apareceu sem Etapa. Preservar o nome não preserva
+ * nada — o que liga um item à opção é o id.
+ *
+ * @param {string} token
+ * @param {string} fieldId
+ * @param {Array<{name: string, color: string, id?: string}>} options
+ *   Opções na ordem final. Com `id` = preserva a existente; sem `id` = cria.
+ */
 export async function updateStatusField(token, fieldId, options) {
   const client = makeClient(token);
   await client(`
@@ -51,7 +68,12 @@ export async function updateStatusField(token, fieldId, options) {
     }
   `, {
     fieldId,
-    options: options.map(o => ({ name: o.name, color: o.color, description: '' })),
+    options: options.map(o => ({
+      ...(o.id ? { id: o.id } : {}),
+      name: o.name,
+      color: o.color,
+      description: '',
+    })),
   });
 }
 

package/src/commands/decompose.mjs

@@ -33,6 +33,7 @@ import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
+import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
 import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 import {
   renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
@@ -194,18 +195,11 @@ function formatItemsLintWarning(texts) {
   return `\n\n⚠️ possíveis artefatos de idioma nos itens gerados: ${excerpts}`;
 }
 
-// Grava e commita o rascunho — mesmo padrão do generate-plan (o workflow roda
-// com contents: write e checkout com token).
-function commitFile(filePath, content, message) {
-  mkdirSync(path.dirname(filePath), { recursive: true });
-  writeFileSync(filePath, content, 'utf-8');
-  const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-  git('git config user.email "spec-wave[bot]@github.com"');
-  git('git config user.name "spec-wave[bot]"');
-  git(`git add "${filePath}"`);
-  git(`git commit -m "${message}"`);
-  git('git pull --rebase');
-  git('git push');
+// Grava e commita o rascunho. O modo (actions|local) decide identidade do git e
+// o que fazer com falha de push — ver `lib/flow-run.mjs`.
+function commitFile(filePath, content, message, mode) {
+  const published = commitGenerated({ filePath, content, message, mode });
+  if (published.warning) console.warn(`⚠️  ${published.warning}`);
 }
 
 // Os prompts vivem em `src/plugin/skills/decompose/model-prompt.{feature,rfc}.md`
@@ -218,7 +212,7 @@ function commitFile(filePath, content, message) {
 // ---------------------------------------------------------------------------
 
 async function draftDecomposition(ctx) {
-  const { token, owner, repo, issue, issueNumber, type, labels, usage, root, docDir, docPath, docRel } = 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}`;
@@ -267,7 +261,7 @@ async function draftDecomposition(ctx) {
       stories: generated.stories || [],
       tasks: generated.tasks || [],
     });
-    commitFile(docPath, markdown, `docs: rascunho de decomposição de ${docRel} [spec-wave]`);
+    commitFile(docPath, markdown, `docs: rascunho de decomposição de ${docRel} [spec-wave]`, runMode);
     console.log(`Rascunho commitado em ${docRel}.`);
   }
 
@@ -589,15 +583,9 @@ export async function decompose({ issueNumber, apply = false }) {
   // PROJECT_TOKEN deve ter scope "project" para atualizar GitHub Projects v2.
   // Fallback para GITHUB_TOKEN (só funciona em repos pessoais sem org restrictions).
   const projectToken = process.env.PROJECT_TOKEN || token;
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-
-  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 decompose --issue-number 1'
-    );
-  }
+  // Roda nos dois modos: no Action (disparado por label) e na sessão local.
+  const { owner, repo, mode: runMode } = resolveFlowContext({ command: 'decompose' });
+  console.log(`Modo de execução: ${runMode}`);
 
   const number = parseInt(issueNumber, 10);
   const issue = await getIssue(token, owner, repo, number);
@@ -669,7 +657,7 @@ export async function decompose({ issueNumber, apply = false }) {
   const usageEntries = [];
   const ctx = {
     token, projectToken, owner, repo, issue, issueNumber, type, labels, comments,
-    root, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    root, runMode, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
     escalationModel: config?.ai?.escalationModel || null,
     maxCritiqueAttempts:
       Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0

package/src/commands/generate-plan.mjs

@@ -1,6 +1,5 @@
-import { execSync } from 'node:child_process';
 import path from 'node:path';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import {
   getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
@@ -16,7 +15,8 @@ import {
 } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { loadConfig, resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 
@@ -109,16 +109,9 @@ async function critiquePlan({
 
 export async function generatePlan({ issueNumber }) {
   const token = await resolveToken();
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const { config, root } = loadConfig();
-
-  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-plan --issue-number 1'
-    );
-  }
+  // Roda nos dois modos: no Action (disparado por label) e na sessão local.
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-plan' });
+  console.log(`Modo de execução: ${mode}`);
 
   console.log(`Buscando issue #${issueNumber}...`);
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
@@ -180,17 +173,13 @@ export async function generatePlan({ issueNumber }) {
       usage: usageEntries,
     });
 
-    mkdirSync(featureDir, { recursive: true });
-    writeFileSync(filePath, content, 'utf-8');
-
-    // Commit and push
-    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-    git(`git config user.email "spec-wave[bot]@github.com"`);
-    git(`git config user.name "spec-wave[bot]"`);
-    git(`git add "${filePath}"`);
-    git(`git commit -m "docs: generate plan.md for ${slug} [spec-wave]"`);
-    git('git pull --rebase');
-    git('git push');
+    const published = commitGenerated({
+      filePath,
+      content,
+      message: `docs: generate plan.md for ${slug} [spec-wave]`,
+      mode,
+    });
+    if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
     // Remove trigger label
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan');

package/src/commands/generate-spec.mjs

@@ -1,12 +1,11 @@
-import { execSync } from 'node:child_process';
 import path from 'node:path';
-import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { loadConfig, resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFromRoot } from '../lib/project-root.mjs';
+import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
 import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
@@ -30,16 +29,9 @@ function formatLintWarning(lintFindings) {
 
 export async function generateSpec({ issueNumber }) {
   const token = await resolveToken();
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const { root } = loadConfig();
-
-  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-spec --issue-number 1'
-    );
-  }
+  // Roda nos dois modos: no Action (disparado por label) e na sessão local.
+  const { owner, repo, root, mode } = resolveFlowContext({ command: 'generate-spec' });
+  console.log(`Modo de execução: ${mode}`);
 
   console.log(`Buscando issue #${issueNumber}...`);
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
@@ -95,17 +87,13 @@ export async function generateSpec({ issueNumber }) {
       usage: usageEntries,
     });
 
-    mkdirSync(featureDir, { recursive: true });
-    writeFileSync(filePath, content, 'utf-8');
-
-    // Commit and push
-    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-    git(`git config user.email "spec-wave[bot]@github.com"`);
-    git(`git config user.name "spec-wave[bot]"`);
-    git(`git add "${filePath}"`);
-    git(`git commit -m "docs: generate spec.md for ${slug} [spec-wave]"`);
-    git('git pull --rebase');
-    git('git push');
+    const published = commitGenerated({
+      filePath,
+      content,
+      message: `docs: generate spec.md for ${slug} [spec-wave]`,
+      mode,
+    });
+    if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
     // Remove trigger label
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');

package/src/commands/refresh.mjs

@@ -18,28 +18,38 @@ const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json')
  * board mais as etapas canônicas que faltam, cada uma na posição canônica. Nada
  * é removido — nem coluna inventada, nem etapa descontinuada.
  *
- * O motivo é o contrato da API: `updateProjectV2Field` SUBSTITUI o conjunto de
- * opções do single-select, e a preservação do valor de cada item do board
- * depende de a opção continuar existindo com o mesmo nome. Uma opção que some
- * leva junto a Etapa de todo item que estava nela — silenciosamente. Remover
- * coluna continua sendo trabalho manual, feito com os itens já esvaziados.
+ * ⚠️ E cada opção existente leva seu **id** junto. O contrato da API é o que
+ * torna isso obrigatório: `updateProjectV2Field` SUBSTITUI o conjunto de
+ * opções, e o que liga um item do board a uma opção é o ID — não o nome. Uma
+ * opção reenviada sem id é RECRIADA com id novo, e todo item que estava nela
+ * fica sem Etapa, em silêncio.
  *
- * @param {string[]} current nomes das opções hoje no board, na ordem atual
+ * A versão anterior preservava só o nome. No smoke test do RFC-004 isso apagou
+ * a Etapa de uma Feature que estava em 🎯 Priorizado, enquanto o comando
+ * relatava "nenhuma é removida" — verdade sobre os nomes, mentira sobre o
+ * board.
+ *
+ * @param {Record<string, string>} current opções hoje no board: nome → id
  * @param {Array<{name: string, color: string}>} canonical STATUS_OPTIONS
- * @returns {{ missing: string[], preserved: string[], ordered: Array<{name: string, color: string}> }}
+ * @returns {{ missing: string[], preserved: string[],
+ *             ordered: Array<{name: string, color: string, id?: string}> }}
  */
 export function planStageSync(current, canonical) {
-  const have = new Set(current || []);
+  const atual = current || {};
+  const idDe = (name) => atual[name];
   const canonicalNames = new Set(canonical.map(o => o.name));
 
-  const missing = canonical.filter(o => !have.has(o.name)).map(o => o.name);
+  const missing = canonical.filter(o => !idDe(o.name)).map(o => o.name);
   // Colunas que o board tem e o fluxo canônico não conhece (inventadas ou
   // descontinuadas). Vão para o fim, preservando a ordem relativa que tinham.
-  const preserved = (current || []).filter(name => !canonicalNames.has(name));
+  const preserved = Object.keys(atual).filter(name => !canonicalNames.has(name));
 
   const ordered = [
-    ...canonical.map(o => ({ name: o.name, color: o.color })),
-    ...preserved.map(name => ({ name, color: 'GRAY' })),
+    ...canonical.map(o => {
+      const id = idDe(o.name);
+      return id ? { name: o.name, color: o.color, id } : { name: o.name, color: o.color };
+    }),
+    ...preserved.map(name => ({ name, color: 'GRAY', id: atual[name] })),
   ];
   return { missing, preserved, ordered };
 }
@@ -61,7 +71,9 @@ async function syncStages(token, snapshot, options) {
     return false;
   }
 
-  const current = Object.keys(etapa.options || {});
+  // Mapa nome → id: é o id que preserva o vínculo dos itens com a opção.
+  const current = etapa.options || {};
+  const nomesAntes = Object.keys(current);
   const { missing, preserved, ordered } = planStageSync(current, STATUS_OPTIONS);
 
   if (missing.length === 0) {
@@ -74,7 +86,7 @@ async function syncStages(token, snapshot, options) {
     (preserved.length
       ? `${chalk.dim('=')} preservar (fora do fluxo canônico): ${preserved.join(', ')}\n`
       : '') +
-    `${chalk.dim('=')} preservar (canônicas já presentes): ${current.length - preserved.length}\n\n` +
+    `${chalk.dim('=')} preservar (canônicas já presentes): ${nomesAntes.length - preserved.length}\n\n` +
     chalk.dim(`Resultado: ${ordered.length} opções. Nenhuma é removida.`),
     'Plano para o campo "Etapa"'
   );
@@ -115,8 +127,13 @@ async function syncStages(token, snapshot, options) {
     p.log.warn(`Campo atualizado, mas a verificação falhou: ${err.message}`);
     return true;
   }
-  const now = Object.keys(after?.fields?.['Etapa']?.options || {});
-  const lost = current.filter(name => !now.includes(name));
+  const depois = after?.fields?.['Etapa']?.options || {};
+  const now = Object.keys(depois);
+  const lost = nomesAntes.filter(name => !now.includes(name));
+  // A verificação que importa: o ID de cada opção preexistente tem que ser o
+  // MESMO. Conferir só o nome era o que deixava passar o pior desfecho — as 12
+  // opções presentes, todos os ids trocados, e o board inteiro sem Etapa.
+  const recriadas = nomesAntes.filter(name => depois[name] && depois[name] !== current[name]);
   const stillMissing = STATUS_OPTIONS.map(o => o.name).filter(name => !now.includes(name));
   spinner.stop(`Campo "Etapa" com ${now.length} opções.`);
 
@@ -128,6 +145,15 @@ async function syncStages(token, snapshot, options) {
     process.exitCode = 1;
     return false;
   }
+  if (recriadas.length > 0) {
+    p.log.error(
+      `Opções RECRIADAS com id novo: ${recriadas.join(', ')}. Os itens que estavam nelas ` +
+      'perderam a Etapa — reposicione-os no board. Isto é um bug do comando, não do seu ' +
+      'Project: reporte com a saída acima.'
+    );
+    process.exitCode = 1;
+    return false;
+  }
   if (stillMissing.length > 0) {
     p.log.warn(`Etapas canônicas ainda ausentes: ${stillMissing.join(', ')}.`);
     return true;

package/src/lib/flow-run.mjs

@@ -0,0 +1,145 @@
+// Modo de execução do fluxo: GitHub Actions ou sessão local.
+//
+// `generate-spec`, `generate-plan` e `decompose` nasceram como comandos de
+// Action e exigiam `GITHUB_REPOSITORY`, recusando qualquer execução fora do
+// runner. Mas eles são só comandos — o que os prendia ao CI era a resolução de
+// owner/repo, não o trabalho em si. Agora o MESMO comando roda nos dois lugares:
+// dentro do Action, disparado por label, ou na sua sessão do agente.
+//
+// O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), não por flag: um
+// comando com dois nomes para a mesma coisa envelhece mal.
+//
+// **O comportamento é deliberadamente IDÊNTICO nos dois modos** — gera, commita,
+// dá pull --rebase, faz push, comenta na issue e avança a Etapa. O board é a
+// fonte de verdade do RFC-001 independentemente de onde a geração rodou; um modo
+// local que não sincronizasse o board deixaria o próximo passo do fluxo cego.
+//
+// Duas diferenças existem, e as duas são de SEGURANÇA, não de resultado:
+//
+//  1. IDENTIDADE DO GIT. O Action roda `git config user.email "spec-wave[bot]"`
+//     sem `--global`, o que grava em `.git/config`. Num runner descartável isso
+//     é inócuo; no seu clone, mudaria o autor de TODOS os seus commits futuros
+//     naquele repositório. Localmente a sua identidade é preservada.
+//  2. FALHA DE PUSH. No Action, não conseguir publicar é falha do job. Local, o
+//     arquivo já está gerado e commitado — perder isso porque o remoto andou
+//     seria pior que avisar e deixar você resolver o push.
+
+import { execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveRepoContext } from './project-root.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+
+/** Rodando dentro do GitHub Actions? (função PURA) */
+export function isActionsRun(env = process.env) {
+  return env.GITHUB_ACTIONS === 'true';
+}
+
+/** 'actions' | 'local' (função PURA) */
+export function executionMode(env = process.env) {
+  return isActionsRun(env) ? 'actions' : 'local';
+}
+
+/**
+ * Resolve owner/repo + modo, ou lança com a instrução certa para cada contexto.
+ *
+ * Nos Actions o `GITHUB_REPOSITORY` vem do runner; local, o `.spec-wave.json`
+ * gravado pelo `init` é a fonte. `resolveRepoContext` já cobre os dois.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.command] nome do comando, para a mensagem de erro
+ * @param {object} [opts.env]
+ * @returns {{owner: string, repo: string, root: string|null, config: object|null, mode: 'actions'|'local'}}
+ */
+export function resolveFlowContext({ cwd = process.cwd(), command = 'este comando', env = process.env } = {}) {
+  // Repassa o `env` recebido: sem isso o modo local fica intestável dentro do
+  // GitHub Actions, que define GITHUB_REPOSITORY em toda execução.
+  const { owner, repo, root, config } = resolveRepoContext(cwd, env);
+  const mode = executionMode(env);
+
+  if (!owner || !repo) {
+    throw new Error(
+      'Não foi possível determinar owner/repo.\n' +
+      (mode === 'actions'
+        ? 'No GitHub Actions, o runner define GITHUB_REPOSITORY — verifique o workflow.'
+        : `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`), ` +
+          `ou defina GITHUB_REPOSITORY=owner/repo:\n` +
+          `  GITHUB_REPOSITORY=owner/repo spec-wave ${command} --issue-number 1`)
+    );
+  }
+  return { owner, repo, root, config, mode };
+}
+
+/**
+ * Grava um arquivo gerado e o publica: commit + pull --rebase + push.
+ *
+ * Era o mesmo bloco copiado em `generate-spec`, `generate-plan` e `decompose`,
+ * com a identidade do bot embutida. Centralizado aqui para que a diferença
+ * entre os modos exista num lugar só.
+ *
+ * O commit é escopado ao caminho (`git commit -- <arquivo>`): sem isso, qualquer
+ * coisa que você já tivesse no index entraria junto no commit do spec-wave —
+ * irrelevante num runner limpo, nada irrelevante no seu clone.
+ *
+ * @param {object} params
+ * @param {string} params.filePath caminho absoluto do arquivo
+ * @param {string} params.content
+ * @param {string} params.message mensagem de commit
+ * @param {'actions'|'local'} params.mode
+ * @returns {{committed: boolean, pushed: boolean, warning: string|null}}
+ */
+export function commitGenerated({ filePath, content, message, mode }) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content, 'utf-8');
+
+  const git = (cmd, opts = {}) => execSync(cmd, { stdio: 'inherit', ...opts });
+  const gitQuiet = (cmd) => execSync(cmd, { stdio: 'pipe' }).toString().trim();
+
+  if (mode === 'actions') {
+    // Runner descartável: identidade do bot é o que se quer no histórico.
+    git('git config user.email "spec-wave[bot]@github.com"');
+    git('git config user.name "spec-wave[bot]"');
+  }
+
+  git(`git add "${filePath}"`);
+
+  // Nada mudou (regerar conteúdo idêntico) → `git commit` sairia 1 e derrubaria
+  // o comando depois de o trabalho estar feito.
+  let hasChanges = true;
+  try {
+    execSync(`git diff --cached --quiet -- "${filePath}"`, { stdio: 'pipe' });
+    hasChanges = false;
+  } catch {
+    hasChanges = true;
+  }
+  if (!hasChanges) {
+    return { committed: false, pushed: false, warning: 'conteúdo idêntico ao já versionado — nada a commitar' };
+  }
+
+  git(`git commit -m "${message}" -- "${filePath}"`);
+
+  try {
+    git('git pull --rebase');
+    git('git push');
+    return { committed: true, pushed: true, warning: null };
+  } catch (err) {
+    if (mode === 'actions') throw err;
+    // Local: o arquivo está gerado e commitado. Derrubar o comando aqui
+    // esconderia esse fato atrás de um erro de rede/divergência.
+    const branch = (() => {
+      try {
+        return gitQuiet('git rev-parse --abbrev-ref HEAD');
+      } catch {
+        return 'seu branch';
+      }
+    })();
+    return {
+      committed: true,
+      pushed: false,
+      warning:
+        `commit feito em ${branch}, mas o push falhou (${err.message.split('\n')[0]}). ` +
+        'O arquivo está salvo e versionado — publique quando resolver.',
+    };
+  }
+}

package/src/lib/project-root.mjs

@@ -76,12 +76,19 @@ export function resolveFromRoot(root, ...parts) {
  *
  * Era o mesmo bloco copiado em story/task/order/qa/code-review/validate.
  *
+ * `env` é INJETÁVEL, e precisa ser: ler `process.env` aqui dentro tornava
+ * impossível testar o caminho local. Quem chamava com `env: {}` para simular
+ * "sem GITHUB_REPOSITORY" recebia o valor real assim mesmo — o teste passava na
+ * máquina do dev (onde a env não existe) e falhava no GitHub Actions (onde o
+ * runner a define).
+ *
  * @param {string} [cwd=process.cwd()]
+ * @param {object} [env=process.env] ambiente; injetável para teste
  * @returns {{ owner: string|undefined, repo: string|undefined,
  *             root: string|null, config: object|null, error: string|null }}
  */
-export function resolveRepoContext(cwd = process.cwd()) {
-  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+export function resolveRepoContext(cwd = process.cwd(), env = process.env) {
+  const [envOwner, envRepo] = (env.GITHUB_REPOSITORY || '').split('/');
   const { config, root, error } = loadConfig(cwd);
   return {
     owner: envOwner || config?.owner,

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

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

@@ -38,8 +38,11 @@ spec-wave:decompose-apply
 
 1. **Pré-requisito.** Feature: confirme que está em **✅ Ready** (spec e plan validados — skill **ready**). RFC: basta a descrição estar completa.
 
-2. **Etapa 1 — gerar o rascunho:**
+2. **Etapa 1 — gerar o rascunho**, no modo que preferir (mesmo resultado; o modo é detectado pelo ambiente):
    ```bash
+   # local — resultado nesta sessão
+   npx @spec-wave/cli@latest decompose --issue-number <número>
+   # ou Action — assíncrono
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
    Informe: "Rascunho iniciado — vai commitar o `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
@@ -54,6 +57,9 @@ spec-wave:decompose-apply
 
 4. **Etapa 2 — aplicar o rascunho aprovado**, só depois da revisão:
    ```bash
+   # local
+   npx @spec-wave/cli@latest decompose --issue-number <número> --apply
+   # ou Action
    gh issue edit <número> --add-label "spec-wave:decompose-apply"
    ```
    Aplicar essa label **é** a aprovação humana — não há nova crítica.

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

@@ -12,7 +12,9 @@ allowed-tools:
 
 # spec-wave plan — plano técnico (2º documento)
 
-> **Regra fundamental: nunca gere o `plan.md` você mesmo.** Aplique a label e deixe o Action gerar e commitar. Exceção: revisar/melhorar um plano já gerado.
+> **Regra fundamental: nunca escreva o `plan.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. Exceção: revisar/melhorar um plano já gerado.
+
+**Dois modos, mesmo resultado.** `npx @spec-wave/cli@latest generate-plan --issue-number <n>` roda **agora**, nesta sessão; a label `spec-wave:plan` roda no Action. O modo é detectado pelo ambiente. Ambos geram, commitam, fazem push, criticam e comentam na issue. Local exige a chave de IA no seu ambiente. Veja a skill **spec** para a tabela completa.
 
 **Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
 
@@ -24,8 +26,11 @@ O plano segue o schema do **RFC-002 §3.2**: **Estratégia Técnica** (com Matri
 
 2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read). **Se não existir, ajude a criar AGORA** — o passo a passo está em `reference/tech-context.md`, ao lado deste arquivo. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
 
-3. Adicione a label de gatilho:
+3. **Acione**, no modo escolhido:
    ```bash
+   # local — resultado nesta sessão
+   npx @spec-wave/cli@latest generate-plan --issue-number <número>
+   # ou Action — assíncrono
    gh issue edit <número> --add-label "spec-wave:plan"
    ```
 

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

@@ -9,7 +9,18 @@ allowed-tools:
 
 # spec-wave spec — especificação funcional (1º documento)
 
-> **Regra fundamental: nunca gere o `spec.md` você mesmo.** Aplique a label e deixe o Action gerar — é isso que garante que o arquivo seja commitado no repositório e referenciado na issue. Exceção: revisar/melhorar um `spec.md` já gerado (aí sim use Edit no arquivo local).
+> **Regra fundamental: nunca escreva o `spec.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. É isso que garante que o arquivo seja commitado e referenciado na issue. Exceção: revisar/melhorar um `spec.md` já gerado (aí sim use Edit).
+
+## Dois modos, mesmo resultado
+
+| Modo | Como acionar | Quando |
+|------|--------------|--------|
+| **Action** | aplicar a label `spec-wave:spec` | fluxo assíncrono; roda no CI, você acompanha pela issue |
+| **Local** | `npx @spec-wave/cli@latest generate-spec --issue-number <n>` | você quer o documento **agora**, nesta sessão, e iterar em cima dele |
+
+O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local automaticamente. Os dois geram o arquivo, commitam, dão push, comentam na issue e removem a label de gatilho. **Pergunte ao usuário qual ele quer** se não estiver claro; na dúvida numa sessão interativa, prefira o local (o resultado aparece em segundos, em vez de exigir acompanhar o Action).
+
+> Local exige a chave de IA no seu ambiente (`OPENROUTER_API_KEY` ou `ANTHROPIC_API_KEY`) e um `.spec-wave.json` no repositório. O provider `anthropic` **só** funciona local — no Action ele precisaria do Claude Code como subprocesso, que o runner não tem.
 
 **Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
 
@@ -19,12 +30,19 @@ allowed-tools:
 
    > **Apenas Features.** Para **Spike, RFC e Bug** o Action **pula** a geração, remove a label e comenta. Não use esta skill nesses tipos.
 
-2. Adicione a label de gatilho:
+2. **Escolha o modo** (veja a tabela acima) e acione:
+
+   **Local** — resultado nesta sessão:
    ```bash
-   gh issue edit <número> --add-label "spec-wave:spec"
+   npx @spec-wave/cli@latest generate-spec --issue-number <número>
    ```
+   O comando imprime `Modo de execução: local`, gera, commita e faz push.
 
-3. Informe ao usuário: "Label `spec-wave:spec` adicionada. O Action `generate-spec.yml` vai gerar o `spec.md` automaticamente. Acompanhe em Actions → Generate Spec."
+   **Action** — assíncrono:
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:spec"
+   ```
+   Informe: "Label `spec-wave:spec` adicionada. O Action `generate-spec.yml` vai gerar o `spec.md`. Acompanhe em Actions → Generate Spec."
 
 4. Quando concluir, ofereça revisar o arquivo em `docs/features/<slug>/spec.md`. O slug vem do título: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`.
 

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

@@ -27,7 +27,11 @@ Toda a CLI é invocada como `npx @spec-wave/cli@latest <comando>`.
 
 ## Regras fundamentais
 
-1. **Nunca gere `spec.md` ou `plan.md` você mesmo.** Aplique a label de gatilho e deixe o Action gerar e commitar. Exceção: revisar/melhorar um documento já gerado.
+1. **Nunca escreva `spec.md` ou `plan.md` à mão.** Quem gera é o spec-wave — e ele roda de **dois modos**, com o mesmo resultado:
+   - **Action:** aplique a label de gatilho (`spec-wave:spec`, `spec-wave:plan`, `spec-wave:decompose`);
+   - **Local:** `npx @spec-wave/cli@latest generate-spec|generate-plan|decompose --issue-number <n>` na sua sessão.
+
+   O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), sem flag. Os dois geram, commitam, fazem push, comentam na issue e sincronizam o board — o board é a fonte de verdade independentemente de onde rodou. Local exige a chave de IA no seu ambiente e um `.spec-wave.json`. Exceção à regra: revisar/melhorar um documento já gerado.
 2. **Nunca crie Story ou Task avulsa.** Elas nascem do `decompose`, já em **✅ Ready** e vinculadas ao pai. Criadas à mão caem em 📥 Backlog e **não aparecem em tela nenhuma** da UI (o inbox do PM lista Features, a tela do Dev lê 🚧 Desenvolvimento, a fila do TL lê ✅ Ready).
 3. **Nunca use `gh issue create`** para work items — não adiciona ao Project, a issue fica sem Etapa e some das telas. Use `npx @spec-wave/cli@latest issue`.
 4. **A Etapa só avança, nunca retrocede.** O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira `move`, `task start|done` e `story review` a mutações GraphQL manuais — os comandos embutem essas regras.