@spec-wave/cli 0.11.0 → 0.11.1

package/README.md

@@ -85,6 +85,14 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 | `code-review.yml` | PR aberto/reaberto | Move Feature para `👀 Code Review` |
 | `qa.yml` | PR aprovado | Move Feature para `🧪 QA` |
 
+**Re-executar uma etapa (`spec-wave:force`).** Adicionada *junto* de uma label de gatilho, a label `spec-wave:force` manda o comando re-executar a etapa ignorando os guards; ela é consumida pelo run (vale uma vez). Sozinha não dispara nada.
+
+```bash
+gh issue edit 12 --add-label "spec-wave:force" --add-label "spec-wave:decompose"
+```
+
+No `decompose` ela **fecha as sub-issues da decomposição anterior** (Stories e suas Tasks) antes de gerar as novas — operação destrutiva, com aviso no comentário da issue quando alguma já saiu de `✅ Ready`. Em `generate-spec`/`generate-plan` não muda nada: essas etapas já sobrescrevem o documento a cada acionamento. A flag equivalente para execução local é `--force`.
+
 ### Skill (`src/templates/skill/SKILL.md`)
 
 Skill que guia o usuário pelo fluxo via comandos como `/spec-wave spec 42`, `/spec-wave plan 42`, `/spec-wave decompose 42`. A skill lê o `.spec-wave.json` local, detecta o estado atual e executa os comandos corretos sem abrir wizards interativos. Instale-a no seu agente com `install-skill` (ver abaixo).

package/bin/spec-wave.mjs

