@spec-wave/cli 0.13.0 → 0.14.0

package/src/commands/decompose.mjs

@@ -1,16 +1,46 @@
-import { existsSync, readFileSync } from 'node:fs';
+// Decomposição de Feature → Stories(+Tasks) e RFC → Tasks, em DUAS etapas.
+//
+// Antes era atômico: gerava o JSON, submetia à crítica, e se a crítica reprovasse
+// descartava o rascunho inteiro. Os achados citavam "Story 5, task 1" de um
+// artefato que não existia em lugar nenhum — nem na issue, nem no repo, nem nos
+// logs. E como cada tentativa regenerava do zero, cada execução produzia uma
+// lista diferente de achados: cinco tentativas, cinco listas.
+//
+// Agora:
+//   label spec-wave:decompose        → grava/re-critica docs/**/decomposition.md
+//   label spec-wave:decompose-apply  → cria as issues a partir do rascunho revisado
+//
+// A crítica passa a apontar para um arquivo ESTÁVEL, versionado, com âncoras
+// ("Story 3", "Task 3.2"), e o humano corrige o artefato em vez de tentar
+// influenciar indiretamente pelo plan.md. Um rascunho existente NUNCA é
+// regenerado: re-aplicar :decompose critica o arquivo como está, preservando as
+// edições humanas. Para regerar do zero, apague o arquivo.
+
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
-import { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy } from '../api/github-rest.mjs';
+import {
+  getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
+} from '../api/github-rest.mjs';
 import { addSubIssue, listSubIssues } from '../api/github-graphql.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
 import { generateDocument } from '../lib/claude.mjs';
-import { runCritique } from '../lib/critique.mjs';
+import { runCritique, resolveCritiqueAttempt, renderNeedsHumanComment } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 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, TARGET_LANGUAGE, STAGE_READY, PROGRESS_TODO } from '../config.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import {
+  renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
+} 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,
+  STAGE_READY, PROGRESS_TODO, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+} 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).
@@ -19,6 +49,20 @@ async function moveToReady(token, project, etapaField, statusField, nodeId) {
   await advanceToStage(token, project, etapaField, statusField, nodeId, STAGE_READY, PROGRESS_TODO);
 }
 
+/**
+ * Parada por decisão do fluxo (crítica grave, crítica indisponível, teto de
+ * tentativas): o comentário já foi postado, o catch externo não deve duplicá-lo,
+ * mas o erro PRECISA propagar. Antes esses caminhos faziam `return`, e a Action
+ * terminava verde tendo criado zero Stories — só se descobria olhando as labels.
+ */
+class DecomposeBlockedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DecomposeBlockedError';
+    this.blocked = true;
+  }
+}
+
 // Dobra as barras invertidas que NÃO iniciam um escape válido de JSON. O corpo
 // das tasks costuma trazer trecho de shell/YAML/regex ("\d+", "gradlew \" no fim
 // da linha) e o modelo emite a barra crua: `JSON.parse` morre com "Bad escaped
