@spec-wave/cli 0.11.0 → 0.11.2

package/README.md

@@ -85,6 +85,27 @@ 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` ela **versiona** o documento em vez de sobrescrever (veja abaixo). A flag equivalente para execução local é `--force`.
+
+### Documentos versionados
+
+A primeira geração escreve `spec.md`/`plan.md` (v1). Cada regeração **forçada** grava a próxima versão ao lado, preservando as anteriores:
+
+```
+docs/features/<slug>/
+  spec.md       ← v1
+  spec-v2.md    ← regeração forçada  ⬅ spec atual
+  plan.md       ⬅ plano atual (spec e plan versionam independente)
+```
+
+A **maior versão é o documento atual**: é ela que o `generate-plan` usa como contexto, que o `validate` valida, e que o `decompose` e o `implement` leem. Uma regeração **sem** force sobrescreve essa versão atual.
+
 ### 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.2",
   "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,10 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { 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 { resolveDoc } from '../lib/feature-docs.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
@@ -10,7 +12,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 +24,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 +91,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 +123,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) {
@@ -132,14 +286,18 @@ async function decomposeFeature(ctx) {
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
 
-  const planContent = existsSync(`${featureDir}/plan.md`)
-    ? readFileSync(`${featureDir}/plan.md`, 'utf-8')
-    : '(plan.md não encontrado)';
-  const specContent = existsSync(`${featureDir}/spec.md`)
-    ? readFileSync(`${featureDir}/spec.md`, 'utf-8')
-    : '(spec.md não encontrado)';
+  // Documentos ATUAIS (maior versão): com regerações forçadas o vigente é
+  // spec-v2.md/plan-v3.md…, não o arquivo original.
+  const spec = resolveDoc(featureDir, 'spec');
+  const plan = resolveDoc(featureDir, 'plan');
+  const specContent = spec ? readFileSync(spec.path, 'utf-8') : '(spec.md não encontrado)';
+  const planContent = plan ? readFileSync(plan.path, 'utf-8') : '(plan.md não encontrado)';
 
   console.log(`Decompondo Feature: ${issue.title}`);
+  if (spec || plan) {
+    console.log(`Documentos: ${spec ? `${spec.path} (v${spec.version})` : 'spec ausente'} · ` +
+                `${plan ? `${plan.path} (v${plan.version})` : 'plano ausente'}`);
+  }
   const userContent = [
     `Feature: ${issue.title}`,
     `Issue #${issueNumber}`,
