@spec-wave/cli 0.11.1 → 0.12.0

package/README.md

@@ -91,7 +91,20 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 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`.
+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`)
 

package/package.json

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

package/src/commands/decompose.mjs

@@ -1,9 +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, 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';
@@ -285,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}`,
@@ -308,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,
     });

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';
@@ -9,6 +9,7 @@ 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
@@ -70,18 +71,22 @@ export async function generatePlan({ issueNumber, force = false }) {
     return;
   }
 
-  // Ver generate-spec: não há guard aqui — a label já regera e sobrescreve.
+  // 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));
-  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`;
+  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 || '' });
@@ -119,7 +124,7 @@ export async function generatePlan({ issueNumber, force = false }) {
     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');
 
@@ -129,8 +134,12 @@ export async function generatePlan({ issueNumber, force = false }) {
     // 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

@@ -6,6 +6,7 @@ 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';
 
@@ -71,16 +72,17 @@ export async function generateSpec({ issueNumber, force = false }) {
     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).
+  // 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));
-  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`;
+  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 = {
@@ -115,7 +117,7 @@ export async function generateSpec({ issueNumber, force = false }) {
     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');
 
@@ -125,8 +127,12 @@ export async function generateSpec({ issueNumber, force = false }) {
     // 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/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/templates/skill/SKILL.md

@@ -109,7 +109,11 @@ Label **modificadora** — `spec-wave:force`: sozinha **não dispara nada**; adi
 ```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.
+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`.
 
@@ -246,6 +250,22 @@ 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.
@@ -416,7 +436,10 @@ 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. **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.
+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>`.
 
 ---
@@ -436,7 +459,7 @@ 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. **Para regerar**: re-adicione a label — o Action sobrescreve o `plan.md` (mesma ressalva do spec: edições manuais se perdem, confirme antes).
+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>`.
 
 ---
@@ -695,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`