@spec-wave/cli 0.16.3 → 0.17.0

package/package.json

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

package/src/commands/decompose.mjs

@@ -26,7 +26,10 @@ import {
 import { addSubIssue, listSubIssues } from '../api/github-graphql.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
 import { generateDocument } from '../lib/claude.mjs';
-import { runCritique, resolveCritiqueAttempt, renderNeedsHumanComment } from '../lib/critique.mjs';
+import {
+  runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
+  parseCritiqueDecisions, applyCritiqueDecisions, renderRiskAcceptedComment,
+} from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { formatDependencyLine } from '../lib/dependencies.mjs';
 import { lintLanguage } from '../lib/output-lint.mjs';
@@ -40,7 +43,7 @@ import {
 } from '../lib/decomposition-doc.mjs';
 import {
   DECOMPOSE_TARGETS, LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY, LABEL_DECOMPOSE_READY,
-  LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, TARGET_LANGUAGE,
+  LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_RISK_ACCEPTED, TARGET_LANGUAGE,
   STAGE_READY, PROGRESS_TODO, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
 } from '../config.mjs';
 
@@ -294,6 +297,8 @@ async function draftDecomposition(ctx) {
   const { attempt, blocked } = resolveCritiqueAttempt({
     comments: ctx.comments, labels, kind: 'stories', maxAttempts: ctx.maxCritiqueAttempts,
   });
+  // Decisões do TL sobre findings anteriores desta decomposição.
+  const decisions = parseCritiqueDecisions(ctx.comments, 'stories');
   if (blocked) {
     console.log(`Teto de ${ctx.maxCritiqueAttempts} tentativas de crítica atingido — exigindo revisão humana.`);
     await commentOnIssue(token, owner, repo, number, renderNeedsHumanComment({
@@ -318,6 +323,7 @@ async function draftDecomposition(ctx) {
   try {
     critique = await runCritique({
       kind: 'stories',
+      decisions,
       spec: specContent,
       plan: planContent,
       decomposition: markdown,
@@ -345,8 +351,17 @@ async function draftDecomposition(ctx) {
   await commentOnIssue(token, owner, repo, number, critique.markdown)
     .catch(err => console.warn(`Falha ao comentar a crítica: ${err.message}`));
 
-  if (critique.grave) {
-    console.log('Crítica adversarial apontou findings GRAVES — nenhum item foi criado.');
+  // Graves SEM decisão do TL. É este o portão que travava a #18: com spec e
+  // plan em contradição, nenhum rascunho passava — agora o TL pode afirmar que
+  // um documento está certo, ou aceitar o risco, item a item.
+  const { blocking, accepted } = applyCritiqueDecisions(critique.findings, decisions, 'stories');
+  if (accepted.length > 0) {
+    await addLabel(token, owner, repo, number, LABEL_RISK_ACCEPTED).catch(() => {});
+    await commentOnIssue(token, owner, repo, number,
+      renderRiskAcceptedComment({ kind: 'stories', accepted })).catch(() => {});
+  }
+  if (blocking.length > 0) {
+    console.log(`Crítica adversarial apontou ${blocking.length} finding(s) GRAVE(s) sem decisão — nenhum item foi criado.`);
     await addLabel(token, owner, repo, number, LABEL_CRITIQUE_FAILED);
     await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_READY).catch(() => {});
     await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE);

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

@@ -7,11 +7,14 @@ import {
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
   allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE,
-  LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+  LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_RISK_ACCEPTED,
+  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,
+  parseCritiqueDecisions, applyCritiqueDecisions, renderRiskAcceptedComment,
 } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
@@ -65,6 +68,9 @@ async function critiquePlan({
     return [];
   });
   const { attempt, blocked } = resolveCritiqueAttempt({ comments, labels, kind: 'plan', maxAttempts });
+  // Decisões que o Tech Leader já tomou sobre findings anteriores. Entram no
+  // prompt (para a crítica reconsiderar) e no portão (grave decidido não bloqueia).
+  const decisions = parseCritiqueDecisions(comments, 'plan');
 
   if (blocked) {
     console.log(`Teto de ${maxAttempts} tentativas de crítica atingido — exigindo revisão humana.`);
@@ -81,6 +87,7 @@ async function critiquePlan({
   try {
     critique = await runCritique({
       kind: 'plan', spec, plan, techContextYaml, attempt, maxAttempts, model, labels, usage,
+      decisions,
     });
   } catch (err) {
     console.warn(`Crítica adversarial não concluiu: ${err.message}`);
@@ -97,9 +104,19 @@ async function critiquePlan({
   await commentOnIssue(token, owner, repo, issueNumber, critique.markdown)
     .catch(err => console.warn(`Falha ao comentar a crítica: ${err.message}`));
 
-  if (critique.grave) {
+  // O portão olha os graves SEM decisão do TL. Um grave que ele marcou como
+  // `ignorar` (risco aceito) ou `plano-correto` não trava o fluxo — foi decisão
+  // humana explícita, registrada e auditável na issue.
+  const { blocking, accepted } = applyCritiqueDecisions(critique.findings, decisions, 'plan');
+  if (accepted.length > 0) {
+    await addLabel(token, owner, repo, issueNumber, LABEL_RISK_ACCEPTED).catch(() => {});
+    await commentOnIssue(token, owner, repo, issueNumber,
+      renderRiskAcceptedComment({ kind: 'plan', accepted })).catch(() => {});
+    console.log(`${accepted.length} finding(s) aceito(s) como risco pelo Tech Leader.`);
+  }
+  if (blocking.length > 0) {
     await addLabel(token, owner, repo, issueNumber, LABEL_CRITIQUE_FAILED);
-    console.log(`Crítica adversarial apontou findings GRAVES — label ${LABEL_CRITIQUE_FAILED} aplicada.`);
+    console.log(`Crítica adversarial apontou ${blocking.length} finding(s) GRAVE(s) sem decisão — label ${LABEL_CRITIQUE_FAILED} aplicada.`);
     return;
   }
   // Crítica limpa remove o bloqueio anterior — é isso que zera o contador de
@@ -165,7 +182,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 +190,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

@@ -227,6 +227,75 @@ function buildContext({
   return lines.join('\n');
 }
 
+/**
+ * Etapa de cada item no board, por número. Best-effort: qualquer falha vira
+ * `null` para aquele item (tratado como "não implementado" por quem consome).
+ *
+ * A leitura passa por `addProjectItem`, que é MUTAÇÃO — adiciona o item ao
+ * Project se ainda não estiver lá. Por isso a consulta inteira é pulada em
+ * dry-run: um dry-run não pode ter efeito remoto.
+ *
+ * @param {string} token
+ * @param {Array<{number:number, nodeId:string}>} items
+ * @param {{dryRun?:boolean, warnOnSkip?:boolean}} [opts]
+ * @returns {Promise<Map<number, string|null>>}
+ */
+async function fetchStagesOf(token, items, { dryRun = false, warnOnSkip = false } = {}) {
+  const stageOf = new Map();
+  if (items.length === 0) return stageOf;
+  const { project, error: projectError } = loadProjectConfig();
+  if (dryRun) {
+    if (warnOnSkip) {
+      p.log.warn(
+        'Dry-run: Etapas do board não consultadas (a consulta adicionaria itens ao Project); ' +
+        'nenhuma Story será considerada implementada.'
+      );
+    }
+    return stageOf;
+  }
+  if (projectError) {
+    if (warnOnSkip) {
+      p.log.warn(`${projectError} — Etapas do board não consultadas; nenhuma Story será considerada implementada.`);
+    }
+    return stageOf;
+  }
+  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+  if (!etapaField?.id) return stageOf;
+  await Promise.all(items.map(async (s) => {
+    try {
+      const itemId = await addProjectItem(token, project.id, s.nodeId);
+      stageOf.set(s.number, await getItemSingleSelectValue(token, itemId, etapaField.id));
+    } catch {
+      stageOf.set(s.number, null);
+    }
+  }));
+  return stageOf;
+}
+
+/**
+ * A Feature pode avançar para Code Review? Só quando TODAS as Stories irmãs já
+ * estão em Code Review ou além. Pura — recebe as etapas já consultadas.
+ *
+ * Etapa desconhecida (`null`/ausente) conta como PENDENTE: na dúvida a Feature
+ * não avança. Um falso avanço mente sobre o estado do trabalho; um falso
+ * "não avança" só adia, e a etapa nunca retrocede depois.
+ *
+ * @param {Array<{number:number}>} siblings Stories irmãs (sem a atual)
+ * @param {Map<number, string|null>} stageOf
+ * @param {{reviewStage?:string, stageOrder?:string[]}} [opts]
+ */
+export function featureCanAdvance(siblings, stageOf, {
+  reviewStage = STAGE_CODE_REVIEW, stageOrder = STAGE_ORDER,
+} = {}) {
+  const reviewIdx = stageOrder.indexOf(reviewStage);
+  if (reviewIdx < 0) return false;
+  return siblings.every((s) => {
+    const stage = stageOf.get(s.number) ?? null;
+    const idx = stage ? stageOrder.indexOf(stage) : -1;
+    return idx >= reviewIdx;
+  });
+}
+
 /**
  * Planeja a implementação de uma Feature: separa as Stories já implementadas
  * (Etapa >= reviewStage na ordem canônica) das pendentes e ordena as pendentes
@@ -496,31 +565,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   }));
 
   // F3. Etapa de cada Story no board (best-effort — sem board, nada é pulado).
-  const { project, error: projectError } = loadProjectConfig();
-  const stageOf = new Map();
-  if (dryRun) {
-    // A leitura da Etapa passa por addProjectItem, que é MUTAÇÃO (adiciona a
-    // Story ao Project se ainda não estiver lá). Num dry-run isso é proibido, então
-    // a consulta é pulada inteira — o planejamento segue com stage null.
-    p.log.warn(
-      'Dry-run: Etapas do board não consultadas (a consulta adicionaria itens ao Project); ' +
-      'nenhuma Story será considerada implementada.'
-    );
-  } else if (projectError) {
-    p.log.warn(`${projectError} — Etapas do board não consultadas; nenhuma Story será considerada implementada.`);
-  } else {
-    const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
-    if (etapaField?.id) {
-      await Promise.all(enriched.map(async (s) => {
-        try {
-          const itemId = await addProjectItem(token, project.id, s.nodeId);
-          stageOf.set(s.number, await getItemSingleSelectValue(token, itemId, etapaField.id));
-        } catch {
-          stageOf.set(s.number, null);
-        }
-      }));
-    }
-  }
+  const stageOf = await fetchStagesOf(token, enriched, { dryRun, warnOnSkip: true });
 
   // F4. Planejamento: pendentes em ordem topológica, puladas, ciclos.
   const { pending, skipped, cycle } = planFeatureImplementation(
@@ -542,6 +587,14 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
     );
   }
   if (pending.length === 0) {
+    // "Nada a fazer" para o spec-kit, mas há o que fazer no board: se TODAS as
+    // Stories estão em Code Review+, é exatamente a condição de avanço da
+    // Feature. Sem isso, uma Feature que ficou para trás (executor que concluiu
+    // sem mover o card, run interrompido) não tinha como ser destravada —
+    // reexecutar o implement caía aqui e retornava.
+    await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
+      feature: { nodeId: feature.node_id, number: feature.number },
+    }) });
     p.outro(`Todas as ${stories.length} story(ies) da Feature #${feature.number} já estão implementadas — nada a fazer.`);
     return;
   }
@@ -660,13 +713,26 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
       `  Próximo: acompanhe os PRs de cada Story; a Feature avança para ${STAGE_CODE_REVIEW} após a última.`,
     onSuccess: async () => {
       // Execução única para todas as pendentes: no sucesso, Tasks → Done e
-      // Stories → Code Review (a Feature fica com a Action de PR/code-review).
+      // Stories → Code Review.
       for (const s of pending) {
         await applyBoardMoves({ token, moves: planBoardMoves('success', {
           story: { nodeId: s.nodeId, number: s.number },
           tasks: s.tasks || [],
         }) });
       }
+      // E a Feature em seguida: neste ponto TODAS as suas Stories estão em
+      // Code Review ou além — as `pending` acabaram de ir, as `skipped` já
+      // estavam lá (é esse o critério que as pulou). Não é preciso reconsultar
+      // o board para saber disso.
+      //
+      // Antes isso era prosa no contexto ("avance a Feature somente se TODAS
+      // já estiverem em Code Review") e ficava por conta do LLM, com a Action
+      // do PR como plano B. Sob o dev-agent, que trabalha num branch único e
+      // não abre PR, nenhum dos dois acontecia: as 6 Stories da feature #18
+      // foram para Code Review e a Feature ficou em Desenvolvimento.
+      await applyBoardMoves({ token, moves: planBoardMoves('success', {
+        feature: { nodeId: feature.node_id, number: feature.number },
+      }) });
     },
   });
 }
@@ -803,7 +869,8 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     const featureSubs = await listSubIssues(token, feature.nodeId).catch(() => []);
     siblingStories = featureSubs
       .filter(s => detectIssueType({ title: s.title }) === 'Story' && s.number !== issue.number)
-      .map(s => ({ number: s.number, title: s.title }));
+      // nodeId serve à consulta de Etapa no fim da Story (avanço da Feature).
+      .map(s => ({ number: s.number, title: s.title, nodeId: s.nodeId }));
   }
 
   // 4c. Comentários das issues (best-effort) — revisões e correções vivem nos
@@ -872,10 +939,33 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     outroSuccess:
       `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
       '  Próximo: revise as mudanças e abra o PR — o board já foi atualizado.',
-    onSuccess: () => applyBoardMoves({ token, moves: planBoardMoves('success', {
-      story: type === 'Story' ? { nodeId: issue.node_id, number: issue.number } : null,
-      tasks: tasks.map(t => ({ nodeId: t.nodeId, number: t.number })),
-    }) }),
+    onSuccess: async () => {
+      await applyBoardMoves({ token, moves: planBoardMoves('success', {
+        story: type === 'Story' ? { nodeId: issue.node_id, number: issue.number } : null,
+        tasks: tasks.map(t => ({ nodeId: t.nodeId, number: t.number })),
+      }) });
+      // Última Story da Feature? Então a Feature avança junto.
+      //
+      // Este é o caminho que o dev-agent realmente percorre: o feature_prompt
+      // manda `npx spec-wave implement <story>` uma por vez, então o modo
+      // Feature (que avança a Feature no seu próprio onSuccess) nunca roda sob
+      // o agente. Sem isto, a Feature dependia só da Action do PR — e quando o
+      // PR não nascia, ficava presa em Desenvolvimento com todas as Stories em
+      // Code Review.
+      //
+      // A consulta é por irmã e só acontece aqui, ao fim de uma Story: no pior
+      // caso é uma leitura por Story da Feature ao longo de toda a execução.
+      if (type !== 'Story' || !feature?.nodeId) return;
+      // Sem irmãs, esta era a única Story: a Feature avança direto (nada a
+      // consultar). Com irmãs, todas precisam já estar em Code Review+.
+      if (siblingStories.length > 0) {
+        const stageOf = await fetchStagesOf(token, siblingStories, { dryRun });
+        if (!featureCanAdvance(siblingStories, stageOf)) return;
+      }
+      await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
+        feature: { nodeId: feature.nodeId, number: feature.number },
+      }) });
+    },
   });
 }
 

package/src/config.mjs

@@ -334,6 +334,10 @@ export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
 export const LABEL_DECOMPOSE_READY = 'spec-wave:decompose-ready';
 export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
+// Achado GRAVE que o Tech Leader aceitou como risco conhecido. Fica na issue
+// depois que a crítica passa: sem ela, o risco aceito some da vista assim que a
+// rodada seguinte roda limpa, e ninguém mais sabe que houve uma decisão.
+export const LABEL_RISK_ACCEPTED = 'spec-wave:risk-accepted';
 
 export const TRIGGER_LABELS = [
   { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
@@ -357,6 +361,7 @@ export const TRIGGER_LABELS = [
   { name: LABEL_DECOMPOSE_READY,     color: '0E8A16', description: 'Rascunho de decomposição pronto para revisão humana' },
   { name: LABEL_CRITIQUE_FAILED,     color: 'B60205', description: 'Crítica adversarial apontou contradições graves' },
   { name: LABEL_NEEDS_HUMAN,         color: 'B60205', description: 'Crítica reprovou N vezes seguidas — precisa de revisão humana' },
+  { name: LABEL_RISK_ACCEPTED,       color: 'D93F0B', description: 'Tech Leader aceitou finding(s) grave(s) como risco conhecido' },
   { name: LABEL_DECOMPOSED,          color: 'EDEDED', description: 'Feature já decomposta em Stories e Tasks' },
 ];
 

package/src/lib/critique.mjs

@@ -265,6 +265,251 @@ export function critiqueMarker({ kind, attempt, verdict }) {
   return `<!-- spec-wave:critique kind=${kind} attempt=${attempt} verdict=${verdict} -->`;
 }
 
+// ---------------------------------------------------------------------------
+// Decisões do Tech Leader sobre os findings
+// ---------------------------------------------------------------------------
+//
+// A crítica reprova; quem decide o que fazer é o TL. Sem isso, o único caminho
+// era corrigir o documento — e quando spec e plan se contradizem, corrigir o
+// artefato criticado não alcança a causa: a crítica reprova de novo, com o
+// achado oposto, indefinidamente.
+//
+// Três desfechos por finding, além do default (corrigir e rodar de novo):
+//   • `plano-correto` — o TL afirma que o documento está certo. O achado NÃO é
+//     suprimido: vai para a próxima crítica como contexto, para ela levar a
+//     afirmação em conta em vez de repetir o mesmo raciocínio.
+//   • `ignorar` — o achado é conhecido e aceito. Sai da conta que bloqueia.
+//   • (sem decisão) — comportamento de hoje: bloqueia se for grave.
+//
+// A decisão é por ITEM: uma crítica com três achados pode ter um ignorado e
+// dois a corrigir. E pode carregar uma instrução livre para a próxima rodada.
+//
+// Persistência: comentário na issue com marcador, como a própria crítica. É o
+// que mantém CLI, Actions e UI enxergando o mesmo estado — o GitHub segue sendo
+// a fonte de verdade, e o histórico da decisão fica auditável.
+
+export const CRITIQUE_DISPOSITIONS = ['plano-correto', 'ignorar'];
+const DISPOSITION_SET = new Set(CRITIQUE_DISPOSITIONS);
+
+export const DECISIONS_MARKER_RE =
+  /<!--\s*spec-wave:critique-decisions\s+kind=(?<kind>[a-z]+)\s*-->/g;
+
+/**
+ * Impressão digital de um finding (função PURA).
+ *
+ * A decisão precisa sobreviver à rodada seguinte, e a única coisa estável entre
+ * rodadas é o CONTEÚDO do achado — não há id vindo do modelo. Ancorar no sha do
+ * documento não serve: no caso típico (corrigir dois achados, ignorar um) o
+ * documento muda por causa das correções e a decisão sobre o terceiro expiraria
+ * junto, que é exatamente o que se quer evitar.
+ *
+ * Normaliza espaços, caixa e acentos para tolerar reformulação cosmética do
+ * modelo. Reformulação material muda a digital — e aí é outro achado, que volta
+ * a ser levantado de propósito.
+ */
+export function findingFingerprint({ kind = 'plan', anchor = null, text = '' } = {}) {
+  const norm = (s) => String(s || '')
+    .normalize('NFD').replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+  const base = `${norm(kind)}|${norm(anchor)}|${norm(text)}`;
+  // FNV-1a de 32 bits: curto o bastante para caber no comentário e determinístico
+  // entre execuções (o hash do Node varia por processo).
+  let h = 0x811c9dc5;
+  for (let i = 0; i < base.length; i += 1) {
+    h ^= base.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/** Monta o marcador do comentário de decisões (função PURA). */
+export function decisionsMarker({ kind }) {
+  return `<!-- spec-wave:critique-decisions kind=${kind} -->`;
+}
+
+/**
+ * Comentário de decisões do TL (função PURA).
+ *
+ * O corpo é legível por humano E parseável: o bloco JSON cercado é o que a
+ * próxima rodada lê. Escrever em prosa e reparsear com regex seria frágil — o
+ * texto do TL é livre e pode conter qualquer coisa.
+ */
+export function renderDecisionsComment({
+  kind = 'plan', decisions = [], guidance = null, author = null,
+} = {}) {
+  const porTipo = {
+    'plano-correto': decisions.filter(d => d.disposition === 'plano-correto'),
+    ignorar: decisions.filter(d => d.disposition === 'ignorar'),
+  };
+  const linhas = [
+    decisionsMarker({ kind }),
+    '',
+    `🧭 **Decisões do Tech Leader sobre a crítica**${author ? ` — por @${author}` : ''}`,
+    '',
+  ];
+  if (porTipo['plano-correto'].length > 0) {
+    linhas.push('### ✅ Documento está correto');
+    linhas.push('');
+    linhas.push('> A próxima crítica recebe estas afirmações como contexto.');
+    linhas.push('');
+    for (const d of porTipo['plano-correto']) {
+      linhas.push(`- ${d.anchor ? `**${d.anchor}** — ` : ''}${d.summary || d.fingerprint}`);
+      if (d.note) linhas.push(`  - Justificativa: ${d.note}`);
+    }
+    linhas.push('');
+  }
+  if (porTipo.ignorar.length > 0) {
+    linhas.push('### ⚠️ Aceitos como risco');
+    linhas.push('');
+    for (const d of porTipo.ignorar) {
+      linhas.push(`- ${d.anchor ? `**${d.anchor}** — ` : ''}${d.summary || d.fingerprint}`);
+      if (d.note) linhas.push(`  - Justificativa: ${d.note}`);
+    }
+    linhas.push('');
+  }
+  if (guidance) {
+    linhas.push('### 🧭 Instrução para a próxima crítica');
+    linhas.push('');
+    linhas.push(guidance);
+    linhas.push('');
+  }
+  linhas.push('```json spec-wave:decisions');
+  linhas.push(JSON.stringify({ kind, guidance: guidance || null, decisions }, null, 2));
+  linhas.push('```');
+  return linhas.join('\n');
+}
+
+const DECISIONS_JSON_RE = /```json spec-wave:decisions\s*\n([\s\S]*?)\n```/;
+
+/**
+ * Decisões vigentes da issue (função PURA).
+ *
+ * Comentários em ordem cronológica; o mais recente de cada `kind` vence — o TL
+ * pode revisar o que decidiu, e a última palavra é a que vale. Payload
+ * inválido é IGNORADO em silêncio: uma decisão ilegível não pode virar
+ * "ignorar tudo" por acidente.
+ *
+ * @returns {{ byFingerprint: Map<string,object>, guidance: string|null }}
+ */
+export function parseCritiqueDecisions(comments = [], kind = 'plan') {
+  let vigente = null;
+  for (const comment of comments) {
+    const body = String(comment?.body || '');
+    DECISIONS_MARKER_RE.lastIndex = 0;
+    const m = DECISIONS_MARKER_RE.exec(body);
+    if (!m || m.groups.kind !== kind) continue;
+    const bloco = body.match(DECISIONS_JSON_RE);
+    if (!bloco) continue;
+    try {
+      const payload = JSON.parse(bloco[1]);
+      if (!Array.isArray(payload?.decisions)) continue;
+      vigente = payload;
+    } catch { /* payload ilegível não vira decisão */ }
+  }
+  const byFingerprint = new Map();
+  for (const d of vigente?.decisions || []) {
+    if (!d?.fingerprint || !DISPOSITION_SET.has(d.disposition)) continue;
+    byFingerprint.set(String(d.fingerprint), d);
+  }
+  return { byFingerprint, guidance: vigente?.guidance || null };
+}
+
+/**
+ * Cruza os findings recém-produzidos com as decisões vigentes (função PURA).
+ *
+ * `blocking` é o que decide se a label de reprova entra: um grave decidido sai
+ * da conta. `accepted` alimenta o comentário de aceite de risco — sem esse
+ * registro, o risco aceito desaparece assim que a crítica seguinte roda limpa.
+ *
+ * @returns {{ findings: Array, blocking: Array, accepted: Array, asserted: Array }}
+ */
+export function applyCritiqueDecisions(findings = [], { byFingerprint = new Map() } = {}, kind = 'plan') {
+  const anotados = findings.map((f) => {
+    const fingerprint = findingFingerprint({ kind, anchor: f.anchor, text: f.text });
+    const decision = byFingerprint.get(fingerprint) || null;
+    return { ...f, fingerprint, decision: decision ? decision.disposition : null, decisionNote: decision?.note || null };
+  });
+  return {
+    findings: anotados,
+    // Grave sem decisão = bloqueia, como sempre foi.
+    blocking: anotados.filter(f => f.severity === 'grave' && f.decision === null),
+    accepted: anotados.filter(f => f.decision === 'ignorar'),
+    asserted: anotados.filter(f => f.decision === 'plano-correto'),
+  };
+}
+
+/**
+ * Comentário de aceite de risco (função PURA).
+ *
+ * Um grave aceito pelo TL deixa de bloquear — e é justamente por isso que
+ * precisa de registro permanente. Sem este comentário, o risco desaparece da
+ * vista assim que a crítica seguinte roda limpa, e ninguém mais sabe que houve
+ * uma decisão nem qual foi a justificativa.
+ */
+export function renderRiskAcceptedComment({ kind = 'plan', accepted = [] } = {}) {
+  const linhas = [
+    `<!-- spec-wave:risk-accepted kind=${kind} -->`,
+    '',
+    '⚠️ **Findings graves aceitos como risco pelo Tech Leader**',
+    '',
+    'Estes achados **não** bloquearam o avanço — a decisão foi humana e explícita:',
+    '',
+  ];
+  for (const f of accepted) {
+    linhas.push(`- ${f.anchor ? `**${f.anchor}** — ` : ''}${f.text || f.summary || ''}`);
+    if (f.decisionNote || f.note) linhas.push(`  - Justificativa: ${f.decisionNote || f.note}`);
+  }
+  linhas.push('');
+  linhas.push(`A label \`spec-wave:risk-accepted\` fica na issue como marca dessa decisão.`);
+  return linhas.join('\n');
+}
+
+/**
+ * Bloco que entra no prompt da próxima crítica (função PURA).
+ *
+ * As afirmações do TL entram como CONTEXTO, não como ordem de silenciar: o
+ * objetivo é que a crítica reconsidere com a informação nova, e diga se
+ * discorda. Silenciar por decreto transformaria o portão em teatro.
+ */
+export function renderDecisionsForPrompt({ decisions = [], guidance = null } = {}) {
+  // Aceita tanto os REGISTROS persistidos (que guardam `summary`) quanto os
+  // findings anotados (que guardam `text`) — os dois chamadores existem.
+  const texto = (d) => d.text || d.summary || '';
+  const asserted = decisions.filter(d => d.disposition === 'plano-correto' || d.decision === 'plano-correto');
+  const accepted = decisions.filter(d => d.disposition === 'ignorar' || d.decision === 'ignorar');
+  if (asserted.length === 0 && accepted.length === 0 && !guidance) return '';
+  const linhas = ['## Decisões do Tech Leader sobre a crítica anterior', ''];
+  if (asserted.length > 0) {
+    linhas.push(
+      'O Tech Leader AFIRMA que os pontos abaixo estão corretos no documento. ' +
+      'Leve a afirmação em conta: se ela resolve o problema, NÃO repita o finding. ' +
+      'Se você ainda discorda, pode levantá-lo de novo — mas explique por que a ' +
+      'afirmação do Tech Leader não procede.',
+      ''
+    );
+    for (const f of asserted) {
+      linhas.push(`- ${f.anchor ? `**${f.anchor}** — ` : ''}${texto(f)}`);
+      const nota = f.note || f.decisionNote;
+      if (nota) linhas.push(`  - Tech Leader: ${nota}`);
+    }
+    linhas.push('');
+  }
+  if (accepted.length > 0) {
+    linhas.push(
+      'Os pontos abaixo foram ACEITOS COMO RISCO conhecido. Não os levante de novo.',
+      ''
+    );
+    for (const f of accepted) {
+      linhas.push(`- ${f.anchor ? `**${f.anchor}** — ` : ''}${texto(f)}`);
+    }
+    linhas.push('');
+  }
+  if (guidance) {
+    linhas.push('### Instrução do Tech Leader para esta rodada', '', guidance, '');
+  }
+  return linhas.join('\n');
+}
+
 /**
  * Quantas reprovas consecutivas desta crítica já existem na issue (função PURA).
  *
@@ -288,6 +533,7 @@ export function resolveCritiqueAttempt({
 } = {}) {
   const names = labelNames(labels);
   if (names.includes(LABEL_NEEDS_HUMAN)) return { attempt: 0, previous: 0, blocked: true };
+
   if (!names.includes(LABEL_CRITIQUE_FAILED)) return { attempt: 1, previous: 0, blocked: false };
 
   let previous = 0;
@@ -398,6 +644,23 @@ export function renderCritiqueMarkdown({
   if (graves.length > 0) parts.push(`### ❌ Graves\n\n${bullets(graves)}`);
   if (menores.length > 0) parts.push(`### ⚠️ Menores\n\n${bullets(menores)}`);
   parts.push((KIND_TRAILER[kind] || KIND_TRAILER.plan)(graves.length > 0));
+  // Findings estruturados, com a MESMA digital que o portão usa. É o que
+  // permite decidir item a item numa UI: parsear os bullets de volta seria
+  // frágil, e uma digital recalculada de forma diferente não casaria com a
+  // decisão gravada. Quem escreve a digital é quem a compara.
+  parts.push([
+    '```json spec-wave:findings',
+    JSON.stringify({
+      kind,
+      findings: findings.map(f => ({
+        fingerprint: findingFingerprint({ kind, anchor: f.anchor, text: f.text }),
+        severity: f.severity,
+        anchor: f.anchor || null,
+        text: sanitizeFindingText(f.text),
+      })),
+    }, null, 2),
+    '```',
+  ].join('\n'));
   return parts.join('\n\n');
 }
 
@@ -430,7 +693,7 @@ export function renderCritiqueMarkdown({
 export async function runCritique({
   kind, spec, plan, techContextYaml, decomposition, bugDoc, bugReport,
   attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
-  model, labels = [], usage, cwd,
+  model, labels = [], usage, cwd, decisions = null,
 } = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
@@ -447,6 +710,15 @@ export async function runCritique({
   // tem que explicar OS SINTOMAS RELATADOS, não sintomas plausíveis quaisquer.
   if (bugReport) sections.push(`## Relato original (issue e comentários)\n\n${bugReport}`);
   if (bugDoc) sections.push(`## bug.md\n\n${bugDoc}`);
+  // Decisões do TL sobre a rodada anterior entram por ÚLTIMO: são o contexto
+  // mais recente, e a crítica precisa lê-las depois de já ter visto os documentos.
+  const decisoesBloco = decisions
+    ? renderDecisionsForPrompt({
+        decisions: [...(decisions.byFingerprint?.values() || [])],
+        guidance: decisions.guidance,
+      })
+    : '';
+  if (decisoesBloco) sections.push(decisoesBloco);
   const userContent = sections.join('\n\n') || '(nenhum documento fornecido)';
 
   const report = await generateStructured(buildSystemPrompt(kind, cwd), userContent, {

package/src/lib/implement-board.mjs

@@ -70,6 +70,16 @@ export function planBoardMoves(phase, {
       moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`,
                    stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
     }
+    // Feature: só o modo Feature passa `feature` aqui, e só depois de TODAS as
+    // suas Stories terem ido para Code Review — quem decide é o chamador, que
+    // conhece as pendentes e as puladas. Antes, o avanço da Feature dependia da
+    // Action disparada pelo PR; quando o PR não nascia (o dev-agent trabalha
+    // num branch único e não abre PR), a Feature ficava presa em
+    // Desenvolvimento com todas as Stories já em Code Review.
+    if (feature?.nodeId) {
+      moves.push({ nodeId: feature.nodeId, label: `Feature #${feature.number}`,
+                   stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
+    }
   }
   return moves;
 }

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.17.0",
   "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",