@@ -147,7 +305,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.
@@ -155,8 +313,8 @@ async function decomposeFeature(ctx) {
   try {
     critique = await runCritique({
       kind: 'stories',
-      spec: existsSync(`${featureDir}/spec.md`) ? specContent : null,
-      plan: existsSync(`${featureDir}/plan.md`) ? planContent : null,
+      spec: spec ? specContent : null,
+      plan: plan ? planContent : null,
       stories: decomposition.stories,
       usage,
     });
@@ -283,7 +441,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 +485,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 +524,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 +565,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

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
@@ -8,6 +8,8 @@ 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 { resolveDoc, resolveWritePath } from '../lib/feature-docs.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 +43,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,13 +71,22 @@ export async function generatePlan({ issueNumber }) {
     return;
   }
 
+  // Force: grava a PRÓXIMA versão (plan-v2.md…) preservando as anteriores; sem
+  // force, sobrescreve a versão vigente. Ver lib/feature-docs.mjs.
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
-  const filePath = `${featureDir}/plan.md`;
+  const target = resolveWritePath(featureDir, 'plan', { force: forced });
+  const filePath = target.path;
+  if (forced) console.log(`Modo forçado ativo — gerando ${filePath} (v${target.version}), sem tocar nas versões anteriores.`);
 
-  // Read existing spec.md if available (spec é gerada antes do plano)
-  const specPath = `${featureDir}/spec.md`;
-  const specContent = existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null;
+  // Spec ATUAL (maior versão) como contexto — a spec é gerada antes do plano.
+  const spec = resolveDoc(featureDir, 'spec');
+  const specPath = spec?.path || `${featureDir}/spec.md`;
+  const specContent = spec ? readFileSync(spec.path, 'utf-8') : null;
+  if (spec) console.log(`Usando ${spec.path} (spec v${spec.version}) como contexto.`);
 
   // Tech context (RFC-002 §4): estático + dinâmico + override do corpo da issue.
   const tech = buildTechContext({ issueBody: issue.body || '' });
@@ -113,7 +124,7 @@ export async function generatePlan({ issueNumber }) {
     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 commit -m "docs: generate plan v${target.version} for ${slug} [spec-wave]"`);
     git('git pull --rebase');
     git('git push');
 
@@ -123,8 +134,12 @@ export async function generatePlan({ issueNumber }) {
     // Comment on issue
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
-      `📋 **plan.md gerado automaticamente!**\n\n` +
+      `📋 **plano técnico gerado automaticamente** (v${target.version})\n\n` +
       `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
+      (target.isNewVersion
+        ? `♻️ Regeração forçada: as versões anteriores foram **preservadas**; ` +
+          `**v${target.version} passa a ser o plano atual** — é ele que a validação e a decomposição vão ler.\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

@@ -5,6 +5,8 @@ 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 { resolveWritePath } from '../lib/feature-docs.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE } from '../config.mjs';
 
@@ -41,7 +43,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,9 +72,17 @@ export async function generateSpec({ issueNumber }) {
     return;
   }
 
+  // Force (flag --force ou label spec-wave:force): em vez de sobrescrever,
+  // grava a PRÓXIMA versão (spec-v2.md, spec-v3.md…) e ela passa a ser o
+  // documento atual. Sem force, sobrescreve a versão vigente.
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
-  const filePath = `${featureDir}/spec.md`;
+  const target = resolveWritePath(featureDir, 'spec', { force: forced });
+  const filePath = target.path;
+  if (forced) console.log(`Modo forçado ativo — gerando ${filePath} (v${target.version}), sem tocar nas versões anteriores.`);
 
   // Payload estruturado (RFC-002 §5.1): metadata + entrada de negócio.
   const payload = {
@@ -107,7 +117,7 @@ export async function generateSpec({ issueNumber }) {
     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 commit -m "docs: generate spec v${target.version} for ${slug} [spec-wave]"`);
     git('git pull --rebase');
     git('git push');
 
@@ -117,8 +127,12 @@ export async function generateSpec({ issueNumber }) {
     // Comment on issue
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
-      `📋 **spec.md gerado automaticamente!**\n\n` +
+      `📋 **spec gerada automaticamente** (v${target.version})\n\n` +
       `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
+      (target.isNewVersion
+        ? `♻️ Regeração forçada: as versões anteriores foram **preservadas**; ` +
+          `**v${target.version} passa a ser a spec atual** — é ela que o plano, a validação e a decomposição vão ler.\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/implement.mjs

@@ -14,6 +14,7 @@ import { detectIssueType } from '../lib/issue-type.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
 import { loadProjectConfig, resolveField } from '../lib/board.mjs';
+import { resolveDoc } from '../lib/feature-docs.mjs';
 import { planBoardMoves, applyBoardMoves } from '../lib/implement-board.mjs';
 import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
 
@@ -41,15 +42,16 @@ async function resolveFeature(token, startNodeId) {
   return null;
 }
 
-// Lê spec.md/plan.md de um docs/features/<slug> se existirem.
+// Lê os documentos ATUAIS (maior versão) de um docs/features/<slug>: com
+// regerações forçadas o vigente é spec-v2.md/plan-v3.md…, não o original.
 function readSpecPlan(featureDir) {
-  const specPath = path.join(featureDir, 'spec.md');
-  const planPath = path.join(featureDir, 'plan.md');
+  const spec = resolveDoc(featureDir, 'spec');
+  const plan = resolveDoc(featureDir, 'plan');
   return {
-    specPath,
-    planPath,
-    spec: existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null,
-    plan: existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null,
+    specPath: spec?.path || path.join(featureDir, 'spec.md'),
+    planPath: plan?.path || path.join(featureDir, 'plan.md'),
+    spec: spec ? readFileSync(spec.path, 'utf-8') : null,
+    plan: plan ? readFileSync(plan.path, 'utf-8') : null,
   };
 }
 

package/src/commands/validate.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { resolveDoc } from '../lib/feature-docs.mjs';
 import { CONFIG_FILE, LABEL_CRITIQUE_FAILED, REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
 
@@ -39,37 +40,39 @@ export async function validate({ issueNumber }) {
     );
   }
 
-  // Check plan.md
-  const planPath = `${featureDir}/plan.md`;
-  if (!existsSync(planPath)) {
+  // Valida sempre o documento ATUAL de cada tipo — com regerações forçadas a
+  // versão vigente é a maior (plan-v2.md, plan-v3.md…), não o plan.md original.
+  const plan = resolveDoc(featureDir, 'plan');
+  const planPath = plan?.path || `${featureDir}/plan.md`;
+  if (!plan) {
     errors.push('❌ `plan.md` não encontrado em `' + planPath + '`');
   } else {
-    const planContent = readFileSync(planPath, 'utf-8');
+    const planContent = readFileSync(plan.path, 'utf-8');
     for (const section of REQUIRED_PLAN_SECTIONS) {
       if (!planContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
+        errors.push(`❌ Seção obrigatória ausente no plano (v${plan.version}): **${section}**`);
       }
     }
     for (const problem of findIncompleteDocSigns(planContent)) {
-      errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
+      errors.push(`❌ \`${planPath}\` parece incompleto: ${problem}`);
     }
   }
 
-  // Check spec.md
-  const specPath = `${featureDir}/spec.md`;
-  if (!existsSync(specPath)) {
+  const spec = resolveDoc(featureDir, 'spec');
+  const specPath = spec?.path || `${featureDir}/spec.md`;
+  if (!spec) {
     errors.push('❌ `spec.md` não encontrado em `' + specPath + '`');
   } else {
-    const specContent = readFileSync(specPath, 'utf-8');
+    const specContent = readFileSync(spec.path, 'utf-8');
     for (const section of REQUIRED_SPEC_SECTIONS) {
       if (!specContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
+        errors.push(`❌ Seção obrigatória ausente na spec (v${spec.version}): **${section}**`);
       }
     }
     // Seções presentes não garantem documento completo: um corte dentro da
     // última seção passa na checagem acima (foi o caso da EP2-F13).
     for (const problem of findIncompleteDocSigns(specContent)) {
-      errors.push(`❌ \`spec.md\` parece incompleto: ${problem}`);
+      errors.push(`❌ \`${specPath}\` parece incompleto: ${problem}`);
     }
   }
 

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/feature-docs.mjs

@@ -0,0 +1,89 @@
+// Resolução dos documentos versionados de uma Feature (docs/features/<slug>/).
+//
+// A primeira geração escreve `spec.md`/`plan.md` (= v1). Cada regeração
+// FORÇADA (flag --force ou label spec-wave:force) cria a próxima versão em vez
+// de sobrescrever: `spec-v2.md`, `spec-v3.md`, … O documento ATUAL é sempre a
+// MAIOR versão — é ele que validate/generate-plan/decompose/implement leem, e
+// é ele que uma regeração sem force sobrescreve.
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Versão de um arquivo de documento (função PURA).
+ * `spec.md` → 1; `spec-v2.md` → 2. Outro nome → null.
+ *
+ * @param {string} filename nome do arquivo (sem diretório)
+ * @param {string} base 'spec' ou 'plan'
+ * @returns {number|null}
+ */
+export function parseDocVersion(filename, base) {
+  const match = new RegExp(`^${base}(?:-v(\\d+))?\\.md$`).exec(String(filename ?? ''));
+  if (!match) return null;
+  return match[1] ? parseInt(match[1], 10) : 1;
+}
+
+/**
+ * Documento ATUAL entre os arquivos dados: o de maior versão (função PURA).
+ * Empate (raro: `spec.md` e `spec-v1.md` coexistindo) resolve pelo sufixado,
+ * para o resultado ser determinístico.
+ *
+ * @param {string[]} filenames
+ * @param {string} base 'spec' ou 'plan'
+ * @returns {{ file: string, version: number }|null}
+ */
+export function pickLatestDoc(filenames, base) {
+  const found = (filenames || [])
+    .map(file => ({ file, version: parseDocVersion(file, base), suffixed: /-v\d+\.md$/.test(file) }))
+    .filter(entry => entry.version !== null)
+    .sort((a, b) => (a.version - b.version) || (Number(a.suffixed) - Number(b.suffixed)));
+  if (found.length === 0) return null;
+  const { file, version } = found[found.length - 1];
+  return { file, version };
+}
+
+/**
+ * Nome do arquivo da PRÓXIMA versão (função PURA): `spec.md` quando ainda não
+ * há nenhum, `spec-v<N+1>.md` a partir da maior versão existente.
+ *
+ * @param {string[]} filenames
+ * @param {string} base 'spec' ou 'plan'
+ * @returns {string}
+ */
+export function nextDocName(filenames, base) {
+  const latest = pickLatestDoc(filenames, base);
+  return latest ? `${base}-v${latest.version + 1}.md` : `${base}.md`;
+}
+
+// Nomes de arquivo do diretório da feature ([] se ele ainda não existe).
+function readDir(featureDir) {
+  return featureDir && existsSync(featureDir) ? readdirSync(featureDir) : [];
+}
+
+/**
+ * Caminho do documento ATUAL (maior versão) — null se nenhum existe.
+ *
+ * @returns {{ path: string, version: number }|null}
+ */
+export function resolveDoc(featureDir, base) {
+  const latest = pickLatestDoc(readDir(featureDir), base);
+  return latest ? { path: path.join(featureDir, latest.file), version: latest.version } : null;
+}
+
+/**
+ * Caminho onde a geração deve escrever.
+ * - `force: true`  → próxima versão (nunca sobrescreve nada);
+ * - `force: false` → o documento atual (sobrescreve), ou `<base>.md` no 1º run.
+ *
+ * @returns {{ path: string, version: number, isNewVersion: boolean }}
+ */
+export function resolveWritePath(featureDir, base, { force = false } = {}) {
+  const files = readDir(featureDir);
+  if (!force) {
+    const latest = pickLatestDoc(files, base);
+    return latest
+      ? { path: path.join(featureDir, latest.file), version: latest.version, isNewVersion: false }
+      : { path: path.join(featureDir, `${base}.md`), version: 1, isNewVersion: false };
+  }
+  const name = nextDocName(files, base);
+  return { path: path.join(featureDir, name), version: parseDocVersion(name, base), isNewVersion: true };
+}

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,16 @@ 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:
+- **spec** e **plan** → geram a **próxima versão** em vez de sobrescrever: `spec.md` (v1) → `spec-v2.md` → `spec-v3.md`… As versões anteriores ficam intactas e a **maior versão passa a ser o documento atual** (veja *Documentos versionados*).
+- **decompose** → ignora o guard e **fecha as sub-issues da decomposição anterior** antes de gerar as novas (veja *Guard de idempotência*).
+
+Sem a label, `spec`/`plan` **sobrescrevem o documento atual** (comportamento de sempre).
+
 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 +193,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).
 >
@@ -239,11 +250,31 @@ Após o `generate-plan` e **antes** da criação de issues no `decompose`, um se
 - **Fluxo de resolução:** (1) leia o comentário 🔎 na issue; (2) corrija `spec.md`/`plan.md` (regenere com as labels ou edite e commite); (3) remova a label: `gh issue edit <n> --remove-label "spec-wave:critique-failed"`; (4) re-aplique `spec-wave:ready` para validar de novo.
 - Findings leves não bloqueiam — trate-os como revisão de qualidade.
 
+### Documentos versionados (`spec-v2.md`, `plan-v3.md`…)
+
+A primeira geração escreve `spec.md` e `plan.md` — a **v1**. Cada regeração **forçada** (label `spec-wave:force`) grava a **próxima versão** ao lado, sem tocar nas anteriores:
+
+```
+docs/features/<slug>/
+  spec.md       ← v1
+  spec-v2.md    ← 1ª regeração forçada
+  spec-v3.md    ← 2ª regeração forçada  ⬅ spec ATUAL
+  plan.md       ⬅ plano ATUAL (spec e plan versionam independente)
+```
+
+**A maior versão é sempre o documento atual** — é ela que o `generate-plan` usa como contexto, que o `validate` valida, que o `decompose` lê e que o `implement` anexa. Uma regeração **sem** force sobrescreve essa versão atual (não volta para o `spec.md` original).
+
+Ao mostrar os documentos ao usuário, use a versão atual; ofereça as anteriores só se ele quiser comparar. Nunca renomeie nem apague versões antigas por conta própria — elas são o histórico da Feature.
+
 ### Guard de idempotência do decompose (`spec-wave:decomposed`)
 
 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 +436,11 @@ 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): adicione `spec-wave:force` junto com o gatilho — o Action grava a **próxima versão** (`spec-v2.md`, `spec-v3.md`…) e preserva as anteriores; a nova passa a ser a spec atual. Sem o force, a versão atual é **sobrescrita** (edições manuais se perdem) — avise antes de acionar assim.
+   ```bash
+   gh issue edit <número> --add-label "spec-wave:force" --add-label "spec-wave:spec"
+   ```
+6. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
 
 ---
 
@@ -424,7 +459,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**: adicione `spec-wave:force` junto com `spec-wave:plan` — grava `plan-v2.md`, `plan-v3.md`… preservando as anteriores. Sem o force, o plano atual é sobrescrito (confirme antes).
+7. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
 
 ---
 
@@ -516,7 +552,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).
 
 ---
 
@@ -682,8 +718,12 @@ Audita um Pull Request e corrige automaticamente os problemas encontrados — se
 docs/
   features/
     <slug-da-feature>/
-      spec.md    ← gerado pelo GitHub Action quando spec-wave:spec é adicionado (1º)
-      plan.md    ← gerado pelo GitHub Action quando spec-wave:plan é adicionado (2º, usa a spec)
+      spec.md       ← gerado quando spec-wave:spec é adicionado (1º) = v1
+      spec-v2.md    ← regeração forçada (spec-wave:force); v1 preservada
+      plan.md       ← gerado quando spec-wave:plan é adicionado (2º, usa a spec ATUAL) = v1
+      plan-v2.md    ← regeração forçada do plano
 ```
 
+A **maior versão de cada tipo é o documento atual** (aqui: `spec-v2.md` e `plan-v2.md`) — veja *Documentos versionados*.
+
 O slug é gerado a partir do título da issue: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`