@spec-wave/cli 0.16.3 → 0.16.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.16.3",
+  "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/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/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.3",
+  "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",