@@ -79,6 +123,22 @@ export function parseModelJson(raw) {
 // Prefixo de título das sub-issues geradas por cada tipo decompoível.
 const CHILD_PREFIX = { Feature: '[STORY]', RFC: '[TASK]' };
 
+/**
+ * Modo do run (função PURA — testável).
+ *
+ * A flag `--apply` vem do workflow, onde a label que disparou é a fonte de
+ * verdade. O fallback por label cobre a execução manual e o retry de runner.
+ *
+ * @param {object} params
+ * @param {Array<string|{name:string}>} [params.labels] labels da issue
+ * @param {boolean} [params.apply] flag --apply
+ * @returns {'draft'|'apply'}
+ */
+export function resolveDecomposeMode({ labels = [], apply = false } = {}) {
+  if (apply) return 'apply';
+  return labelNames(labels).includes(LABEL_DECOMPOSE_APPLY) ? 'apply' : 'draft';
+}
+
 /**
  * Guard de idempotência do decompose (função PURA — testável).
  *
@@ -86,6 +146,9 @@ 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.
  *
+ * `spec-wave:decompose-ready` de propósito NÃO entra aqui: é estado de rascunho
+ * pendente, não de decomposição feita — re-aplicar `:decompose` deve re-criticar.
+ *
  * @param {object} params
  * @param {Array<string|{name: string}>} [params.labels] labels da issue
  * @param {Array<{ number?: number, title?: string }>} [params.subIssues] sub-issues existentes
@@ -93,9 +156,7 @@ const CHILD_PREFIX = { Feature: '[STORY]', RFC: '[TASK]' };
  * @returns {{ skip: boolean, reason: string }}
  */
 export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {}) {
-  const names = labels
-    .map(l => (typeof l === 'string' ? l : l?.name))
-    .filter(Boolean);
+  const names = labelNames(labels);
   if (names.includes(LABEL_DECOMPOSED)) {
     return { skip: true, reason: `a issue já tem a label \`${LABEL_DECOMPOSED}\`` };
   }
@@ -112,6 +173,14 @@ export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {})
   return { skip: false, reason: '' };
 }
 
+// Diretório do documento por tipo. Feature usa o mesmo docs/features/<slug> da
+// spec/plan; RFC ganha o seu, já que não passa por spec/plan.
+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) };
+}
+
 // Lint de idioma sobre títulos+corpos gerados; retorna aviso pronto para
 // anexar ao comentário final ('' se limpo).
 function formatItemsLintWarning(texts) {
@@ -124,6 +193,20 @@ function formatItemsLintWarning(texts) {
   return `\n\n⚠️ possíveis artefatos de idioma nos itens gerados: ${excerpts}`;
 }
 
+// Grava e commita o rascunho — mesmo padrão do generate-plan (o workflow roda
+// com contents: write e checkout com token).
+function commitFile(filePath, content, message) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content, 'utf-8');
+  const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
+  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 "${message}"`);
+  git('git pull --rebase');
+  git('git push');
+}
+
 const FEATURE_SYSTEM_PROMPT = `Você é um Tech Lead experiente em decomposição de trabalho ágil.
 A partir da Feature fornecida (com spec.md e plan.md), gere uma lista de Stories e Tasks.
 
