@spec-wave/cli 0.12.0 → 0.13.0

package/README.md

@@ -85,27 +85,6 @@ 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,7 +132,6 @@ 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); });
@@ -142,7 +141,6 @@ 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); });
@@ -161,7 +159,6 @@ 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.12.0",
+  "version": "0.13.0",
   "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,7 +198,6 @@ export async function listSubIssues(token, issueNodeId) {
               number
               title
               body
-              state
               labels(first: 20) { nodes { name } }
             }
           }
@@ -212,9 +211,6 @@ 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,19 +101,6 @@ 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,10 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, 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 { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy } from '../api/github-rest.mjs';
+import { addSubIssue, listSubIssues } 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';
@@ -12,10 +10,7 @@ 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, LABEL_FORCE,
-  TARGET_LANGUAGE, STAGE_READY, STAGE_DEVELOPMENT, STAGE_ORDER, PROGRESS_TODO,
-} from '../config.mjs';
+import { DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, TARGET_LANGUAGE, STAGE_READY, 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).
@@ -91,19 +86,13 @@ 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, force = false } = {}) {
-  if (force) return { skip: false, reason: '' };
-
+export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {}) {
   const names = labels
     .map(l => (typeof l === 'string' ? l : l?.name))
     .filter(Boolean);
@@ -123,103 +112,6 @@ export function shouldSkipDecompose({ labels = [], subIssues = [], type, force =
   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) {
@@ -286,18 +178,14 @@ async function decomposeFeature(ctx) {
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
 
-  // 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)';
+  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)';
 
   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}`,
@@ -313,8 +201,8 @@ async function decomposeFeature(ctx) {
   try {
     critique = await runCritique({
       kind: 'stories',
-      spec: spec ? specContent : null,
-      plan: plan ? planContent : null,
+      spec: existsSync(`${featureDir}/spec.md`) ? specContent : null,
+      plan: existsSync(`${featureDir}/plan.md`) ? planContent : null,
       stories: decomposition.stories,
       usage,
     });
@@ -485,7 +373,7 @@ async function decomposeRFC(ctx) {
   console.log(`Decomposição concluída: ${created.length} tasks criadas.`);
 }
 
-export async function decompose({ issueNumber, force = false }) {
+export async function decompose({ issueNumber }) {
   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).
@@ -524,25 +412,17 @@ export async function decompose({ issueNumber, force = false }) {
     console.warn(`Não foi possível listar sub-issues: ${err.message} — seguindo sem o guard de sub-issues.`);
     subIssues = [];
   }
-  // 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 });
+  const guard = shouldSkipDecompose({ labels: issue.labels || [], subIssues, type });
   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}.\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.'
+      `⏭️ **decompose ignorado:** ${guard.reason}. Para forçar, remova a label ` +
+      `\`${LABEL_DECOMPOSED}\` (e apague as sub-issues antigas se quiser re-gerar).`
     ).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();
@@ -565,11 +445,8 @@ export async function decompose({ issueNumber, force = false }) {
   // 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, type, project, etapaField, statusField, usage: usageEntries };
+  const ctx = { token, projectToken, owner, repo, issue, issueNumber, 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 } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } 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,8 +8,6 @@ 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
@@ -43,7 +41,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, force = false }) {
+export async function generatePlan({ issueNumber }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
 
@@ -71,22 +69,13 @@ export async function generatePlan({ issueNumber, force = false }) {
     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 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.`);
+  const filePath = `${featureDir}/plan.md`;
 
-  // 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.`);
+  // 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;
 
   // Tech context (RFC-002 §4): estático + dinâmico + override do corpo da issue.
   const tech = buildTechContext({ issueBody: issue.body || '' });
@@ -124,7 +113,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 v${target.version} for ${slug} [spec-wave]"`);
+    git(`git commit -m "docs: generate plan.md for ${slug} [spec-wave]"`);
     git('git pull --rebase');
     git('git push');
 
@@ -134,12 +123,8 @@ export async function generatePlan({ issueNumber, force = false }) {
     // Comment on issue
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
-      `📋 **plano técnico gerado automaticamente** (v${target.version})\n\n` +
+      `📋 **plan.md gerado automaticamente!**\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,8 +5,6 @@ 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';
 
@@ -43,7 +41,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, force = false }) {
+export async function generateSpec({ issueNumber }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
 
@@ -72,17 +70,9 @@ export async function generateSpec({ issueNumber, force = false }) {
     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 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.`);
+  const filePath = `${featureDir}/spec.md`;
 
   // Payload estruturado (RFC-002 §5.1): metadata + entrada de negócio.
   const payload = {
@@ -117,7 +107,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 v${target.version} for ${slug} [spec-wave]"`);
+    git(`git commit -m "docs: generate spec.md for ${slug} [spec-wave]"`);
     git('git pull --rebase');
     git('git push');
 
@@ -127,12 +117,8 @@ export async function generateSpec({ issueNumber, force = false }) {
     // Comment on issue
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
-      `📋 **spec gerada automaticamente** (v${target.version})\n\n` +
+      `📋 **spec.md gerado automaticamente!**\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,7 +14,6 @@ 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';
 
@@ -42,16 +41,15 @@ async function resolveFeature(token, startNodeId) {
   return null;
 }
 
-// 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.
+// Lê spec.md/plan.md de um docs/features/<slug> se existirem.
 function readSpecPlan(featureDir) {
-  const spec = resolveDoc(featureDir, 'spec');
-  const plan = resolveDoc(featureDir, 'plan');
+  const specPath = path.join(featureDir, 'spec.md');
+  const planPath = path.join(featureDir, 'plan.md');
   return {
-    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,
+    specPath,
+    planPath,
+    spec: existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null,
+    plan: existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null,
   };
 }
 

package/src/commands/validate.mjs

@@ -3,7 +3,6 @@ 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';
 
@@ -40,39 +39,37 @@ export async function validate({ issueNumber }) {
     );
   }
 
-  // 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) {
+  // Check plan.md
+  const planPath = `${featureDir}/plan.md`;
+  if (!existsSync(planPath)) {
     errors.push('❌ `plan.md` não encontrado em `' + planPath + '`');
   } else {
-    const planContent = readFileSync(plan.path, 'utf-8');
+    const planContent = readFileSync(planPath, 'utf-8');
     for (const section of REQUIRED_PLAN_SECTIONS) {
       if (!planContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no plano (v${plan.version}): **${section}**`);
+        errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
       }
     }
     for (const problem of findIncompleteDocSigns(planContent)) {
-      errors.push(`❌ \`${planPath}\` parece incompleto: ${problem}`);
+      errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
     }
   }
 
