@spec-wave/cli 0.18.1 → 0.20.0

package/src/commands/code-review.mjs

@@ -1,10 +1,16 @@
+import { appendFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, getPR, commentOnIssue } from '../api/github-rest.mjs';
-import { addProjectItem, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import {
+  addProjectItem, getIssueParent, listSubIssues, getItemSingleSelectValue, getPRClosingIssues,
+} from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
-import { STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType } from '../config.mjs';
+import {
+  STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType,
+  LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY, labelNames,
+} from '../config.mjs';
 
 // Ao abrir o PR: Stories/Feature → Etapa "👀 Code Review" (Status "Todo");
 // Tasks → Etapa "🎉 Done" (Status "Done"), pois a implementação da task terminou.
@@ -13,18 +19,76 @@ const DONE_STAGE = STAGE_DONE;
 const TODO_STATUS = PROGRESS_TODO;
 const DONE_STATUS = PROGRESS_DONE;
 
-// Extrai números de issues referenciadas no corpo do PR (Closes #N, Fixes #N, #N solto).
-function extractIssueNumbers(body) {
+// Vínculo EXPLÍCITO: o verbo é obrigatório. `Relacionado: #10` e `#10` solto
+// deixaram de contar — referência cruzada em PR é prática comum (uma PR de
+// documentação citando três Features moveu as três para 👀 Code Review, e uma
+// delas nem plano tinha). Aceita `#N`, `owner/repo#N` e a URL completa da issue.
+const EXPLICIT_LINK_RE =
+  /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|implement(?:s|ed)?)\b\s*:?\s+(?:https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/(\d+)|[\w.-]+\/[\w.-]+#(\d+)|#(\d+))/gi;
+
+// Forma antiga, atrás do knob `codeReview.linkMode: "any-mention"`.
+const ANY_MENTION_RE = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
+
+// Blocos de código não são vínculo: um `Closes #12` dentro de um exemplo de
+// commit message é documentação, não promessa.
+function stripCodeBlocks(body) {
+  return String(body)
+    .replace(/^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[ \t]*$/gm, '\n')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+/**
+ * Números de issues que o PR declara implementar (função PURA — testável).
+ *
+ * @param {string} body corpo do PR
+ * @param {object} [opts]
+ * @param {'explicit'|'any-mention'} [opts.linkMode='explicit']
+ * @returns {number[]} na ordem em que aparecem, sem repetição
+ */
+export function extractIssueNumbers(body, { linkMode = 'explicit' } = {}) {
   if (!body) return [];
   const nums = new Set();
-  const re = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
-  for (const m of body.matchAll(re)) {
-    const n = parseInt(m[1] || m[2], 10);
+  const text = stripCodeBlocks(body);
+  const re = linkMode === 'any-mention' ? ANY_MENTION_RE : EXPLICIT_LINK_RE;
+  re.lastIndex = 0;
+  for (const m of text.matchAll(re)) {
+    const n = parseInt(m.slice(1).find(Boolean) || '', 10);
     if (n) nums.add(n);
   }
   return [...nums];
 }
 
+/**
+ * Recorte temporal da subárvore (função PURA — testável).
+ *
+ * Uma sub-issue criada DEPOIS que o PR foi aberto não faz parte daquele PR. Foi
+ * assim que o `decompose-apply` da #10 e o `code-review` da PR #528 se
+ * atropelaram: o comando leu a subárvore no meio da criação das issues e moveu
+ * o que existia naquele instante — duas Stories fundacionais e duas Tasks
+ * nasceram concluídas.
+ *
+ * `pr.created_at` é a referência (e não o relógio do run) porque é determinístico:
+ * reexecutar o mesmo PR dá o mesmo recorte.
+ *
+ * @param {Array<{number,createdAt?}>} subs sub-issues como vêm do listSubIssues
+ * @param {string|null} notAfter ISO-8601; null desliga o recorte
+ * @returns {{ kept: Array, skipped: Array }}
+ */
+export function partitionByCreation(subs = [], notAfter = null) {
+  if (!notAfter) return { kept: [...subs], skipped: [] };
+  const limit = Date.parse(notAfter);
+  if (Number.isNaN(limit)) return { kept: [...subs], skipped: [] };
+  const kept = [];
+  const skipped = [];
+  for (const sub of subs) {
+    const at = sub?.createdAt ? Date.parse(sub.createdAt) : NaN;
+    // Sem data legível não dá para afirmar que nasceu depois — mantém.
+    if (Number.isNaN(at) || at <= limit) kept.push(sub);
+    else skipped.push(sub);
+  }
+  return { kept, skipped };
+}
+
 // A partir de qualquer issue (Feature/Story/Task), sobe a hierarquia e retorna a Feature.
 async function resolveFeatureIssue(token, owner, repo, issueNumber) {
   let issue;
@@ -70,21 +134,32 @@ export function classifyReviewTarget(type) {
   return 'ignore';
 }
 
-async function collectReviewUnit(token, owner, repo, issueNumber) {
+// Labels que dizem "há uma decomposição em curso nesta Feature". Descer para a
+// subárvore no meio disso é a corrida do item 3 — melhor não tocar em nada e
+// deixar o humano reexecutar.
+const DECOMPOSING_LABELS = [LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY];
+
+function isDecomposing(issue) {
+  return labelNames(issue?.labels || []).some(n => DECOMPOSING_LABELS.includes(n));
+}
+
+async function collectReviewUnit(token, owner, repo, issueNumber, { notAfter = null } = {}) {
   const stories = new Map();
   const tasks = new Map();
   const bugs = new Map();
+  const skipped = [];
   const addStory = (n, nodeId, title) => { if (n && nodeId && !stories.has(n)) stories.set(n, { nodeId, title }); };
   const addTask = (n, nodeId, title) => { if (n && nodeId && !tasks.has(n)) tasks.set(n, { nodeId, title }); };
+  const empty = (extra = {}) => ({ feature: null, stories, tasks, bugs, skipped, deferred: null, ...extra });
 
   let issue;
-  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, stories, tasks, bugs }; }
+  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return empty(); }
   const type = detectIssueType(issue);
   const kind = classifyReviewTarget(type);
-  if (kind === 'ignore') return { feature: null, stories, tasks, bugs };
+  if (kind === 'ignore') return empty();
   if (kind === 'bug') {
     bugs.set(issue.number, { nodeId: issue.node_id, title: issue.title });
-    return { feature: null, stories, tasks, bugs };
+    return empty({ bugs });
   }
 
   const featureIssue = await resolveFeatureIssue(token, owner, repo, issueNumber);
@@ -92,32 +167,42 @@ async function collectReviewUnit(token, owner, repo, issueNumber) {
     ? { number: featureIssue.number, nodeId: featureIssue.node_id, title: featureIssue.title }
     : null;
 
+  // Decomposição em curso: as sub-issues estão sendo criadas AGORA. Mover o que
+  // já existe deixa o board mentindo sobre metade da árvore.
+  if (isDecomposing(issue) || (featureIssue && isDecomposing(featureIssue))) {
+    return empty({ deferred: (featureIssue || issue).number });
+  }
+
   // Spikes (tipos manuais) nunca são movidos automaticamente — pulados aqui.
   const isManual = (sub) => isManualStageType(detectIssueType({ title: sub.title, labels: sub.labels }));
 
+  // Desce um nível aplicando o recorte temporal, registrando o que ficou de fora.
+  const children = async (nodeId) => {
+    const all = await listSubIssues(token, nodeId).catch(() => []);
+    const { kept, skipped: out } = partitionByCreation(all, notAfter);
+    skipped.push(...out);
+    return kept;
+  };
+
   if (type === 'Feature') {
     // Referência direta à Feature: toda a subárvore (Stories + Tasks).
-    const subs = await listSubIssues(token, issue.node_id).catch(() => []);
-    for (const st of subs) {
+    for (const st of await children(issue.node_id)) {
       if (isManual(st)) continue;
       addStory(st.number, st.nodeId, st.title);
-      const tks = await listSubIssues(token, st.nodeId).catch(() => []);
-      for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
+      for (const t of await children(st.nodeId)) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
     }
   } else if (type === 'Story') {
     addStory(issue.number, issue.node_id, issue.title);
-    const tks = await listSubIssues(token, issue.node_id).catch(() => []);
-    for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
+    for (const t of await children(issue.node_id)) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
   } else { // Task → inclui a Story pai e as Tasks irmãs.
     addTask(issue.number, issue.node_id, issue.title);
     const parent = await getIssueParent(token, issue.node_id).catch(() => null);
     if (parent && detectIssueType({ title: parent.title }) === 'Story') {
       addStory(parent.number, parent.nodeId, parent.title);
-      const tks = await listSubIssues(token, parent.nodeId).catch(() => []);
-      for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
+      for (const t of await children(parent.nodeId)) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
     }
   }
-  return { feature, stories, tasks, bugs };
+  return { feature, stories, tasks, bugs, skipped, deferred: null };
 }
 
 // A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
@@ -137,7 +222,7 @@ async function allStoriesReadyForReview(readToken, projToken, project, etapaFiel
   return true;
 }
 
-export async function codeReview({ prNumber }) {
+export async function codeReview({ prNumber, resolveOnly = false }) {
   const token = await resolveToken();
   const projectToken = process.env.PROJECT_TOKEN || token;
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
@@ -153,10 +238,37 @@ export async function codeReview({ prNumber }) {
   }
 
   const pr = await getPR(token, owner, repo, parseInt(prNumber, 10));
-  const issueNums = extractIssueNumbers(pr.body || '');
+  const linkMode = cfg?.codeReview?.linkMode === 'any-mention' ? 'any-mention' : 'explicit';
+
+  // Duas fontes de vínculo, nesta ordem: o que o GitHub reconhece nativamente
+  // (o mesmo que fecha a issue no merge, e que cobre o vínculo feito pela UI) e
+  // o que está escrito no corpo. `Implements #N` só existe na segunda.
+  const linked = await getPRClosingIssues(token, owner, repo, parseInt(prNumber, 10)).catch(err => {
+    console.warn(`Não foi possível ler os vínculos nativos do PR: ${err.message}`);
+    return [];
+  });
+  const issueNums = [...new Set([...linked, ...extractIssueNumbers(pr.body || '', { linkMode })])];
 
   if (issueNums.length === 0) {
-    console.log('PR sem referências a issues — nenhuma Feature atualizada.');
+    console.log(
+      linkMode === 'explicit'
+        ? 'PR sem vínculo explícito (Closes/Fixes/Resolves/Implements #N) — board não atualizado. ' +
+          'Menção solta a uma issue é referência cruzada, não implementação.'
+        : 'PR sem referências a issues — nenhuma Feature atualizada.'
+    );
+    if (resolveOnly) emitResolved(null);
+    return;
+  }
+
+  // `--resolve-only`: só descobre a Feature-alvo e imprime, para o workflow
+  // poder declarar a concurrency por ITEM antes de tocar no board (o job que
+  // move fica atrás da mesma trava do decompose).
+  if (resolveOnly) {
+    for (const num of issueNums) {
+      const feature = await resolveFeatureIssue(token, owner, repo, num).catch(() => null);
+      if (feature) { emitResolved(feature.number); return; }
+    }
+    emitResolved(issueNums[0]);
     return;
   }
 
@@ -174,12 +286,26 @@ export async function codeReview({ prNumber }) {
   const seen = new Set();
   const updated = [];
   const featuresChecked = new Set();
+  const deferred = new Set();
+  const ignored = [];
 
   // Regras ao abrir o PR: Tasks → 🎉 Done (implementação concluída);
   // Stories → 👀 Code Review; Feature → Code Review só quando TODAS as suas
   // Stories já estiverem em Code Review.
   for (const num of issueNums) {
-    const { feature, stories, tasks, bugs } = await collectReviewUnit(token, owner, repo, num);
+    const unit = await collectReviewUnit(token, owner, repo, num, { notAfter: pr.created_at });
+    const { feature, stories, tasks, bugs } = unit;
+    if (unit.deferred) {
+      deferred.add(unit.deferred);
+      console.log(
+        `#${unit.deferred} está com decomposição em andamento — board não atualizado para esta unidade.`
+      );
+      continue;
+    }
+    for (const sub of unit.skipped) {
+      ignored.push(`#${sub.number} ${sub.title}`);
+      console.log(`#${sub.number} criada depois da abertura do PR (${sub.createdAt}) — fora desta review.`);
+    }
 
     // Tasks → Done (Status Done).
     for (const [n, info] of tasks) {
@@ -255,14 +381,43 @@ export async function codeReview({ prNumber }) {
     }
   }
 
-  if (updated.length > 0) {
-    await commentOnIssue(
-      token, owner, repo, parseInt(prNumber, 10),
-      `🔍 **Code Review iniciado**\n\n` +
-      `Board atualizado (Tasks → **${DONE_STAGE}**; Story → **${CODE_REVIEW_STAGE}**; Feature só avança quando todas as Stories concluírem):\n\n` +
-      updated.map(f => `- ${f}`).join('\n')
-    ).catch(() => {});
+  if (updated.length > 0 || deferred.size > 0) {
+    const partes = [];
+    if (updated.length > 0) {
+      partes.push(
+        `🔍 **Code Review iniciado**\n\n` +
+        `Board atualizado (Tasks → **${DONE_STAGE}**; Story → **${CODE_REVIEW_STAGE}**; Feature só avança quando todas as Stories concluírem):\n\n` +
+        updated.map(f => `- ${f}`).join('\n')
+      );
+    }
+    // O que ficou de fora precisa ser dito: silêncio aqui vira "o board está
+    // certo" na cabeça de quem lê, que é exatamente o erro que se quer evitar.
+    if (ignored.length > 0) {
+      partes.push(
+        `_Fora desta review (criadas depois da abertura do PR):_\n\n${ignored.map(i => `- ${i}`).join('\n')}`
+      );
+    }
+    if (deferred.size > 0) {
+      partes.push(
+        `⏳ **Board não atualizado** para ${[...deferred].map(n => `#${n}`).join(', ')}: ` +
+        'há decomposição em andamento. Depois que ela terminar, rode ' +
+        `\`npx @spec-wave/cli@latest code-review --pr-number ${prNumber}\`.`
+      );
+    }
+    await commentOnIssue(token, owner, repo, parseInt(prNumber, 10), partes.join('\n\n')).catch(() => {});
   }
 
   console.log(`code-review: ${updated.length} item(ns) atualizado(s) no board.`);
 }
+
+// Saída do `--resolve-only`: linha legível + `feature=<n>` no GITHUB_OUTPUT,
+// que é o que o job seguinte usa como chave de concurrency.
+function emitResolved(number) {
+  const value = number ? String(number) : '';
+  console.log(`feature=${value}`);
+  const out = process.env.GITHUB_OUTPUT;
+  if (out) {
+    try { appendFileSync(out, `feature=${value}\n`); }
+    catch (err) { console.warn(`Falha ao escrever em GITHUB_OUTPUT: ${err.message}`); }
+  }
+}

package/src/commands/decompose.mjs

@@ -23,7 +23,7 @@ import { resolveToken } from '../api/auth.mjs';
 import {
   getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
 } from '../api/github-rest.mjs';
-import { addSubIssue, listSubIssues } from '../api/github-graphql.mjs';
+import { addSubIssue, listSubIssues, getProjectSnapshot } from '../api/github-graphql.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import {
@@ -31,13 +31,13 @@ import {
   parseCritiqueDecisions, applyCritiqueDecisions, renderRiskAcceptedComment,
 } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
-import { formatDependencyLine } from '../lib/dependencies.mjs';
+import { formatDependencyLine, orderStories, renderOrderComment } 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 { loadConfig } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
-import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
+import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import {
   renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
 } from '../lib/decomposition-doc.mjs';
@@ -54,6 +54,24 @@ async function moveToReady(token, project, etapaField, statusField, nodeId) {
   await advanceToStage(token, project, etapaField, statusField, nodeId, STAGE_READY, PROGRESS_TODO);
 }
 
+/**
+ * Board inalcançável no apply — parada ANTES de criar qualquer issue.
+ *
+ * Separado de DecomposeBlockedError porque o remédio é outro: aqui nada foi
+ * criado e o problema é de credencial/config, não do conteúdo do rascunho.
+ */
+class BoardUnreachableError extends Error {
+  constructor(motivo) {
+    super(
+      `Board inalcançável: ${motivo}. Nenhuma issue foi criada — ` +
+      'sem escrita no board elas nasceriam sem Etapa e ficariam invisíveis em todas as telas. ' +
+      'Verifique se o GH_PROJECT_TOKEN tem scope `project` e acesso ao Project da organização.'
+    );
+    this.name = 'BoardUnreachableError';
+    this.boardUnreachable = true;
+  }
+}
+
 /**
  * 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,
@@ -252,9 +270,9 @@ async function draftDecomposition(ctx) {
       { cwd: root },
     );
     const generated = parseModelJson(await generateDocument(
-      toolFreeSystemPrompt(decomposePrompt),
+      systemPromptWithTools(decomposePrompt),
       userContent,
-      { action: 'decompose', labels, usage }
+      { action: 'decompose', labels, usage, maxTurns: decomposePrompt.maxTurns }
     ));
 
     markdown = renderDecompositionDoc({
@@ -438,16 +456,89 @@ async function applyDecomposition(ctx) {
   }
 
   // Campos do board só são resolvidos aqui: a etapa de rascunho não toca o board.
-  const { project, etapaField, statusField } = await resolveBoard(ctx);
+  // `strict`: no apply, board inalcançável ABORTA antes da primeira criação.
+  const { project, etapaField, statusField } = await resolveBoard(ctx, { strict: true });
   const applyCtx = { ...ctx, project, etapaField, statusField };
 
-  if (doc.kind === 'tasks') await createTasksFromDoc(applyCtx, doc);
-  else await createStoriesFromDoc(applyCtx, doc);
+  // As falhas de board voltam em vez de subir na hora: a exceção precisa esperar
+  // a contabilidade de labels abaixo. Lançar aqui deixaria o gatilho
+  // `spec-wave:decompose-apply` preso na issue — e `issues: [labeled]` não
+  // redispara com a label ainda aplicada, o mesmo beco sem saída que o
+  // generate-plan já evita.
+  const boardFailures = doc.kind === 'tasks'
+    ? await createTasksFromDoc(applyCtx, doc)
+    : await createStoriesFromDoc(applyCtx, doc);
+
+  // O arquivo passa a REGISTRAR o que foi criado, em vez de continuar
+  // descrevendo só a proposta. Sem isto, rescopar as issues à mão (o que é
+  // legítimo e acontece) deixa o decomposition.md como registro enganoso, e nada
+  // no fluxo percebe: o guard `spec-wave:decomposed` impede duplicar, não
+  // desatualizar.
+  //
+  // Depois da criação de propósito: se este commit falhar, as issues já existem
+  // e o pior caso é o comportamento anterior (arquivo sem anotação), avisado no
+  // log. O contrário — anotar antes e falhar na criação — inventaria issues.
+  try {
+    commitFile(
+      docPath,
+      renderDecompositionDoc({ ...doc, appliedAt: new Date().toISOString() }),
+      `docs: registra as issues criadas em ${docRel} [spec-wave]`,
+      ctx.runMode,
+    );
+    console.log(`${docRel} anotado com as issues criadas.`);
+  } catch (err) {
+    console.warn(
+      `⚠️  Issues criadas, mas ${docRel} não foi anotado (${err.message}). ` +
+      'O arquivo segue descrevendo a proposta, não o que existe.'
+    );
+  }
 
   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(() => {});
+
+  // Por último, com as labels já consistentes: escrita de board incompleta
+  // termina o run em VERMELHO.
+  failIfBoardIncomplete(boardFailures);
+}
+
+/**
+ * Bloco do comentário quando itens ficaram sem Etapa (função PURA).
+ *
+ * O comentário é postado ANTES de a exceção subir: quem for reparar precisa da
+ * lista, e ela não pode depender de alguém abrir o log do Action.
+ */
+export function renderBoardFailures(failures) {
+  const linhas = failures.map(f => `- ${f.kind} #${f.number}`).join('\n');
+  const motivo = failures[0]?.reason || 'erro desconhecido';
+  return (
+    `⚠️ **${failures.length} item(ns) ficaram SEM Etapa no board** — eles existem, mas ` +
+    'não aparecem em nenhuma tela (o inbox do PM lista Features, a tela do Dev lê ' +
+    '🚧 Desenvolvimento, a fila do TL lê ✅ Ready):\n\n' +
+    `${linhas}\n\n` +
+    `Motivo: \`${motivo}\`\n\n` +
+    'Verifique o `GH_PROJECT_TOKEN` (scope `project` e acesso ao Project da organização) e ' +
+    'reposicione os itens com `npx @spec-wave/cli@latest repair-stage <issue>`.'
+  );
+}
+
+/**
+ * Escrita do board incompleta = run VERMELHO.
+ *
+ * O apply criava as issues e engolia TODA falha de board, terminando com exit 0:
+ * 27 issues nasceram sem Etapa, invisíveis em todas as telas, com o Action ✓ —
+ * só se descobriu rodando `order` por acaso. É o mesmo princípio que o fluxo já
+ * aplica à crítica ("um pipeline bloqueado nunca fica verde") e ao truncamento
+ * ("documento cortado vale menos que documento nenhum").
+ */
+function failIfBoardIncomplete(failures) {
+  if (failures.length === 0) return;
+  const err = new DecomposeBlockedError(
+    `${failures.length} item(ns) criados ficaram sem Etapa no board — ` +
+    'as issues existem mas estão invisíveis nas telas. Ver o comentário na issue para reparar.'
+  );
+  throw err;
 }
 
 async function createStoriesFromDoc(ctx, doc) {
@@ -456,6 +547,9 @@ async function createStoriesFromDoc(ctx, doc) {
   const created = [];
   const createdStories = []; // issues criadas, na ordem dos índices das stories
   const generatedTexts = []; // títulos+corpos para o lint de idioma final
+  // Item que não consegue Etapa fica invisível em todas as telas. Coletar em vez
+  // de só avisar é o que permite o run terminar VERMELHO — ver reportBoardFailures.
+  const boardFailures = [];
 
   for (let i = 0; i < doc.stories.length; i++) {
     const story = doc.stories[i];
@@ -472,6 +566,9 @@ async function createStoriesFromDoc(ctx, doc) {
     if (depLine) storyBody += `\n\n${depLine}`;
 
     const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]']);
+    // Anota no doc em memória: é daqui que sai o `**Issue:** #N` gravado no
+    // arquivo no fim do apply.
+    story.issue = createdStory.number;
     created.push({ title: storyTitle, url: createdStory.url });
     createdStories.push(createdStory);
     generatedTexts.push(storyTitle, storyBody);
@@ -494,6 +591,7 @@ async function createStoriesFromDoc(ctx, doc) {
       await moveToReady(projectToken, project, etapaField, statusField, createdStory.nodeId);
     } catch (err) {
       console.warn(`  Falha ao mover story #${createdStory.number} para "${STAGE_READY}": ${err.message}`);
+      boardFailures.push({ number: createdStory.number, kind: 'Story', reason: err.message });
     }
 
     for (const task of story.tasks || []) {
@@ -501,6 +599,7 @@ async function createStoriesFromDoc(ctx, doc) {
       const taskTitle = `[TASK] ${task.title}`;
       const taskBody = `${task.body}\n\n_Story pai: ${createdStory.url}_`;
       const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]']);
+      task.issue = createdTask.number;
       generatedTexts.push(taskTitle, taskBody);
       try {
         await addSubIssue(token, createdStory.nodeId, createdTask.nodeId);
@@ -511,6 +610,7 @@ async function createStoriesFromDoc(ctx, doc) {
         await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
       } catch (err) {
         console.warn(`    Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
+        boardFailures.push({ number: createdTask.number, kind: 'Task', reason: err.message });
       }
     }
   }
@@ -520,16 +620,68 @@ async function createStoriesFromDoc(ctx, doc) {
     if (project?.id && etapaField) console.log(`Feature movida para "${STAGE_READY}" no board.`);
   } catch (err) {
     console.warn(`Falha ao mover Feature para "${STAGE_READY}": ${err.message}`);
+    boardFailures.push({ number: parseInt(issueNumber, 10), kind: 'Feature', reason: err.message });
   }
 
   const list = created.map(s => `- ${s.url} — ${s.title}`).join('\n');
+  const posicionamento = boardFailures.length === 0
+    ? `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx @spec-wave/cli@latest implement ${issueNumber}\` (Stories em ordem de dependência).`
+    : renderBoardFailures(boardFailures);
   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).` +
+    posicionamento +
     formatItemsLintWarning(generatedTexts)
-  );
+  ).catch(err => console.warn(`Falha ao comentar a decomposição: ${err.message}`));
+
+  await commentStoryOrder({ token, owner, repo, issueNumber, doc, createdStories });
+
   console.log(`Decomposição aplicada: ${created.length} stories criadas.`);
+  return boardFailures;
+}
+
+/**
+ * Publica a ordem de execução das Stories como um segundo comentário.
+ *
+ * Os dados saem do que ACABOU de ser criado — `createdStories` (índice → issue)
+ * e `doc.stories[i].dependsOn` (0-based, já validado pelo parser). Não consulta
+ * o board: reconstruir isso pela API custaria ~4 chamadas por Story para chegar
+ * ao que já está em memória, e a Etapa é ✅ Ready por construção — se não fosse,
+ * `failIfBoardIncomplete` já teria derrubado o run.
+ *
+ * BEST-EFFORT, como o comentário que o antecede: a decomposição está feita e
+ * paga, e falhar ao comentar não pode desfazê-la nem mascarar o que deu certo.
+ */
+async function commentStoryOrder({ token, owner, repo, issueNumber, doc, createdStories }) {
+  try {
+    const stories = doc.stories
+      .map((story, i) => {
+        const criada = createdStories[i];
+        if (!criada) return null; // criação falhou no meio: não inventa a Story
+        return {
+          number: criada.number,
+          title: story.title,
+          // dependsOn vem 0-based (índice no doc) e vira número de issue.
+          dependsOn: (story.dependsOn || [])
+            .map(idx => createdStories[idx]?.number)
+            .filter(Boolean),
+        };
+      })
+      .filter(Boolean);
+
+    if (stories.length === 0) return;
+
+    const byNumber = new Map(stories.map(s => [s.number, s]));
+    const { order: sorted, cycle } = orderStories(
+      stories.map(({ number, dependsOn }) => ({ number, dependsOn }))
+    );
+
+    await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
+      renderOrderComment({ sorted, cycle, byNumber }));
+    console.log(`Ordem de execução comentada: ${sorted.length} story(ies).`);
+  } catch (err) {
+    console.warn(`Falha ao comentar a ordem de execução: ${err.message}`);
+  }
 }
 
 async function createTasksFromDoc(ctx, doc) {
@@ -537,12 +689,14 @@ async function createTasksFromDoc(ctx, doc) {
   const parentNodeId = issue.node_id;
   const created = [];
   const generatedTexts = [];
+  const boardFailures = [];
 
   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}`}_`;
     const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]']);
+    task.issue = createdTask.number;
     created.push({ title: taskTitle, url: createdTask.url });
     generatedTexts.push(taskTitle, taskBody);
 
@@ -555,34 +709,65 @@ async function createTasksFromDoc(ctx, doc) {
       await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
     } catch (err) {
       console.warn(`  Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
+      boardFailures.push({ number: createdTask.number, kind: 'Task', reason: err.message });
     }
   }
 
   const list = created.map(t => `- ${t.url} — ${t.title}`).join('\n');
+  const posicionamento = boardFailures.length === 0
+    ? `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx @spec-wave/cli@latest implement <task>\`.`
+    : renderBoardFailures(boardFailures);
   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>\`.` +
+    posicionamento +
     formatItemsLintWarning(generatedTexts)
-  );
+  ).catch(err => console.warn(`Falha ao comentar a decomposição: ${err.message}`));
   console.log(`Decomposição aplicada: ${created.length} tasks criadas.`);
+  return boardFailures;
 }
 
 // Projeto + campos Etapa/Status do board (reutilizados em todos os itens).
-async function resolveBoard({ projectToken, root }) {
+async function resolveBoard({ projectToken, root }, { strict = false } = {}) {
   const { project, error: projectError } = loadProjectConfig({ cwd: root || process.cwd() });
-  if (projectError) console.warn(`${projectError} — itens criados não serão posicionados no board.`);
+  if (projectError) {
+    if (strict) throw new BoardUnreachableError(projectError);
+    console.warn(`${projectError} — itens criados não serão posicionados no board.`);
+  }
+
+  // PREFLIGHT do apply: resolver o NODE do project antes de criar qualquer issue.
+  //
+  // `resolveField` não serve como preflight: ele devolve do cache do config
+  // (`project.fields`) sem tocar a rede, então um token sem acesso ao Project
+  // passava aqui limpo e só falhava na primeira mutação — depois de 27 issues
+  // criadas. Elas nascem sem Etapa, e sem Etapa somem de TODAS as telas (o inbox
+  // do PM lista Features, a tela do Dev lê 🚧 Desenvolvimento, a fila do TL lê
+  // ✅ Ready). Vinte e sete issues existindo e nenhuma aparecendo, com o Action
+  // verde. `getProjectSnapshot` faz `node(id:)` e é exatamente o que falha
+  // quando o token não alcança o Project da organização.
+  if (strict && project?.id) {
+    try {
+      await getProjectSnapshot(projectToken, project.id);
+    } catch (err) {
+      throw new BoardUnreachableError(
+        `o Project ${project.id} não pôde ser resolvido com o token disponível (${err.message})`
+      );
+    }
+  }
+
   let etapaField = null;
   let statusField = null;
   if (project?.id) {
     try {
       etapaField = await resolveField(projectToken, project, 'Etapa');
     } catch (err) {
+      if (strict) throw new BoardUnreachableError(`campo Etapa não resolvido (${err.message})`);
       console.warn(`Não foi possível resolver campo Etapa do board: ${err.message}`);
     }
     try {
       statusField = await resolveField(projectToken, project, 'Status');
     } catch (err) {
+      if (strict) throw new BoardUnreachableError(`campo Status não resolvido (${err.message})`);
       console.warn(`Não foi possível resolver campo Status do board: ${err.message}`);
     }
   }