@spec-wave/cli 0.24.0 → 0.25.0

package/src/commands/run.mjs

@@ -0,0 +1,396 @@
+// Executa LOCALMENTE o passo que a label dispararia no GitHub Actions.
+//
+// O YAML nunca fez trabalho nenhum: ele instala a CLI e chama um comando. Este
+// comando fecha o buraco que sobra quando os workflows estão desarmados
+// (`spec-wave mode local`) — decidir QUAL comando é o próximo e chamá-lo, sem
+// aplicar label nenhuma.
+//
+// A decisão é uma função pura (`lib/next-step.mjs`), testada sem rede. Aqui só
+// mora o que é impuro: coletar o estado, segurar o lock, despachar e relatar.
+//
+// Três coisas que este comando NUNCA faz, e o porquê:
+//  • aplicar label de gatilho — dispararia o Action e a execução aconteceria duas vezes;
+//  • rodar dentro do Actions — lá o contrato é a label (`assertNotInActions`);
+//  • encadear passos sem teto — cada passo de IA custa dinheiro (`--max-steps`).
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue, getPR, getFileContent, listPullRequestReviews } from '../api/github-rest.mjs';
+import { loadProjectConfig } from '../lib/board.mjs';
+import { existsOnRemote } from '../lib/doc-availability.mjs';
+import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
+import { isActionsRun, resolveFlowContext } from '../lib/flow-run.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { nextStep, resolveForcedStep, STEPS } from '../lib/next-step.mjs';
+import { nextPrStep, reviewVerdict } from '../lib/pr-step.mjs';
+import { configuredMode } from '../lib/execution-mode.mjs';
+import { labelNames } from '../config.mjs';
+
+const LOCK_STALE_MS = 30 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Lock — o substituto do `concurrency: spec-wave-item-<n>` dos workflows.
+//
+// Sem ele, dois `run` na mesma issue geram dois documentos, dois commits
+// disputando a ponta da branch e leitura-modificação-escrita concorrente do
+// comentário de uso. Fica em .git/ porque já é ignorado e é por clone.
+// ---------------------------------------------------------------------------
+
+function lockPath(root, key) {
+  return path.join(root || process.cwd(), '.git', 'spec-wave', `run-${key}.lock`);
+}
+
+function acquireLock(root, key) {
+  const file = lockPath(root, key);
+  mkdirSync(path.dirname(file), { recursive: true });
+  const payload = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+  try {
+    writeFileSync(file, payload, { flag: 'wx' });
+    return file;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    let idade = Infinity;
+    let dono = null;
+    try {
+      dono = JSON.parse(readFileSync(file, 'utf-8'));
+      idade = Date.now() - Date.parse(dono.startedAt);
+    } catch { /* lock ilegível conta como velho */ }
+    if (idade < LOCK_STALE_MS) {
+      throw new Error(
+        `Já existe um \`spec-wave run\` para ${key} (pid ${dono?.pid ?? '?'}, desde ${dono?.startedAt ?? '?'}).\n` +
+        `Se tiver certeza de que morreu, apague ${file}.`
+      );
+    }
+    console.warn(`⚠️  Lock antigo encontrado (${file}) — assumindo processo morto e seguindo.`);
+    writeFileSync(file, payload);
+    return file;
+  }
+}
+
+function releaseLock(file) {
+  try {
+    if (file) unlinkSync(file);
+  } catch { /* já removido */ }
+}
+
+// Commits locais ainda não publicados: gerar o próximo documento por cima de um
+// anterior que ficou só no clone é execução parcial disfarçada de sucesso.
+function unpushedCommits(root) {
+  try {
+    const out = execSync('git rev-list --count @{u}..HEAD', {
+      cwd: root || process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return Number.parseInt(out, 10) || 0;
+  } catch {
+    return 0; // sem upstream configurado: não dá para afirmar nada
+  }
+}
+
+function assertNotInActions() {
+  if (!isActionsRun()) return;
+  throw new Error(
+    'O `run` é o gatilho do modo LOCAL — dentro do GitHub Actions o gatilho é a label, ' +
+    'e o workflow já chama o comando certo. Rodar os dois seria executar o passo duas vezes.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Coleta do estado
+// ---------------------------------------------------------------------------
+
+function localDocStates(issue, type, root) {
+  if (type === 'Bug') {
+    const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+    return {
+      docs: { bug: existsSync(fileAbs) ? 'local' : 'missing' },
+      docPaths: { bug: fileRel },
+    };
+  }
+  const paths = featureDocPaths(root, issue, type);
+  const docs = {};
+  const docPaths = {};
+  for (const nome of ['spec', 'plan', 'decomposition']) {
+    docs[nome] = existsSync(paths[nome].abs) ? 'local' : 'missing';
+    docPaths[nome] = paths[nome].rel;
+  }
+  return { docs, docPaths };
+}
+
+/**
+ * Sonda o remoto SÓ pelos documentos que o passo escolhido usa e que faltam no
+ * clone. É a diferença entre "ainda não foi gerado" e "foi gerado e você não
+ * puxou" — a segunda leva a sobrescrever trabalho publicado.
+ */
+async function probeRemote({ decision, docs, docPaths, token, owner, repo }) {
+  const step = STEPS[decision.action];
+  if (!step) return docs;
+  const alvos = [step.writes, ...step.reads]
+    .filter(Boolean)
+    .filter(doc => docs[doc] === 'missing');
+  if (alvos.length === 0) return docs;
+
+  const atualizado = { ...docs };
+  for (const doc of alvos) {
+    const onRemote = await existsOnRemote({
+      getFileContent, token, owner, repo, pathRel: docPaths[doc],
+    });
+    if (onRemote === true) atualizado[doc] = 'remote';
+    else if (onRemote === null) atualizado[doc] = 'unknown';
+  }
+  return atualizado;
+}
+
+// ---------------------------------------------------------------------------
+// Relato
+// ---------------------------------------------------------------------------
+
+function reportDecision(decision, { issueNumber, type, title, warnings }) {
+  console.log(chalk.bold(`\nIssue #${issueNumber} · ${type || 'tipo desconhecido'} · ${title}`));
+  console.log(`Próximo passo: ${chalk.cyan(decision.action)}`);
+  console.log(`Motivo: ${decision.reason}`);
+  if (decision.command) console.log(`Comando: ${chalk.dim(decision.command)}`);
+  for (const aviso of warnings) console.warn(chalk.yellow(`⚠️  ${aviso}`));
+  if (decision.blocked) {
+    console.log(chalk.yellow(`\n⛔ ${decision.blocked.code}: ${decision.blocked.message}`));
+    console.log(`   ${decision.blocked.unblock}`);
+  }
+}
+
+// O prefixo do título é o que os workflows filtram (`contains(title, '[FEATURE]')`),
+// enquanto detectIssueType tem fallback por label: sem o aviso, uma issue rodaria
+// local e nunca rodaria no runner, e a diferença só apareceria ao voltar o modo.
+function parityWarnings(issue, type) {
+  const avisos = [];
+  const titulo = String(issue.title || '');
+  if (type && !titulo.includes(`[${type.toUpperCase()}]`)) {
+    avisos.push(
+      `O título não traz o prefixo [${type.toUpperCase()}] — o workflow correspondente NÃO ` +
+      'dispararia para esta issue no modo actions (ele filtra pelo título).'
+    );
+  }
+  return avisos;
+}
+
+// ---------------------------------------------------------------------------
+// Despacho
+// ---------------------------------------------------------------------------
+
+async function dispatch(action, { issueNumber }) {
+  switch (action) {
+    case 'generate-spec': {
+      const { generateSpec } = await import('./generate-spec.mjs');
+      return await generateSpec({ issueNumber });
+    }
+    case 'generate-plan': {
+      const { generatePlan } = await import('./generate-plan.mjs');
+      return await generatePlan({ issueNumber });
+    }
+    case 'critique': {
+      const { critique } = await import('./generate-plan.mjs');
+      return await critique({ issueNumber });
+    }
+    case 'validate': {
+      const { validate } = await import('./validate.mjs');
+      return await validate({ issueNumber });
+    }
+    case 'decompose': {
+      const { decompose } = await import('./decompose.mjs');
+      return await decompose({ issueNumber, apply: false });
+    }
+    case 'decompose-apply': {
+      const { decompose } = await import('./decompose.mjs');
+      return await decompose({ issueNumber, apply: true });
+    }
+    case 'generate-bug': {
+      const { generateBug } = await import('./generate-bug.mjs');
+      return await generateBug({ issueNumber });
+    }
+    default:
+      throw new Error(`Passo sem despacho: ${action}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Modo PR
+// ---------------------------------------------------------------------------
+
+async function runForPr({ prNumber, dryRun, yes, only, json }) {
+  const { owner, repo, root } = resolveFlowContext({ command: 'run --pr' });
+  const token = await resolveToken();
+  const n = parseInt(prNumber, 10);
+
+  const pr = await getPR(token, owner, repo, n);
+  const reviews = await listPullRequestReviews(token, owner, repo, n);
+  const verdict = reviewVerdict(reviews);
+  const decision = nextPrStep({
+    state: pr.state,
+    draft: Boolean(pr.draft),
+    merged: Boolean(pr.merged_at),
+    approved: verdict.approved,
+    changesRequestedAfterApproval: verdict.changesRequestedAfterApproval,
+    only: only || null,
+  });
+
+  const { error: boardError } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (boardError) decision.warnings.push(`${boardError} — o board não será atualizado.`);
+
+  if (json) {
+    console.log(JSON.stringify({ pr: n, ...decision, approvers: verdict.approvers }, null, 2));
+  } else {
+    console.log(chalk.bold(`\nPR #${n} · ${pr.title}`));
+    console.log(`Passos: ${decision.steps.length ? chalk.cyan(decision.steps.join(' → ')) : '(nenhum)'}`);
+    console.log(`Motivo: ${decision.reason}`);
+    for (const aviso of decision.warnings) console.warn(chalk.yellow(`⚠️  ${aviso}`));
+    if (decision.blocked) console.log(chalk.yellow(`\n⛔ ${decision.blocked.code}: ${decision.blocked.message}`));
+  }
+
+  if (decision.blocked || decision.steps.length === 0) {
+    process.exitCode = decision.blocked ? 2 : 0;
+    return decision;
+  }
+  if (verdict.changesRequestedAfterApproval && !yes) {
+    console.log(chalk.yellow('\n⛔ needs-confirmation: há pedido de mudanças além da aprovação. Confirme com `--yes`.'));
+    process.exitCode = 2;
+    return decision;
+  }
+  if (dryRun) {
+    console.log(chalk.dim('\nDry-run: nada foi executado.'));
+    return decision;
+  }
+
+  const lock = acquireLock(root, `pr-${n}`);
+  try {
+    for (const step of decision.steps) {
+      console.log(chalk.bold(`\n▶ ${step} --pr-number ${n}`));
+      if (step === 'code-review') {
+        const { codeReview } = await import('./code-review.mjs');
+        await codeReview({ prNumber: String(n) });
+      } else {
+        const { qa } = await import('./qa.mjs');
+        await qa({ prNumber: String(n) });
+      }
+    }
+  } finally {
+    releaseLock(lock);
+  }
+  return decision;
+}
+
+// ---------------------------------------------------------------------------
+// Comando
+// ---------------------------------------------------------------------------
+
+export async function run(issueArg, options = {}) {
+  assertNotInActions();
+
+  const {
+    pr, dryRun = false, yes = false, apply = false, step: forced = null,
+    maxSteps = 1, force = false, remoteCheck = true, json = false, only = null,
+  } = options;
+
+  if (pr) return await runForPr({ prNumber: pr, dryRun, yes, only, json });
+
+  if (!issueArg) throw new Error('Informe o número da issue: `spec-wave run <issue>` (ou `--pr <n>`).');
+
+  const { owner, repo, root, config } = resolveFlowContext({ command: 'run' });
+  const token = await resolveToken();
+  const issueNumber = String(issueArg).replace(/^#/, '');
+  const teto = Math.max(1, parseInt(maxSteps, 10) || 1);
+
+  if (configuredMode(config) !== 'local') {
+    console.warn(chalk.yellow(
+      '⚠️  Este repositório está em modo `actions` — os workflows continuam armados e podem ' +
+      'rodar o mesmo passo. Use `spec-wave mode local` para desarmá-los.'
+    ));
+  }
+
+  const lock = acquireLock(root, issueNumber);
+  // `critiqueFile` seta process.exitCode = 1; sem preservar, um run inteiro
+  // bem-sucedido sairia com código de erro.
+  const exitCodeAntes = process.exitCode;
+  try {
+    let ultimaDecisao = null;
+
+    for (let i = 0; i < teto; i++) {
+      const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+      const type = detectIssueType(issue);
+      const { docs, docPaths } = localDocStates(issue, type, root);
+      const { error: boardError } = loadProjectConfig({ cwd: root || process.cwd() });
+
+      let forcedStep = null;
+      if (forced && i === 0) {
+        const resolvido = resolveForcedStep(forced, { type });
+        if (resolvido.error) throw new Error(resolvido.error);
+        forcedStep = resolvido.action;
+      }
+
+      const entrada = {
+        type,
+        issueNumber,
+        state: issue.state,
+        labels: labelNames(issue),
+        docPaths,
+        forcedStep,
+        confirmed: yes || apply,
+        boardReady: !boardError,
+        force,
+      };
+
+      let decision = nextStep({ ...entrada, docs });
+      if (remoteCheck && decision.action !== 'none' && !decision.blocked) {
+        const docsRemotos = await probeRemote({ decision, docs, docPaths, token, owner, repo });
+        decision = nextStep({ ...entrada, docs: docsRemotos });
+      }
+      ultimaDecisao = decision;
+
+      // `--apply` é uma asserção sobre o estado esperado, não um "faça o que for":
+      // se o passo pendente virou outro, errar é melhor que sobrescrever um documento.
+      if (apply && decision.action !== 'decompose-apply' && !yes) {
+        throw new Error(
+          `--apply autoriza especificamente o \`decompose-apply\`, mas o passo pendente é ` +
+          `\`${decision.action}\`. Use --yes se era isso mesmo que você queria.`
+        );
+      }
+
+      if (json) console.log(JSON.stringify({ issue: Number(issueNumber), type, ...decision }, null, 2));
+      else reportDecision(decision, { issueNumber, type, title: issue.title, warnings: parityWarnings(issue, type) });
+
+      if (decision.blocked) { process.exitCode = 2; break; }
+      if (decision.action === 'none') break;
+      if (dryRun) {
+        console.log(chalk.dim('\nDry-run: nada foi executado.'));
+        break;
+      }
+
+      console.log(chalk.bold(`\n▶ ${decision.command}\n`));
+      const resultado = await dispatch(decision.action, { issueNumber });
+      process.exitCode = exitCodeAntes;
+
+      // Reprova do validate é desfecho esperado, não exceção — mas encadear em
+      // cima dela repetiria o mesmo passo até esgotar `--max-steps`.
+      if (resultado?.ok === false) {
+        console.warn(chalk.yellow('\n⚠️  O passo terminou reprovado — corrija os problemas acima e repita.'));
+        process.exitCode = 2;
+        break;
+      }
+
+      const pendentes = unpushedCommits(root);
+      if (pendentes > 0) {
+        console.warn(chalk.yellow(
+          `\n⚠️  ${pendentes} commit(s) ainda não publicado(s). O próximo passo leria um documento ` +
+          'que só existe no seu clone — publique antes de continuar.'
+        ));
+        break;
+      }
+    }
+
+    return ultimaDecisao;
+  } finally {
+    releaseLock(lock);
+  }
+}

package/src/commands/validate.mjs

@@ -5,12 +5,15 @@ import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-r
 import { slugify } from '../lib/slugify.mjs';
 import {
   CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_BUG, LABEL_BUG_APPROVED,
+  LABEL_READY, LABEL_PLAN_APPROVED,
   REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, REQUIRED_BUG_SECTIONS, labelNames,
 } from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
 import { bugDocPaths, describeMissingSections } from '../lib/bug-doc.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
+import { executionMode } from '../lib/flow-run.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 
 /**
  * Validação do bug.md (RFC-004 §5).
@@ -55,7 +58,7 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
     }
   }
 
-  await removeLabel(token, owner, repo, n, 'spec-wave:ready');
+  await removeLabel(token, owner, repo, n, LABEL_READY);
 
   if (errors.length > 0) {
     await commentOnIssue(
@@ -65,18 +68,19 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
       `\n\nCorrija os problemas e adicione novamente a label \`spec-wave:ready\`.`
     );
     console.error('Validação falhou:', errors.join(', '));
-    process.exit(1);
+    return { ok: false, errors };
   }
 
   await addLabel(token, owner, repo, n, LABEL_BUG_APPROVED);
   await commentOnIssue(
     token, owner, repo, n,
     '✅ **bug.md validado.**\n\n' +
-    `📄 [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+    `📄 [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode: executionMode(), root })})\n\n` +
     'As seis seções obrigatórias estão presentes — reprodução, causa raiz e teste de ' +
     'regressão inclusive. O bug pode ser aceito na triagem.'
   );
   console.log('bug.md validado.');
+  return { ok: true, errors: [] };
 }
 
 /**
@@ -95,6 +99,17 @@ export function renderMissingSection(doc, { section, found }) {
     : base;
 }
 
+/**
+ * Valida os documentos de uma issue.
+ *
+ * Devolve o veredito em vez de chamar `process.exit(1)` na reprova: quem
+ * encerra o processo é o wrapper do `bin` (mesmo exit code no Actions), e assim
+ * o `run` consegue tratar a reprova como o desfecho ESPERADO que ela é — sem
+ * morrer no meio da cadeia, sem pular o `finally` e sem deixar o lock para trás.
+ *
+ * @param {{issueNumber: string|number}} params
+ * @returns {Promise<{ok: boolean, errors: string[]}>}
+ */
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
@@ -174,7 +189,7 @@ export async function validate({ issueNumber }) {
   }
 
   // Remove trigger label
-  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:ready');
+  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_READY);
 
   if (errors.length > 0) {
     await commentOnIssue(
@@ -199,11 +214,11 @@ export async function validate({ issueNumber }) {
     //
     // Regenerar é decisão humana, e o comentário acima diz como e o que custa.
     console.error('Validação falhou:', errors.join(', '));
-    process.exit(1);
+    return { ok: false, errors };
   }
 
   // Validação passou: adiciona label plan-approved.
-  await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan-approved');
+  await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_PLAN_APPROVED);
 
   await commentOnIssue(
     token, owner, repo, parseInt(issueNumber, 10),
@@ -216,4 +231,5 @@ export async function validate({ issueNumber }) {
   );
 
   console.log('Validação OK. Feature pronta para decomposição.');
+  return { ok: true, errors: [] };
 }

package/src/config.mjs

@@ -407,6 +407,9 @@ export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
 // pronta de uma que só foi movida à mão para ✅ Ready.
 export const LABEL_PLAN_APPROVED = 'spec-wave:plan-approved';
 // Gatilhos que REGERAM documento: presentes na issue, indicam etapa pendente.
+// `spec-wave:ready` era o único gatilho sem constante — e por isso aparecia como
+// string literal no validate, no YAML e em toda tabela que precisasse citá-lo.
+export const LABEL_READY = 'spec-wave:ready';
 export const LABEL_SPEC = 'spec-wave:spec';
 export const LABEL_PLAN = 'spec-wave:plan';
 // Achado GRAVE que o Tech Leader aceitou como risco conhecido. Fica na issue
@@ -422,7 +425,7 @@ export const TRIGGER_LABELS = [
   { name: LABEL_SPEC,                color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
   { name: LABEL_PLAN,                color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
   { name: LABEL_CRITIQUE,            color: 'BFD4F2', description: 'Re-criticar o plan.md COMO ESTÁ, sem regerar' },
-  { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
+  { name: LABEL_READY,               color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
   { name: LABEL_PLAN_APPROVED,       color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
   { name: LABEL_DECOMPOSE_APPLY,     color: 'BFD4F2', description: 'Aplicar o decomposition.md revisado: criar Stories e Tasks' },

package/src/lib/config-file.mjs

@@ -0,0 +1,62 @@
+// Escrita do `.spec-wave.json` — um lugar só.
+//
+// Havia três escritores, cada um com a sua lógica: `init` monta o objeto do zero
+// (e por isso descarta campos custom como `codeReview.linkMode` e `specKit`),
+// `refresh` faz merge preservando o resto, e `update` tem a mesma lógica do
+// refresh duplicada. Quem só precisa mexer em UM campo — o caso do `mode` — não
+// tinha por onde.
+//
+// A serialização é parte do contrato, não detalhe: `update` compara o config
+// byte a byte com o remoto para decidir se ele entra no PR (`lib/pr-branch.mjs`),
+// então um `\n` a mais no fim faria o arquivo entrar em toda execução.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+import { CONFIG_FILE } from '../config.mjs';
+import { findConfigPath } from './project-root.mjs';
+
+/**
+ * Serialização canônica do config (função PURA).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+export function serializeConfig(config) {
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+/**
+ * Aplica uma mutação ao `.spec-wave.json` preservando todo o resto.
+ *
+ * O mutator recebe uma CÓPIA e pode alterá-la no lugar ou devolver outro objeto.
+ * Gravação idempotente: conteúdo idêntico não reescreve o arquivo (não suja o
+ * mtime nem o `git status` de quem só consultou).
+ *
+ * @param {(config: object) => object|void} mutator
+ * @param {{cwd?: string}} [options]
+ * @returns {{configPath: string, config: object, changed: boolean}}
+ */
+export function updateConfig(mutator, { cwd = process.cwd() } = {}) {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) {
+    throw new Error(
+      `${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` neste repositório.`,
+    );
+  }
+
+  const raw = readFileSync(configPath, 'utf-8');
+  let current;
+  try {
+    current = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${CONFIG_FILE} está corrompido (${err.message}) — corrija-o à mão antes.`);
+  }
+
+  const draft = structuredClone(current);
+  const next = mutator(draft) ?? draft;
+  const content = serializeConfig(next);
+  if (content === raw) return { configPath, config: next, changed: false };
+
+  writeFileSync(configPath, content);
+  return { configPath, config: next, changed: true };
+}

package/src/lib/doc-paths.mjs

@@ -0,0 +1,51 @@
+// Onde mora cada documento do fluxo, a partir do TÍTULO da issue.
+//
+// O slug vem do título (`slugify`), então renomear a issue muda o diretório —
+// motivo pelo qual o `run` compara o que as labels afirmam com o que existe no
+// clone antes de decidir qualquer coisa.
+//
+// Funções PURAS: montam caminhos, não tocam o filesystem.
+
+import path from 'node:path';
+
+import { slugify } from './slugify.mjs';
+
+export { bugDocPaths } from './bug-doc.mjs';
+
+/**
+ * Diretório do documento por tipo de issue.
+ *
+ * Feature usa o mesmo `docs/features/<slug>` da spec/plan; RFC ganha o seu, já
+ * que não passa por spec/plan.
+ *
+ * @param {string|null} root raiz do repositório (ausente = process.cwd())
+ * @param {{title?: string}} issue
+ * @param {string|null} [type] tipo canônico ('Feature', 'RFC', ...)
+ * @returns {{slug: string, rel: string, dir: string}}
+ */
+export function resolveDocDir(root, issue, type) {
+  const slug = slugify(issue?.title || '');
+  const rel = type === 'RFC' ? `docs/rfcs/${slug}` : `docs/features/${slug}`;
+  return { slug, rel, dir: path.resolve(root || process.cwd(), rel) };
+}
+
+/**
+ * Caminhos dos três documentos de uma Feature/RFC (função PURA).
+ *
+ * @param {string|null} root
+ * @param {{title?: string}} issue
+ * @param {string|null} [type]
+ * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition}} cada documento com {rel, abs}
+ */
+export function featureDocPaths(root, issue, type) {
+  const { slug, rel, dir } = resolveDocDir(root, issue, type);
+  const doc = name => ({ rel: `${rel}/${name}`, abs: path.join(dir, name) });
+  return {
+    slug,
+    dirRel: rel,
+    dirAbs: dir,
+    spec: doc('spec.md'),
+    plan: doc('plan.md'),
+    decomposition: doc('decomposition.md'),
+  };
+}