-  const spec = resolveDoc(featureDir, 'spec');
-  const specPath = spec?.path || `${featureDir}/spec.md`;
-  if (!spec) {
+  // Check spec.md
+  const specPath = `${featureDir}/spec.md`;
+  if (!existsSync(specPath)) {
     errors.push('❌ `spec.md` não encontrado em `' + specPath + '`');
   } else {
-    const specContent = readFileSync(spec.path, 'utf-8');
+    const specContent = readFileSync(specPath, 'utf-8');
     for (const section of REQUIRED_SPEC_SECTIONS) {
       if (!specContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente na spec (v${spec.version}): **${section}**`);
+        errors.push(`❌ Seção obrigatória ausente no spec.md: **${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(`❌ \`${specPath}\` parece incompleto: ${problem}`);
+      errors.push(`❌ \`spec.md\` parece incompleto: ${problem}`);
     }
   }
 

package/src/config.mjs

@@ -183,10 +183,6 @@ 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'      },
@@ -196,7 +192,6 @@ 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/templates/skill/SKILL.md

@@ -105,16 +105,6 @@ 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`.
 
 ---
@@ -193,7 +183,6 @@ 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).
 >
@@ -250,31 +239,11 @@ 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**, 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.
+**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`.
 
 ### Dependências entre Stories (`Depende de: #N`)
 
@@ -436,11 +405,7 @@ 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): 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>`.
+5. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
 
 ---
 
@@ -459,8 +424,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**: 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>`.
+6. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
 
 ---
 
@@ -552,7 +516,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 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).
+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*.
 
 ---
 
@@ -718,12 +682,8 @@ Audita um Pull Request e corrige automaticamente os problemas encontrados — se
 docs/
   features/
     <slug-da-feature>/
-      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
+      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)
 ```
 
-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`

package/src/lib/feature-docs.mjs

@@ -1,89 +0,0 @@
-// 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

@@ -1,34 +0,0 @@
-// 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(() => {});
-}