@@ -132,6 +132,7 @@ program
   .command('generate-plan')
   .description('Gera plan.md para uma Feature (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { generatePlan } = await import('../src/commands/generate-plan.mjs');
     await generatePlan(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -141,6 +142,7 @@ program
   .command('generate-spec')
   .description('Gera spec.md para uma Feature (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { generateSpec } = await import('../src/commands/generate-spec.mjs');
     await generateSpec(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -159,6 +161,7 @@ program
   .command('decompose')
   .description('Decompõe uma Feature em Stories e Tasks (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { decompose } = await import('../src/commands/decompose.mjs');
     await decompose(options).catch(err => { console.error(err.message); process.exit(1); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.11.0",
+  "version": "0.11.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

@@ -198,6 +198,7 @@ export async function listSubIssues(token, issueNodeId) {
               number
               title
               body
+              state
               labels(first: 20) { nodes { name } }
             }
           }
@@ -211,6 +212,9 @@ export async function listSubIssues(token, issueNodeId) {
     title: n.title,
     body: n.body || '',
     nodeId: n.id,
+    // 'OPEN' | 'CLOSED' (GraphQL) normalizado para o vocabulário do REST, que
+    // é o que o resto do código compara (issue.state === 'closed').
+    state: n.state === 'CLOSED' ? 'closed' : 'open',
     labels: (n.labels?.nodes || []).map(l => l.name),
   }));
 }

package/src/api/github-rest.mjs

@@ -101,6 +101,19 @@ export async function getIssue(token, owner, repo, issueNumber) {
   return res.data;
 }
 
+// Fecha uma issue. Usado pelo re-decompose forçado para limpar as sub-issues
+// da decomposição anterior antes de gerar as novas.
+export async function closeIssue(token, owner, repo, issueNumber, reason = 'not_planned') {
+  const octokit = makeOctokit(token);
+  await octokit.rest.issues.update({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    state: 'closed',
+    state_reason: reason,
+  });
+}
+
 export async function deleteLabel(token, owner, repo, name) {
   const octokit = makeOctokit(token);
   try {

package/src/commands/decompose.mjs

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
-import { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy } from '../api/github-rest.mjs';
-import { addSubIssue, listSubIssues } from '../api/github-graphql.mjs';
+import { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, closeIssue } from '../api/github-rest.mjs';
+import { addSubIssue, listSubIssues, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { isForced, consumeForceLabel } from '../lib/force.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
@@ -10,7 +11,10 @@ import { formatDependencyLine } from '../lib/dependencies.mjs';
 import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, TARGET_LANGUAGE, STAGE_READY, PROGRESS_TODO } from '../config.mjs';
+import {
+  DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, LABEL_FORCE,
+  TARGET_LANGUAGE, STAGE_READY, STAGE_DEVELOPMENT, STAGE_ORDER, PROGRESS_TODO,
+} from '../config.mjs';
 
 // Adiciona a issue ao board na Etapa ✅ Ready / Status Todo. Best-effort; a
 // Etapa nunca retrocede (advanceToStage não toca itens já adiante).
@@ -19,15 +23,61 @@ async function moveToReady(token, project, etapaField, statusField, nodeId) {
   await advanceToStage(token, project, etapaField, statusField, nodeId, STAGE_READY, PROGRESS_TODO);
 }
 
-// Extrai JSON da resposta do modelo (tolera texto em volta).
-function parseJson(raw) {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    const jsonMatch = raw.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) throw new Error('Claude did not return valid JSON');
-    return JSON.parse(jsonMatch[0]);
+// Dobra as barras invertidas que NÃO iniciam um escape válido de JSON. O corpo
+// das tasks costuma trazer trecho de shell/YAML/regex ("\d+", "gradlew \" no fim
+// da linha) e o modelo emite a barra crua: `JSON.parse` morre com "Bad escaped
+// character". Escapes válidos são consumidos inteiros pela regex, então `\\`,
+// `\n` e `\uXXXX` passam intactos.
+function repairEscapes(text) {
+  return text.replace(/\\(u[0-9a-fA-F]{4}|["\\/bfnrt])?/g, (match, valid) => (valid ? match : '\\\\'));
+}
+
+// Trecho ao redor da posição que o V8 reporta ("... at position 18321"), para o
+// log da Action mostrar O QUE quebrou em vez de só um offset.
+function excerptAt(text, message) {
+  const at = /position (\d+)/.exec(message || '');
+  if (!at) return '';
+  const pos = Number(at[1]);
+  const excerpt = text.slice(Math.max(0, pos - 60), pos + 60).replace(/\s+/g, ' ').trim();
+  return excerpt ? ` Trecho: …${excerpt}…` : '';
+}
+
+/**
+ * Extrai o JSON da resposta do modelo (função PURA — testável).
+ *
+ * Tenta, em ordem: conteúdo de fence de código, resposta inteira e o primeiro
+ * objeto `{...}` do texto; cada candidato é parseado cru e, se falhar, com os
+ * escapes reparados. Sem candidato válido, lança com o motivo e o trecho.
+ *
+ * @param {string} raw resposta bruta do modelo
+ * @returns {object} objeto decodificado
+ */
+export function parseModelJson(raw) {
+  const text = String(raw ?? '');
+  const candidates = [];
+  const fence = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+  if (fence) candidates.push(fence[1]);
+  candidates.push(text);
+  const obj = text.match(/\{[\s\S]*\}/);
+  if (obj) candidates.push(obj[0]);
+
+  let failure = null;
+  for (const candidate of candidates) {
+    const trimmed = candidate.trim();
+    if (!trimmed) continue;
+    for (const attempt of [trimmed, repairEscapes(trimmed)]) {
+      try {
+        return JSON.parse(attempt);
+      } catch (err) {
+        failure = { message: err.message, text: attempt };
+      }
+    }
   }
+
+  throw new Error(
+    `O modelo não devolveu JSON válido: ${failure?.message ?? 'nenhum objeto encontrado na resposta'}.` +
+    (failure ? excerptAt(failure.text, failure.message) : '')
+  );
 }
 
 // Prefixo de título das sub-issues geradas por cada tipo decompoível.
@@ -40,13 +90,19 @@ const CHILD_PREFIX = { Feature: '[STORY]', RFC: '[TASK]' };
  * sub-issues já contêm um item do tipo-alvo (Feature → algum `[STORY]` no
  * título; RFC → algum `[TASK]`). Sub-issues de outro tipo não contam.
  *
+ * Com `force` (flag `--force` ou label `spec-wave:force`) nada é pulado — o
+ * chamador é quem limpa a decomposição anterior antes de gerar a nova.
+ *
  * @param {object} params
  * @param {Array<string|{name: string}>} [params.labels] labels da issue
  * @param {Array<{ number?: number, title?: string }>} [params.subIssues] sub-issues existentes
  * @param {string} params.type tipo da issue ('Feature' | 'RFC')
+ * @param {boolean} [params.force] re-executa ignorando os guards
  * @returns {{ skip: boolean, reason: string }}
  */
-export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {}) {
+export function shouldSkipDecompose({ labels = [], subIssues = [], type, force = false } = {}) {
+  if (force) return { skip: false, reason: '' };
+
   const names = labels
     .map(l => (typeof l === 'string' ? l : l?.name))
     .filter(Boolean);
@@ -66,6 +122,103 @@ export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {})
   return { skip: false, reason: '' };
 }
 
+/**
+ * Planeja a limpeza de um re-decompose forçado (função PURA — testável).
+ *
+ * Só entram as sub-issues do tipo-alvo (Feature → `[STORY]`, RFC → `[TASK]`)
+ * que ainda estão abertas — as já fechadas não precisam de nada. Separa as que
+ * já saíram de ✅ Ready (Etapa ≥ 🚧 Desenvolvimento): fechá-las descarta
+ * trabalho em andamento, então elas são destacadas no aviso.
+ *
+ * @param {object} params
+ * @param {Array<{number:number, title?:string, nodeId?:string, state?:string}>} [params.subIssues]
+ * @param {string} params.type tipo da issue pai ('Feature' | 'RFC')
+ * @param {Record<number, string|null>} [params.stages] Etapa atual por número de issue
+ * @returns {{ close: object[], started: object[] }} close: a fechar (com `stage`);
+ *          started: subconjunto de close que já passou de Ready.
+ */
+export function planForcedCleanup({ subIssues = [], type, stages = {} } = {}) {
+  const prefix = CHILD_PREFIX[type];
+  if (!prefix) return { close: [], started: [] };
+
+  const devIdx = STAGE_ORDER.indexOf(STAGE_DEVELOPMENT);
+  const close = subIssues
+    .filter(s => (s.title || '').includes(prefix) && s.state !== 'closed')
+    .map(s => ({ ...s, stage: stages[s.number] ?? null }));
+  const started = close.filter(s => {
+    const idx = s.stage ? STAGE_ORDER.indexOf(s.stage) : -1;
+    return idx !== -1 && devIdx !== -1 && idx >= devIdx;
+  });
+  return { close, started };
+}
+
+// Fecha a decomposição anterior (sub-issues do tipo-alvo e os filhos delas) e
+// comenta o que foi fechado. Best-effort item a item: uma falha vira warn e o
+// re-decompose segue — melhor uma issue órfã do que abortar no meio.
+async function closeStaleSubIssues(ctx, subIssues) {
+  const { token, projectToken, owner, repo, issueNumber, project, etapaField, type } = ctx;
+
+  // Etapa de cada sub-issue (best-effort) — só para avisar o que já saiu de Ready.
+  const stages = {};
+  if (project?.id && etapaField?.id) {
+    await Promise.all(subIssues.map(async (s) => {
+      if (!s.nodeId) return;
+      try {
+        const itemId = await addProjectItem(projectToken, project.id, s.nodeId);
+        stages[s.number] = await getItemSingleSelectValue(projectToken, itemId, etapaField.id);
+      } catch {
+        stages[s.number] = null;
+      }
+    }));
+  }
+
+  const { close, started } = planForcedCleanup({ subIssues, type, stages });
+  if (close.length === 0) {
+    console.log('Re-decompose forçado: nenhuma sub-issue anterior aberta para fechar.');
+    return;
+  }
+
+  console.log(`Re-decompose forçado: fechando ${close.length} sub-issue(s) anterior(es)...`);
+  const closed = [];
+  for (const s of close) {
+    // Filhos primeiro (Tasks de uma Story): fechar só a Story deixaria as Tasks
+    // órfãs e abertas no board.
+    const children = s.nodeId ? await listSubIssues(token, s.nodeId).catch(() => []) : [];
+    for (const child of children.filter(c => c.state !== 'closed')) {
+      try {
+        await closeIssue(token, owner, repo, child.number);
+      } catch (err) {
+        console.warn(`  Falha ao fechar #${child.number}: ${err.message}`);
+      }
+    }
+    try {
+      await closeIssue(token, owner, repo, s.number);
+      closed.push({ ...s, children: children.length });
+      console.log(`  #${s.number} fechada${children.length ? ` (+${children.length} filha(s))` : ''}.`);
+    } catch (err) {
+      console.warn(`  Falha ao fechar #${s.number}: ${err.message}`);
+    }
+  }
+
+  if (closed.length === 0) return;
+  const lines = closed.map(s =>
+    `- #${s.number} ${s.title}${s.stage ? ` — Etapa ${s.stage}` : ''}` +
+    (s.children ? ` _(+${s.children} sub-issue(s))_` : '')
+  );
+  const startedWarning = started.length > 0
+    ? `\n\n⚠️ ${started.length} delas já tinha(m) saído de **${STAGE_READY}**: ` +
+      `${started.map(s => `#${s.number} (${s.stage})`).join(', ')} — ` +
+      'confira se algum trabalho em andamento foi descartado.'
+    : '';
+  await commentOnIssue(
+    token, owner, repo, parseInt(issueNumber, 10),
+    `🔀 **Re-decompose forçado** (label \`${LABEL_FORCE}\`)\n\n` +
+    `Fechadas ${closed.length} sub-issue(s) da decomposição anterior:\n\n${lines.join('\n')}` +
+    startedWarning +
+    '\n\nGerando a nova decomposição…'
+  ).catch(() => {});
+}
+
 // Lint de idioma sobre títulos+corpos gerados; retorna aviso pronto para
 // anexar ao comentário final ('' se limpo).
 function formatItemsLintWarning(texts) {
@@ -147,7 +300,7 @@ async function decomposeFeature(ctx) {
     `\n## plan.md\n${planContent}`,
   ].join('\n');
 
-  const decomposition = parseJson(await generateDocument(FEATURE_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
+  const decomposition = parseModelJson(await generateDocument(FEATURE_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
 
   // Crítica adversarial ANTES de criar qualquer issue: stories que contradizem
   // a spec/plan não devem virar trabalho. Crítica indisponível → só avisa.
@@ -283,7 +436,7 @@ async function decomposeRFC(ctx) {
     `\n## Descrição\n${issue.body || '(sem descrição)'}`,
   ].join('\n');
 
-  const decomposition = parseJson(await generateDocument(RFC_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
+  const decomposition = parseModelJson(await generateDocument(RFC_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
   const rfcNodeId = issue.node_id;
   const tasks = decomposition.tasks || [];
   const created = [];
@@ -327,7 +480,7 @@ async function decomposeRFC(ctx) {
   console.log(`Decomposição concluída: ${created.length} tasks criadas.`);
 }
 
-export async function decompose({ issueNumber }) {
+export async function decompose({ issueNumber, force = false }) {
   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).
@@ -366,17 +519,25 @@ export async function decompose({ issueNumber }) {
     console.warn(`Não foi possível listar sub-issues: ${err.message} — seguindo sem o guard de sub-issues.`);
     subIssues = [];
   }
-  const guard = shouldSkipDecompose({ labels: issue.labels || [], subIssues, type });
+  // Force (flag --force ou label spec-wave:force): ignora o guard e limpa a
+  // decomposição anterior antes de gerar a nova.
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  const guard = shouldSkipDecompose({ labels: issue.labels || [], subIssues, type, force: forced });
   if (guard.skip) {
     console.log(`Decompose ignorado: ${guard.reason}.`);
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:decompose');
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
-      `⏭️ **decompose ignorado:** ${guard.reason}. Para forçar, remova a label ` +
-      `\`${LABEL_DECOMPOSED}\` (e apague as sub-issues antigas se quiser re-gerar).`
+      `⏭️ **decompose ignorado:** ${guard.reason}.\n\n` +
+      `Para re-decompor, adicione a label \`${LABEL_FORCE}\` junto com \`spec-wave:decompose\` — ` +
+      'as sub-issues da decomposição anterior serão **fechadas** e novas serão geradas.'
     ).catch(() => {});
     return;
   }
+  // Consome a label assim que ela é lida — se o run for cancelado/morto mais
+  // adiante, ela não fica pendurada forçando silenciosamente os runs seguintes.
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+  if (forced) console.log(`Modo forçado ativo (${force ? 'flag --force' : `label ${LABEL_FORCE}`}).`);
 
   // Projeto + campos Etapa/Status do board (reutilizados em todos os itens).
   const { project, error: projectError } = loadProjectConfig();
@@ -399,8 +560,11 @@ export async function decompose({ issueNumber }) {
   // Coletor de uso de IA — o finally registra o custo já incorrido mesmo nos
   // fluxos que retornam cedo (ex.: abort da crítica grave) ou que falham.
   const usageEntries = [];
-  const ctx = { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage: usageEntries };
+  const ctx = { token, projectToken, owner, repo, issue, issueNumber, type, project, etapaField, statusField, usage: usageEntries };
   try {
+    // Limpeza do re-decompose forçado ANTES de gerar: fecha as sub-issues da
+    // decomposição anterior para o board não ficar com dois conjuntos.
+    if (forced) await closeStaleSubIssues(ctx, subIssues);
     if (type === 'Feature') await decomposeFeature(ctx);
     else if (type === 'RFC') await decomposeRFC(ctx);
   } finally {

package/src/commands/generate-plan.mjs

@@ -8,6 +8,7 @@ import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { isForced, consumeForceLabel } from '../lib/force.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 
 // Aviso anexado ao comentário quando o lint de idioma ainda reprova após o
@@ -41,7 +42,7 @@ Regras OBRIGATÓRIAS:
 - Forneça detalhes acionáveis: caminhos exatos de endpoints, nomes de DTOs, constraints de banco.
 - Responda APENAS com o conteúdo do plan.md, sem texto adicional.`;
 
-export async function generatePlan({ issueNumber }) {
+export async function generatePlan({ issueNumber, force = false }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
 
@@ -69,6 +70,11 @@ export async function generatePlan({ issueNumber }) {
     return;
   }
 
+  // Ver generate-spec: não há guard aqui — a label já regera e sobrescreve.
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+  if (forced) console.log('Modo forçado ativo — plan.md será regerado (sobrescreve o existente).');
+
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
   const filePath = `${featureDir}/plan.md`;

package/src/commands/generate-spec.mjs

@@ -5,6 +5,7 @@ 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 { isForced, consumeForceLabel } from '../lib/force.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE } from '../config.mjs';
 
@@ -41,7 +42,7 @@ Regras:
 - Seja específico e detalhado em cada seção.
 - Responda APENAS com o conteúdo do spec.md, sem texto adicional.`;
 
-export async function generateSpec({ issueNumber }) {
+export async function generateSpec({ issueNumber, force = false }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
 
@@ -70,6 +71,13 @@ export async function generateSpec({ issueNumber }) {
     return;
   }
 
+  // A geração de spec/plan não tem guard — re-acionar a label já regera e
+  // sobrescreve o arquivo. O force existe por simetria com o decompose (e para
+  // a label ser consumida quando aplicada aos três de uma vez).
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+  if (forced) console.log('Modo forçado ativo — spec.md será regerado (sobrescreve o existente).');
+
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
   const filePath = `${featureDir}/spec.md`;

package/src/config.mjs

@@ -183,6 +183,10 @@ export const PRIORITY_LABELS = [
 // Labels de estado gravadas pelas automações (não são gatilhos do usuário).
 export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
+// Modificador (não é gatilho — sozinha não dispara workflow nenhum): quando
+// presente junto de uma label de gatilho, manda o comando re-executar a etapa
+// ignorando os guards. É consumida (removida) pelo run que a leu.
+export const LABEL_FORCE = 'spec-wave:force';
 
 export const TRIGGER_LABELS = [
   { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
@@ -192,6 +196,7 @@ export const TRIGGER_LABELS = [
   { name: 'spec-wave:decompose',     color: 'BFD4F2', description: 'Decompor em Stories e Tasks'          },
   { name: LABEL_CRITIQUE_FAILED,     color: 'B60205', description: 'Crítica adversarial apontou contradições graves' },
   { name: LABEL_DECOMPOSED,          color: 'EDEDED', description: 'Feature já decomposta em Stories e Tasks' },
+  { name: LABEL_FORCE,               color: 'D93F0B', description: 'Re-executa a etapa ignorando os guards (consumida no run)' },
 ];
 
 export const ALL_LABELS = [...TYPE_LABELS, ...PRIORITY_LABELS, ...TRIGGER_LABELS];

package/src/lib/force.mjs

@@ -0,0 +1,34 @@
+// Detecção do modo "force" (re-executar a etapa ignorando os guards).
+//
+// Os comandos generate-spec/generate-plan/decompose rodam dentro de Actions
+// disparadas por label — a linha de comando do workflow é fixa e não tem como
+// receber uma flag. Por isso o force chega de duas formas equivalentes:
+//   • label `spec-wave:force` na issue (fluxo normal, pelo board);
+//   • flag `--force` (execução local/manual da CLI).
+// A label é CONSUMIDA pelo run que a leu (ver consumeForceLabel), senão ela
+// ficaria pendurada e forçaria silenciosamente todos os runs seguintes.
+import { LABEL_FORCE } from '../config.mjs';
+import { removeLabel } from '../api/github-rest.mjs';
+
+/**
+ * Diz se a etapa deve ser re-executada ignorando os guards (função PURA).
+ *
+ * @param {object} [params]
+ * @param {Array<string|{name: string}>} [params.labels] labels da issue
+ * @param {boolean} [params.flag] valor da flag `--force` da CLI
+ * @returns {boolean}
+ */
+export function isForced({ labels = [], flag = false } = {}) {
+  if (flag) return true;
+  return (labels || [])
+    .map(l => (typeof l === 'string' ? l : l?.name))
+    .includes(LABEL_FORCE);
+}
+
+/**
+ * Remove a label `spec-wave:force` da issue. Best-effort: nunca lança — deixar
+ * de consumir a label é um incômodo, não um motivo para derrubar o comando.
+ */
+export async function consumeForceLabel(token, owner, repo, issueNumber) {
+  await removeLabel(token, owner, repo, issueNumber, LABEL_FORCE).catch(() => {});
+}

package/src/templates/skill/SKILL.md

@@ -105,6 +105,12 @@ Labels de **estado** (gravadas pelas automações — **não** são gatilhos, n
 - `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves** nos documentos; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
 - `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
 
+Label **modificadora** — `spec-wave:force`: sozinha **não dispara nada**; adicionada **junto** de uma label de gatilho, manda o comando **re-executar a etapa ignorando os guards**. É **consumida** (removida) pelo run que a leu, então vale para uma execução só. Adicione-a **antes ou junto** do gatilho, nunca depois (o evento do gatilho já teria disparado):
+```bash
+gh issue edit <n> --add-label "spec-wave:force" --add-label "spec-wave:decompose"
+```
+Efeito por comando: no **decompose**, ignora o guard e **fecha as sub-issues da decomposição anterior** antes de gerar as novas (veja *Guard de idempotência*); em **spec** e **plan**, não muda nada na prática — eles já regeram e sobrescrevem o arquivo a cada acionamento da label.
+
 A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli@latest implement <número>` (não é uma label/Action): lê uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma Story ou uma Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
 ---
@@ -183,6 +189,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
+| `--force` | flag | Re-executa a etapa ignorando os guards. No fluxo por label o equivalente é a label `spec-wave:force` (a linha de comando do workflow é fixa) — prefira a label. |
 
 > ⚠️ Esses quatro comandos são executados pelos **GitHub Actions** (disparados por labels), **não** pela skill diretamente. Veja a *Regra fundamental*: para gerar plan/spec/decompor, adicione a **label** correspondente — não rode o comando à mão (a não ser para debug local).
 >
@@ -243,7 +250,11 @@ Após o `generate-plan` e **antes** da criação de issues no `decompose`, um se
 
 O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar Stories/Tasks, o `decompose` **pula** quando a issue já tem a label **`spec-wave:decomposed`** ou já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). Ao concluir com sucesso, o Action grava a label. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
 
-**Para forçar um re-decompose:** remova a label (`gh issue edit <n> --remove-label "spec-wave:decomposed"`), **apague/feche as sub-issues antigas** (senão a detecção por sub-issues pula de novo) e re-adicione `spec-wave:decompose`.
+**Para forçar um re-decompose**, adicione a label `spec-wave:force` junto com o gatilho:
+```bash
+gh issue edit <n> --add-label "spec-wave:force" --add-label "spec-wave:decompose"
+```
+O comando então: (1) ignora os dois guards; (2) **fecha** as sub-issues abertas do tipo-alvo da decomposição anterior **e os filhos delas** (as Tasks de cada Story), comentando na issue o que foi fechado; (3) gera a nova decomposição. **É destrutivo** — se alguma Story já tiver saído de ✅ Ready, o comentário destaca quais, para você conferir se descartou trabalho em andamento. Confirme com o usuário antes de acionar em Features com desenvolvimento em curso.
 
 ### Dependências entre Stories (`Depende de: #N`)
 
@@ -405,7 +416,8 @@ Inicia a geração da **especificação funcional** para uma Feature. É o **pri
    ```
 3. Informe: "Label `spec-wave:spec` adicionada. O GitHub Action `generate-spec.yml` irá gerar o `spec.md` automaticamente."
 4. Após a conclusão, ofereça revisar o spec.md gerado em `docs/features/<slug>/spec.md`.
-5. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
+5. **Para regerar** (a spec já existe e o usuário quer outra versão): basta re-adicionar a label — o Action sobrescreve o arquivo. A label `spec-wave:force` é aceita, mas aqui não muda nada; **avise que o spec.md atual será perdido** (inclusive edições manuais) e confirme antes.
+6. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
 
 ---
 
@@ -424,7 +436,8 @@ O plano técnico segue o schema do RFC-002 §3.2: **Estratégia Técnica** (com
    ```
 4. Informe: "Label `spec-wave:plan` adicionada. O GitHub Action `generate-plan.yml` irá gerar o `plan.md` automaticamente. Acompanhe em: Actions → Generate Plan."
 5. Após a conclusão (cheque comentários na issue ou aguarde confirmação do usuário), ofereça revisar o plan.md gerado em `docs/features/<slug>/plan.md`.
-6. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
+6. **Para regerar**: re-adicione a label — o Action sobrescreve o `plan.md` (mesma ressalva do spec: edições manuais se perdem, confirme antes).
+7. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
 
 ---
 
@@ -516,7 +529,7 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    ```
 3. Informe: "Decomposição iniciada — Feature gera Stories+Tasks; RFC gera Tasks."
 4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories geradas trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução.
-5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
+5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para re-decompor, adicione `spec-wave:force` junto com o gatilho — isso **fecha** a decomposição anterior antes de gerar a nova (veja *Guard de idempotência*; confirme com o usuário, é destrutivo).
 
 ---