@spec-wave/cli 0.16.1 → 0.16.4

package/package.json

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

package/src/commands/doctor.mjs

@@ -282,6 +282,34 @@ async function checkConfig(ctx) {
  * @param {string[]} [params.repoLabels] nomes das labels do repo
  * @returns {{ unknownStages: string[], missingStages: string[], orphanLabels: string[], missingLabels: string[] }}
  */
+/**
+ * Os ids de opção do .spec-wave.json batem com os do Project? (função PURA)
+ *
+ * Compara ID, não nome. `inspectBoardHygiene` compara nomes — e é justamente
+ * essa cegueira que deixou passar dois defeitos: o `refresh --stages` que
+ * recriava as opções, e o config commitado defasado.
+ *
+ * Por que importa: o que liga um item do board à coluna é o id. Um
+ * `.spec-wave.json` com ids velhos faz TODA escrita de Etapa falhar com "The
+ * single select option Id does not belong to the field" — e a falha é
+ * best-effort em quase todo caminho (implement, code-review, qa), então o card
+ * simplesmente não se move e ninguém percebe.
+ *
+ * Acontece sempre que alguém roda `refresh --config` e não commita: quem clona
+ * o repo — o dev-agent, o runner do Action — lê a versão velha.
+ *
+ * @param {object} params
+ * @param {Record<string,string>|null} [params.configOptions] nome → id do config
+ * @param {Record<string,string>|null} [params.boardOptions] nome → id do Project
+ * @returns {{ staleIds: string[], checked: boolean }}
+ */
+export function inspectStageIds({ configOptions = null, boardOptions = null } = {}) {
+  if (!configOptions || !boardOptions) return { staleIds: [], checked: false };
+  const staleIds = Object.keys(configOptions)
+    .filter(name => boardOptions[name] && boardOptions[name] !== configOptions[name]);
+  return { staleIds, checked: true };
+}
+
 export function inspectBoardHygiene({ boardStages = null, repoLabels = null } = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
@@ -396,6 +424,24 @@ async function checkBoardHygiene(ctx) {
       'do campo "Etapa" e rode `refresh --config`.'
     );
   }
+  // Divergência de ID entre o config e o Project: invisível para quem só
+  // compara nomes, e fatal para toda escrita de Etapa.
+  const { staleIds, checked } = inspectStageIds({
+    configOptions: cfg.project.fields?.['Etapa']?.options ?? null,
+    boardOptions: snapshot?.fields?.['Etapa']?.options ?? null,
+  });
+  if (checked && staleIds.length > 0) {
+    status = 'warn';
+    notes.push(
+      `${CONFIG_FILE} com ids de opção DEFASADOS (${staleIds.length} de ` +
+      `${Object.keys(cfg.project.fields['Etapa'].options).length}): ${staleIds.join(', ')}. ` +
+      'Toda escrita de Etapa falha com "The single select option Id does not belong to the ' +
+      'field" — e a falha é best-effort, então o card não se move e nada é reportado. ' +
+      `Rode \`refresh --config\` e **commite** o ${CONFIG_FILE}: quem clona o repo ` +
+      '(dev-agent, runner do Action) lê a versão commitada.'
+    );
+  }
+
   const { missingTrackStages } = inspectBugTrack({ boardStages, openBugCount });
   if (missingTrackStages.length > 0) {
     status = 'warn';

package/src/commands/generate-bug.mjs

@@ -15,6 +15,7 @@ import {
   getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
 } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
+import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
@@ -103,7 +104,7 @@ export async function generateBug({ issueNumber }) {
   try {
     console.log(`Gerando bug.md para: ${issue.title}`);
     const systemPrompt = toolFreeSystemPrompt(loadPrompt('bug', { cwd: root }));
-    const { content } = await generateDocument(systemPrompt, userContent, {
+    const { content: bruto } = await generateDocument(systemPrompt, userContent, {
       action: 'bug',
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
@@ -111,6 +112,10 @@ export async function generateBug({ issueNumber }) {
       usage: usageEntries,
     });
 
+    // O modelo às vezes entrega o documento embrulhado em prosa e cerca —
+    // ver lib/unwrap-doc.mjs. O que vai para o repositório é o documento.
+    const content = unwrapGeneratedDoc(bruto);
+
     mkdirSync(dirAbs, { recursive: true });
     writeFileSync(fileAbs, content, 'utf-8');
 

package/src/commands/generate-plan.mjs

@@ -10,6 +10,7 @@ import {
   LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
 } from '../config.mjs';
 import { generateDocument } from '../lib/claude.mjs';
+import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
 import {
   runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
 } from '../lib/critique.mjs';
@@ -165,7 +166,7 @@ export async function generatePlan({ issueNumber }) {
   try {
     console.log(`Gerando plan.md para: ${issue.title}`);
     const systemPrompt = toolFreeSystemPrompt(loadPrompt('plan', { cwd: root }));
-    const { content, lintFindings } = await generateDocument(systemPrompt, userContent, {
+    const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
       action: 'plan',
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
@@ -173,6 +174,10 @@ export async function generatePlan({ issueNumber }) {
       usage: usageEntries,
     });
 
+    // O modelo às vezes entrega o documento embrulhado em prosa e cerca —
+    // ver lib/unwrap-doc.mjs. O que vai para o repositório é o documento.
+    const content = unwrapGeneratedDoc(bruto);
+
     const published = commitGenerated({
       filePath,
       content,

package/src/commands/generate-spec.mjs

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
+import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { resolveFromRoot } from '../lib/project-root.mjs';
@@ -79,7 +80,7 @@ export async function generateSpec({ issueNumber }) {
   try {
     console.log(`Gerando spec.md para: ${issue.title}`);
     const systemPrompt = toolFreeSystemPrompt(loadPrompt('spec', { cwd: root }));
-    const { content, lintFindings } = await generateDocument(systemPrompt, userContent, {
+    const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
       action: 'spec',
       labels: issueLabels,
       lint: { lang: TARGET_LANGUAGE },
@@ -87,6 +88,10 @@ export async function generateSpec({ issueNumber }) {
       usage: usageEntries,
     });
 
+    // O modelo às vezes entrega o documento embrulhado em prosa e cerca —
+    // ver lib/unwrap-doc.mjs. O que vai para o repositório é o documento.
+    const content = unwrapGeneratedDoc(bruto);
+
     const published = commitGenerated({
       filePath,
       content,

package/src/commands/implement.mjs

@@ -8,10 +8,11 @@ import {
   CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE, STAGE_ORDER,
   PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE, labelNames,
 } from '../config.mjs';
-import { getIssue, listIssueComments, listBlockedBy } from '../api/github-rest.mjs';
+import { getIssue, listIssueComments, listBlockedBy, getFileContent } from '../api/github-rest.mjs';
 import { listSubIssues, getIssueParent, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
+import { missingDocMessage, existsOnRemote } from '../lib/doc-availability.mjs';
 import { buildBugContext } from '../lib/bug-context.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
@@ -393,7 +394,14 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
     bugDoc = readFileSync(fileAbs, 'utf-8');
     p.log.info(`bug.md encontrado em ${chalk.cyan(fileRel)}.`);
   } else {
-    p.log.warn(`Sem bug.md em ${fileRel} — o contexto assume a investigação inteira.`);
+    const onRemote = await existsOnRemote({
+      getFileContent, token, owner, repo, pathRel: fileRel,
+    });
+    p.log.warn(missingDocMessage({
+      pathRel: fileRel,
+      onRemote,
+      fallback: 'o contexto assume a investigação inteira.',
+    }));
   }
 
   // Board: Bug → Desenvolvimento (In Progress). Não move a Feature-pai.
@@ -564,7 +572,15 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   if (existsSync(featureDir)) {
     specPlan = readSpecPlan(featureDir);
   } else {
-    p.log.warn(`Diretório da feature não encontrado (${featureDir}); seguindo só com as Stories.`);
+    const specRel = `docs/features/${slugify(feature.title)}/spec.md`;
+    const onRemote = await existsOnRemote({
+      getFileContent, token, owner, repo, pathRel: specRel,
+    });
+    p.log.warn(missingDocMessage({
+      pathRel: specRel,
+      onRemote,
+      fallback: 'seguindo só com as Stories.',
+    }));
   }
 
   // F7. Dependências EXTERNAS ainda abertas (da Feature e das Stories pendentes)
@@ -754,7 +770,17 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   if (featureDir && existsSync(featureDir)) {
     specPlan = readSpecPlan(featureDir);
   } else if (featureDir) {
-    p.log.warn(`Diretório da feature não encontrado (${featureDir}); seguindo só com as tasks.`);
+    const specRel = feature?.title
+      ? `docs/features/${slugify(feature.title)}/spec.md`
+      : featureDir;
+    const onRemote = feature?.title
+      ? await existsOnRemote({ getFileContent, token, owner, repo, pathRel: specRel })
+      : null;
+    p.log.warn(missingDocMessage({
+      pathRel: specRel,
+      onRemote,
+      fallback: 'seguindo só com as tasks.',
+    }));
   } else {
     p.log.warn('Não foi possível resolver a Feature; seguindo só com as tasks (use --feature-dir).');
   }

package/src/commands/refresh.mjs

@@ -279,5 +279,13 @@ export async function refresh(options = {}) {
     `${chalk.dim('Versão CLI:')} ${pkg.version}`,
     'Configuração atualizada'
   );
-  p.outro(`${CONFIG_FILE} atualizado. Faça commit do arquivo para versioná-lo.`);
+  // O commit não é opcional: quem CLONA o repo — o dev-agent e o runner do
+  // Action — lê a versão commitada, não a local. Um config não commitado após
+  // mudança de board faz toda escrita de Etapa falhar em silêncio para eles.
+  p.log.warn(
+    `Commite o ${CONFIG_FILE} agora: ele guarda os IDS das opções do board, e quem ` +
+    'clona o repositório (dev-agent, GitHub Actions) lê a versão commitada. Sem o ' +
+    'commit, os cards deixam de se mover para eles — sem erro visível.'
+  );
+  p.outro(`${CONFIG_FILE} atualizado.  git add ${CONFIG_FILE} && git commit -m "chore: sincroniza o board"`);
 }

package/src/commands/update.mjs

@@ -596,7 +596,7 @@ export async function update(options = {}) {
     (skillJobs.length ? ' Recarregue o agente para pegar a skill nova.' : '') +
     (prUrl ? ` Revise e faça o merge do Pull Request: ${prUrl}` : '') +
     (!prMode && repoFiles.length ? ' Arquivos do repo foram commitados no remoto.' : '') +
-    (configPending ? ` Faça commit do ${CONFIG_FILE}.` : '') +
+    (configPending ? ` COMMITE o ${CONFIG_FILE} — quem clona o repo (dev-agent, Actions) lê a versão commitada.` : '') +
     (finalConfigDecision.included
       ? ` O ${CONFIG_FILE} local ficou igual ao do PR — depois do merge, descarte a cópia ` +
         `local com \`git checkout -- ${CONFIG_FILE}\`.`

package/src/lib/doc-availability.mjs

@@ -0,0 +1,52 @@
+// Documento ausente LOCALMENTE não é a mesma coisa que documento inexistente.
+//
+// spec.md, plan.md e bug.md são gerados por GitHub Action e commitados no
+// REMOTO. Quem roda `implement` logo depois — que é o caso comum, porque a
+// geração é o passo anterior — tem o arquivo no repositório e não no clone.
+//
+// A mensagem antiga dizia "sem bug.md — o contexto assume a investigação
+// inteira", mandando o executor investigar do zero quando bastava um
+// `git pull`. Encontrado no smoke test do RFC-004.
+//
+// Decisão em função pura, I/O na função imperativa: a mensagem é testável sem
+// rede, e a consulta ao remoto é best-effort (nunca lança, nunca bloqueia).
+
+/**
+ * Mensagem para um documento ausente no clone local (função PURA).
+ *
+ * @param {object} params
+ * @param {string} params.pathRel caminho do documento, relativo à raiz do repo
+ * @param {boolean|null} params.onRemote true = existe no remoto; false = não
+ *   existe; null = não foi possível consultar (sem token/rede)
+ * @param {string} params.fallback o que o comando fará sem o documento
+ * @returns {string}
+ */
+export function missingDocMessage({ pathRel, onRemote, fallback }) {
+  if (onRemote === true) {
+    return (
+      `${pathRel} existe no repositório mas NÃO no seu clone — rode \`git pull\` e ` +
+      'repita o comando. Seguir agora ignoraria o documento já gerado.'
+    );
+  }
+  if (onRemote === false) {
+    return `Sem ${pathRel} no repositório — ${fallback}`;
+  }
+  return (
+    `Sem ${pathRel} no clone local (não foi possível consultar o remoto) — ${fallback} ` +
+    'Se o documento já foi gerado, rode `git pull` antes.'
+  );
+}
+
+/**
+ * O documento existe no remoto? Best-effort — NUNCA lança.
+ *
+ * @returns {Promise<boolean|null>} null quando não deu para consultar
+ */
+export async function existsOnRemote({ getFileContent, token, owner, repo, pathRel }) {
+  if (!token || !owner || !repo) return null;
+  try {
+    return (await getFileContent(token, owner, repo, pathRel)) != null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/unwrap-doc.mjs

@@ -0,0 +1,64 @@
+// O modelo às vezes ENTREGA o documento em vez de SER o documento.
+//
+// Encontrado no smoke test do RFC-004: o bug.md commitado começava com
+// "Investigação concluída. […] segue o conteúdo completo do bug.md para ser
+// salvo na raiz do repositório:", trazia o documento dentro de uma cerca
+// ```markdown, e terminava com "Resumo do que foi feito: …".
+//
+// Passou pelo `validate` porque a checagem é `content.includes('# Seção')` —
+// e as seções estavam lá, dentro da cerca. O arquivo versionado ficou com
+// texto conversacional que ninguém pediu, e o `implement` entrega isso ao
+// executor como se fosse o documento.
+//
+// Não dá para resolver só no prompt: pedir "responda apenas com o markdown"
+// já está lá, e o modelo desobedece quando acha que precisa explicar algo.
+// Este módulo trata a saída, que é o único ponto sob nosso controle.
+
+/**
+ * Extrai o documento de uma resposta que pode vir embrulhada (função PURA).
+ *
+ * Dois formatos tratados, nesta ordem:
+ *  1. **Cerca envolvente** — o documento inteiro dentro de ```markdown … ```,
+ *     com preâmbulo antes e/ou epílogo depois. Só é tratada como envolvente a
+ *     cerca que aparece ANTES do primeiro heading: uma cerca depois do
+ *     primeiro heading é bloco de código legítimo DO documento.
+ *  2. **Preâmbulo solto** — texto antes do primeiro heading, sem cerca.
+ *
+ * Conteúdo já limpo passa intacto.
+ *
+ * @param {string} raw resposta do modelo
+ * @returns {string}
+ */
+export function unwrapGeneratedDoc(raw) {
+  const text = String(raw ?? '').trim();
+  if (!text) return text;
+
+  const lines = text.split('\n');
+  const abreCerca = /^\s*```+\s*(markdown|md)?\s*$/i;
+  const fechaCerca = /^\s*```+\s*$/;
+  const heading = /^\s{0,3}#{1,6}\s+\S/;
+
+  const primeiroHeading = lines.findIndex(l => heading.test(l));
+  const primeiraCerca = lines.findIndex(l => abreCerca.test(l));
+
+  // (1) Cerca envolvente: abre antes de qualquer heading e fecha depois.
+  if (primeiraCerca !== -1 && (primeiroHeading === -1 || primeiraCerca < primeiroHeading)) {
+    // A cerca de fechamento é a ÚLTIMA do texto — cercas internas pertencem ao
+    // documento (blocos de código nas seções) e não podem encerrar o embrulho.
+    let ultimaCerca = -1;
+    for (let i = lines.length - 1; i > primeiraCerca; i -= 1) {
+      if (fechaCerca.test(lines[i])) { ultimaCerca = i; break; }
+    }
+    if (ultimaCerca > primeiraCerca) {
+      const dentro = lines.slice(primeiraCerca + 1, ultimaCerca).join('\n').trim();
+      if (dentro) return dentro;
+    }
+  }
+
+  // (2) Preâmbulo sem cerca: começa no primeiro heading.
+  if (primeiroHeading > 0) {
+    return lines.slice(primeiroHeading).join('\n').trim();
+  }
+
+  return text;
+}

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.16.1",
+  "version": "0.16.4",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",