@@ -172,65 +255,239 @@ Regras:
 - "body" detalhado e acionável.
 - Gere entre 3 e 10 Tasks concretas que, juntas, cubram o RFC.`;
 
-// Decompõe uma Feature em Stories (+ Tasks), cada uma vinculada como sub-issue.
-async function decomposeFeature(ctx) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage } = ctx;
-  const slug = slugify(issue.title);
-  const featureDir = `docs/features/${slug}`;
-
-  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}`);
-  const userContent = [
-    `Feature: ${issue.title}`,
-    `Issue #${issueNumber}`,
-    `\n## spec.md\n${specContent}`,
-    `\n## plan.md\n${planContent}`,
-  ].join('\n');
-
-  const decomposition = parseModelJson(await generateDocument(FEATURE_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
-
-  // Crítica adversarial ANTES de criar qualquer issue: stories que contradizem
-  // a spec/plan não devem virar trabalho. Crítica indisponível → só avisa.
-  let critique = null;
+// ---------------------------------------------------------------------------
+// Etapa 1: rascunho (label spec-wave:decompose)
+// ---------------------------------------------------------------------------
+
+async function draftDecomposition(ctx) {
+  const { token, owner, repo, issue, issueNumber, type, labels, usage, docDir, docPath, docRel } = ctx;
+  const number = parseInt(issueNumber, 10);
+  const kind = DECOMPOSE_TARGETS[type]; // Feature → 'stories'; RFC → 'tasks'
+  const blobUrl = `https://github.com/${owner}/${repo}/blob/main/${docRel}`;
+
+  const specPath = path.join(docDir, 'spec.md');
+  const planPath = path.join(docDir, 'plan.md');
+  const specContent = existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null;
+  const planContent = existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null;
+
+  // Rascunho existente é preservado COMO ESTÁ: o humano corrige o arquivo e
+  // re-aplica a label para uma nova crítica. Regenerar aqui apagaria a correção
+  // — é justamente o que fazia o ciclo não convergir.
+  let markdown;
+  if (existsSync(docPath)) {
+    console.log(`Rascunho encontrado em ${docRel} — criticando o arquivo como está (sem regerar).`);
+    markdown = readFileSync(docPath, 'utf-8');
+  } else {
+    console.log(`Gerando rascunho de decomposição para ${type}: ${issue.title}`);
+    const userContent = type === 'RFC'
+      ? [
+          `RFC: ${issue.title}`,
+          `Issue #${issueNumber}`,
+          `\n## Descrição\n${issue.body || '(sem descrição)'}`,
+        ].join('\n')
+      : [
+          `Feature: ${issue.title}`,
+          `Issue #${issueNumber}`,
+          `\n## spec.md\n${specContent || '(spec.md não encontrado)'}`,
+          `\n## plan.md\n${planContent || '(plan.md não encontrado)'}`,
+        ].join('\n');
+
+    const generated = parseModelJson(await generateDocument(
+      type === 'RFC' ? RFC_SYSTEM_PROMPT : FEATURE_SYSTEM_PROMPT,
+      userContent,
+      { action: 'decompose', labels, usage }
+    ));
+
+    markdown = renderDecompositionDoc({
+      title: issue.title,
+      issueNumber: number,
+      kind,
+      stories: generated.stories || [],
+      tasks: generated.tasks || [],
+    });
+    commitFile(docPath, markdown, `docs: rascunho de decomposição de ${docRel} [spec-wave]`);
+    console.log(`Rascunho commitado em ${docRel}.`);
+  }
+
+  // Valida a estrutura ANTES de gastar tokens com a crítica: um arquivo quebrado
+  // por edição humana precisa de mensagem clara, não de uma crítica sobre nada.
+  let doc;
+  try {
+    doc = parseDecompositionDoc(markdown);
+  } catch (err) {
+    await commentOnIssue(token, owner, repo, number,
+      `❌ **Não consegui ler o rascunho da decomposição.**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `Corrija [\`${docRel}\`](${blobUrl}) e reaplique \`${LABEL_DECOMPOSE}\`. ` +
+      `Para começar de novo do zero, apague o arquivo.`
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE).catch(() => {});
+    throw new DecomposeBlockedError(err.message);
+  }
+  const itemCount = kind === 'stories'
+    ? `${doc.stories.length} stories`
+    : `${doc.tasks.length} tasks`;
+  console.log(`Rascunho válido: ${itemCount}.`);
+
+  // O RFC não tem spec/plan para auditar contra — a crítica não teria referência.
+  if (kind !== 'stories') {
+    await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: false });
+    return;
+  }
+
+  const { attempt, blocked } = resolveCritiqueAttempt({
+    comments: ctx.comments, labels, kind: 'stories', maxAttempts: ctx.maxCritiqueAttempts,
+  });
+  if (blocked) {
+    console.log(`Teto de ${ctx.maxCritiqueAttempts} tentativas de crítica atingido — exigindo revisão humana.`);
+    await commentOnIssue(token, owner, repo, number, renderNeedsHumanComment({
+      kind: 'stories',
+      attempt,
+      maxAttempts: ctx.maxCritiqueAttempts,
+      escalationModel: ctx.escalationModel,
+    })).catch(() => {});
+    await addLabel(token, owner, repo, number, LABEL_NEEDS_HUMAN);
+    await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE);
+    throw new DecomposeBlockedError(
+      `A crítica reprovou ${ctx.maxCritiqueAttempts - 1}x seguidas. Label ${LABEL_NEEDS_HUMAN} ` +
+      'aplicada: o fluxo exige revisão humana antes de continuar.'
+    );
+  }
+
+  // Da segunda tentativa em diante, escala para o modelo mais forte configurado.
+  const model = attempt > 1 ? (ctx.escalationModel || undefined) : undefined;
+  if (model) console.log(`Tentativa ${attempt}: escalando a crítica para ${model}.`);
+
+  let critique;
   try {
     critique = await runCritique({
       kind: 'stories',
-      spec: existsSync(`${featureDir}/spec.md`) ? specContent : null,
-      plan: existsSync(`${featureDir}/plan.md`) ? planContent : null,
-      stories: decomposition.stories,
+      spec: specContent,
+      plan: planContent,
+      decomposition: markdown,
+      attempt,
+      maxAttempts: ctx.maxCritiqueAttempts,
+      model,
+      labels,
       usage,
     });
   } catch (err) {
-    console.warn(`Crítica adversarial indisponível: ${err.message}`);
-    await commentOnIssue(
-      token, owner, repo, parseInt(issueNumber, 10),
-      `⚠️ crítica adversarial indisponível (erro: ${err.message}) — prosseguindo com a decomposição.`
+    // A crítica é o portão que impede stories contraditórias de virarem trabalho.
+    // Liberar o rascunho com o portão comprovadamente não executado é exatamente
+    // o que se quer evitar — então aborta, e a Action fica vermelha.
+    await commentOnIssue(token, owner, repo, number,
+      `❌ **A crítica adversarial não concluiu.**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `O rascunho está commitado em [\`${docRel}\`](${blobUrl}), mas **nada foi criado** — ` +
+      `sem crítica não há garantia de que as Stories respeitam a spec. ` +
+      `Reaplique \`${LABEL_DECOMPOSE}\` para tentar de novo.`
     ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE).catch(() => {});
+    throw new DecomposeBlockedError(`Crítica adversarial não concluiu: ${err.message}`);
   }
-  if (critique) {
-    await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10), 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 — nenhuma story foi criada.');
-      await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_CRITIQUE_FAILED);
-      await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:decompose');
-      return;
-    }
+
+  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.');
+    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);
+    throw new DecomposeBlockedError(
+      `A crítica adversarial apontou findings graves no rascunho (tentativa ${attempt}). ` +
+      `Nenhuma issue foi criada. Corrija ${docRel} e reaplique ${LABEL_DECOMPOSE}.`
+    );
+  }
+
+  // Crítica limpa: remove o bloqueio anterior, que também zera o contador de
+  // tentativas na próxima rodada (ver resolveCritiqueAttempt).
+  await removeLabel(token, owner, repo, number, LABEL_CRITIQUE_FAILED).catch(() => {});
+  await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: true });
+}
+
+// Fecho comum do rascunho aprovado: libera para revisão humana e o apply.
+async function finishDraft({ token, owner, repo, issueNumber, docRel }, { blobUrl, itemCount, critiqued }) {
+  const number = parseInt(issueNumber, 10);
+  await addLabel(token, owner, repo, number, LABEL_DECOMPOSE_READY);
+  await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE);
+  await commentOnIssue(token, owner, repo, number,
+    `📝 **Rascunho de decomposição pronto para revisão** (${itemCount}).\n\n` +
+    `📄 Arquivo: [\`${docRel}\`](${blobUrl})\n\n` +
+    (critiqued
+      ? 'A crítica adversarial não encontrou contradições graves. '
+      : '') +
+    `**Nada foi criado ainda.** Revise (e edite, se quiser) o arquivo e então crie as issues:\n` +
+    `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE_APPLY}"\n\`\`\`\n` +
+    `Se preferir uma nova crítica depois de editar, reaplique \`${LABEL_DECOMPOSE}\` — ` +
+    'o arquivo é criticado como está, sem ser regerado. Para gerar outro do zero, apague-o.'
+  ).catch(err => console.warn(`Falha ao comentar o rascunho: ${err.message}`));
+  console.log(`Rascunho liberado para revisão: ${itemCount}.`);
+}
+
+// ---------------------------------------------------------------------------
+// Etapa 2: aplicação (label spec-wave:decompose-apply)
+// ---------------------------------------------------------------------------
+
+async function applyDecomposition(ctx) {
+  const { token, owner, repo, issueNumber, docPath, docRel } = ctx;
+  const number = parseInt(issueNumber, 10);
+
+  if (!existsSync(docPath)) {
+    await commentOnIssue(token, owner, repo, number,
+      `❌ **Não há rascunho de decomposição para aplicar.**\n\n` +
+      `Esperava encontrar \`${docRel}\`. Gere o rascunho primeiro:\n` +
+      `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE}"\n\`\`\``
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY).catch(() => {});
+    throw new DecomposeBlockedError(`${docRel} não encontrado — aplique ${LABEL_DECOMPOSE} primeiro.`);
+  }
+
+  let doc;
+  try {
+    doc = parseDecompositionDoc(readFileSync(docPath, 'utf-8'));
+  } catch (err) {
+    await commentOnIssue(token, owner, repo, number,
+      `❌ **Não consegui ler o rascunho da decomposição.**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `Corrija \`${docRel}\` e reaplique \`${LABEL_DECOMPOSE_APPLY}\`.`
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY).catch(() => {});
+    throw new DecomposeBlockedError(err.message);
+  }
+
+  // O slug vem do TÍTULO da issue: se a Feature foi retitulada entre o rascunho e
+  // o apply, o arquivo encontrado pode ser de outra issue. Aviso, não erro — o
+  // humano é quem sabe se houve renomeação.
+  if (doc.issueNumber && doc.issueNumber !== number) {
+    console.warn(
+      `⚠️ ${docRel} foi gerado para a issue #${doc.issueNumber}, não a #${number} ` +
+      '(a issue foi retitulada?). Seguindo com o arquivo encontrado.'
+    );
   }
 
+  // Campos do board só são resolvidos aqui: a etapa de rascunho não toca o board.
+  const { project, etapaField, statusField } = await resolveBoard(ctx);
+  const applyCtx = { ...ctx, project, etapaField, statusField };
+
+  if (doc.kind === 'tasks') await createTasksFromDoc(applyCtx, doc);
+  else await createStoriesFromDoc(applyCtx, doc);
+
+  await addLabel(token, owner, repo, number, LABEL_DECOMPOSED)
+    .catch(err => console.warn(`Falha ao aplicar a label ${LABEL_DECOMPOSED}: ${err.message}`));
+  await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY);
+  await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_READY).catch(() => {});
+}
+
+async function createStoriesFromDoc(ctx, doc) {
+  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, docRel } = ctx;
   const featureNodeId = issue.node_id;
   const created = [];
   const createdStories = []; // issues criadas, na ordem dos índices das stories
   const generatedTexts = []; // títulos+corpos para o lint de idioma final
 
-  for (let i = 0; i < decomposition.stories.length; i++) {
-    const story = decomposition.stories[i];
+  for (let i = 0; i < doc.stories.length; i++) {
+    const story = doc.stories[i];
     console.log(`Criando story: ${story.title}`);
     const storyTitle = `[STORY] ${story.title}`;
     let storyBody = [story.userStory, story.body]
@@ -238,13 +495,8 @@ async function decomposeFeature(ctx) {
       .filter(Boolean)
       .join('\n\n') || '_(sem descrição)_';
 
-    // Dependências: índices 0-based de stories anteriores. Default quando o
-    // campo está ausente: sequencial (story i depende da i-1). [] explícito =
-    // sem dependências. Índices inválidos/futuros são ignorados.
-    const depIndexes = Array.isArray(story.dependsOn)
-      ? [...new Set(story.dependsOn.filter(d => Number.isInteger(d) && d >= 0 && d < i))]
-      : (i > 0 ? [i - 1] : []);
-    const depIssues = depIndexes.map(idx => createdStories[idx]).filter(Boolean);
+    // dependsOn já vem validado pelo parser (0-based, só para trás).
+    const depIssues = story.dependsOn.map(idx => createdStories[idx]).filter(Boolean);
     const depLine = formatDependencyLine(depIssues.map(d => d.number));
     if (depLine) storyBody += `\n\n${depLine}`;
 
@@ -299,43 +551,23 @@ async function decomposeFeature(ctx) {
     console.warn(`Falha ao mover Feature para "${STAGE_READY}": ${err.message}`);
   }
 
-  // Marca a Feature como decomposta (guard de idempotência em runs futuros).
-  try {
-    await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_DECOMPOSED);
-  } catch (err) {
-    console.warn(`Falha ao aplicar a label ${LABEL_DECOMPOSED}: ${err.message}`);
-  }
-  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:decompose');
   const list = created.map(s => `- ${s.url} — ${s.title}`).join('\n');
-  await commentOnIssue(
-    token, owner, repo, parseInt(issueNumber, 10),
-    `🔀 **Decomposição concluída!**\n\n` +
-    `Foram criados ${decomposition.stories.length} stories e suas tasks:\n\n${list}\n\n` +
+  await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
+    `🔀 **Decomposição aplicada!**\n\n` +
+    `A partir de \`${docRel}\` foram criados ${created.length} stories e suas tasks:\n\n${list}\n\n` +
     `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx @spec-wave/cli@latest implement ${issueNumber}\` (Stories em ordem de dependência).` +
     formatItemsLintWarning(generatedTexts)
   );
-  console.log(`Decomposição concluída: ${decomposition.stories.length} stories criadas.`);
+  console.log(`Decomposição aplicada: ${created.length} stories criadas.`);
 }
 
-// Decompõe um RFC diretamente em Tasks (sem Stories), cada uma vinculada como
-// sub-issue do RFC.
-async function decomposeRFC(ctx) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage } = ctx;
-  console.log(`Decompondo RFC: ${issue.title}`);
-
-  const userContent = [
-    `RFC: ${issue.title}`,
-    `Issue #${issueNumber}`,
-    `\n## Descrição\n${issue.body || '(sem descrição)'}`,
-  ].join('\n');
-
-  const decomposition = parseModelJson(await generateDocument(RFC_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
-  const rfcNodeId = issue.node_id;
-  const tasks = decomposition.tasks || [];
+async function createTasksFromDoc(ctx, doc) {
+  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, docRel } = ctx;
+  const parentNodeId = issue.node_id;
   const created = [];
-  const generatedTexts = []; // títulos+corpos para o lint de idioma final
+  const generatedTexts = [];
 
-  for (const task of tasks) {
+  for (const task of doc.tasks) {
     console.log(`Criando task: ${task.title}`);
     const taskTitle = `[TASK] ${task.title}`;
     const taskBody = `${task.body}\n\n_RFC pai: ${issue.html_url || `#${issueNumber}`}_`;
@@ -344,7 +576,7 @@ async function decomposeRFC(ctx) {
     generatedTexts.push(taskTitle, taskBody);
 
     try {
-      await addSubIssue(token, rfcNodeId, createdTask.nodeId);
+      await addSubIssue(token, parentNodeId, createdTask.nodeId);
     } catch (err) {
       console.warn(`  Task #${createdTask.number} criada, mas falhou ao vincular ao RFC: ${err.message}`);
     }
@@ -355,25 +587,42 @@ async function decomposeRFC(ctx) {
     }
   }
 
-  // Marca o RFC como decomposto (guard de idempotência em runs futuros).
-  try {
-    await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_DECOMPOSED);
-  } catch (err) {
-    console.warn(`Falha ao aplicar a label ${LABEL_DECOMPOSED}: ${err.message}`);
-  }
-  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:decompose');
   const list = created.map(t => `- ${t.url} — ${t.title}`).join('\n');
-  await commentOnIssue(
-    token, owner, repo, parseInt(issueNumber, 10),
-    `🔀 **Decomposição do RFC concluída!**\n\n` +
-    `Foram criadas ${created.length} tasks:\n\n${list}\n\n` +
+  await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
+    `🔀 **Decomposição do RFC aplicada!**\n\n` +
+    `A partir de \`${docRel}\` foram criadas ${created.length} tasks:\n\n${list}\n\n` +
     `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx @spec-wave/cli@latest implement <task>\`.` +
     formatItemsLintWarning(generatedTexts)
   );
-  console.log(`Decomposição concluída: ${created.length} tasks criadas.`);
+  console.log(`Decomposição aplicada: ${created.length} tasks criadas.`);
+}
+
+// Projeto + campos Etapa/Status do board (reutilizados em todos os itens).
+async function resolveBoard({ projectToken, root }) {
+  const { project, error: projectError } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (projectError) console.warn(`${projectError} — itens criados não serão posicionados no board.`);
+  let etapaField = null;
+  let statusField = null;
+  if (project?.id) {
+    try {
+      etapaField = await resolveField(projectToken, project, 'Etapa');
+    } catch (err) {
+      console.warn(`Não foi possível resolver campo Etapa do board: ${err.message}`);
+    }
+    try {
+      statusField = await resolveField(projectToken, project, 'Status');
+    } catch (err) {
+      console.warn(`Não foi possível resolver campo Status do board: ${err.message}`);
+    }
+  }
+  return { project, etapaField, statusField };
 }
 
-export async function decompose({ issueNumber }) {
+// ---------------------------------------------------------------------------
+// Entrada
+// ---------------------------------------------------------------------------
+
+export async function decompose({ issueNumber, apply = false }) {
   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).
@@ -388,21 +637,36 @@ export async function decompose({ issueNumber }) {
     );
   }
 
-  const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+  const number = parseInt(issueNumber, 10);
+  const issue = await getIssue(token, owner, repo, number);
   const type = detectIssueType(issue);
+  const labels = labelNames(issue);
+  const mode = resolveDecomposeMode({ labels, apply });
+  const trigger = mode === 'apply' ? LABEL_DECOMPOSE_APPLY : LABEL_DECOMPOSE;
 
   // Só Feature (→ Stories) e RFC (→ Tasks) podem ser decompostos.
   if (!DECOMPOSE_TARGETS[type]) {
     console.log(`Issue #${issueNumber} é ${type || 'desconhecido'} — decompose não se aplica.`);
-    await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:decompose');
-    await commentOnIssue(
-      token, owner, repo, parseInt(issueNumber, 10),
+    await removeLabel(token, owner, repo, number, trigger);
+    await commentOnIssue(token, owner, repo, number,
       `ℹ️ **decompose não se aplica a ${type || 'este tipo'}.** ` +
       `Use em **Features** (gera Stories + Tasks) ou **RFCs** (gera Tasks).`
     ).catch(() => {});
     return;
   }
 
+  // Revisão humana pendente: nada roda até a label sair.
+  if (labels.includes(LABEL_NEEDS_HUMAN)) {
+    console.log(`Decompose ignorado: a issue tem a label ${LABEL_NEEDS_HUMAN}.`);
+    await removeLabel(token, owner, repo, number, trigger);
+    await commentOnIssue(token, owner, repo, number,
+      `⏸️ **decompose parado:** a issue tem a label \`${LABEL_NEEDS_HUMAN}\`, aplicada depois de ` +
+      'reprovas consecutivas da crítica. Corrija os documentos e remova a label ' +
+      `(e a \`${LABEL_CRITIQUE_FAILED}\`) para retomar o fluxo.`
+    ).catch(() => {});
+    return;
+  }
+
   // Guard de idempotência: label spec-wave:decomposed ou sub-issues do
   // tipo-alvo já existentes → não re-decompõe (evita duplicar stories/tasks).
   let subIssues = [];
@@ -412,45 +676,63 @@ export async function decompose({ issueNumber }) {
     console.warn(`Não foi possível listar sub-issues: ${err.message} — seguindo sem o guard de sub-issues.`);
     subIssues = [];
   }
-  const guard = shouldSkipDecompose({ labels: issue.labels || [], subIssues, type });
+  const guard = shouldSkipDecompose({ 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),
+    await removeLabel(token, owner, repo, number, trigger);
+    await commentOnIssue(token, owner, repo, number,
       `⏭️ **decompose ignorado:** ${guard.reason}. Para forçar, remova a label ` +
       `\`${LABEL_DECOMPOSED}\` (e apague as sub-issues antigas se quiser re-gerar).`
     ).catch(() => {});
     return;
   }
 
-  // Projeto + campos Etapa/Status do board (reutilizados em todos os itens).
-  const { project, error: projectError } = loadProjectConfig();
-  if (projectError) console.warn(`${projectError} — itens criados não serão posicionados no board.`);
-  let etapaField = null;
-  let statusField = null;
-  if (project?.id) {
-    try {
-      etapaField = await resolveField(projectToken, project, 'Etapa');
-    } catch (err) {
-      console.warn(`Não foi possível resolver campo Etapa do board: ${err.message}`);
-    }
-    try {
-      statusField = await resolveField(projectToken, project, 'Status');
-    } catch (err) {
-      console.warn(`Não foi possível resolver campo Status do board: ${err.message}`);
-    }
+  // Config do repo: raiz para os caminhos de documento e escalada da crítica.
+  const { config, root } = loadConfig();
+  const { rel: docRel, dir: docDir } = resolveDocDir(root, issue, type);
+  const docPath = path.join(docDir, DECOMPOSITION_FILE);
+
+  // Comentários só são necessários no rascunho (contador de tentativas).
+  let comments = [];
+  if (mode === 'draft') {
+    comments = await listIssueComments(token, owner, repo, number)
+      .catch(err => {
+        console.warn(`Não foi possível listar comentários: ${err.message} — contador de tentativas em 1.`);
+        return [];
+      });
   }
 
   // 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.
+  // fluxos que abortam (ex.: crítica grave) ou que falham.
   const usageEntries = [];
-  const ctx = { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage: usageEntries };
+  const ctx = {
+    token, projectToken, owner, repo, issue, issueNumber, type, labels, comments,
+    root, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    escalationModel: config?.ai?.escalationModel || null,
+    maxCritiqueAttempts:
+      Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0
+        ? config.ai.maxCritiqueAttempts
+        : DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+    usage: usageEntries,
+  };
+
   try {
-    if (type === 'Feature') await decomposeFeature(ctx);
-    else if (type === 'RFC') await decomposeRFC(ctx);
+    if (mode === 'apply') await applyDecomposition(ctx);
+    else await draftDecomposition(ctx);
+  } catch (err) {
+    // Paradas por decisão do fluxo já comentaram na issue; erros inesperados não.
+    if (!err.blocked) {
+      await removeLabel(token, owner, repo, number, trigger).catch(() => {});
+      await commentOnIssue(token, owner, repo, number,
+        `❌ **Falha no decompose (${mode === 'apply' ? 'aplicação' : 'rascunho'}).**\n\n` +
+        `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+        `A label \`${trigger}\` foi removida para destravar o gatilho — ` +
+        'adicione-a de novo para tentar outra vez.'
+      ).catch(() => {});
+    }
+    throw err;
   } finally {
     // Best-effort: nunca propaga erro (ver recordUsage).
-    await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });
+    await recordUsage({ token, owner, repo, issueNumber: number, entries: usageEntries });
   }
 }