@spec-wave/cli 0.19.0 → 0.20.0

package/package.json

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

@@ -31,7 +31,7 @@ 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';
@@ -633,10 +633,57 @@ async function createStoriesFromDoc(ctx, doc) {
     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) {
   const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, docRel } = ctx;
   const parentNodeId = issue.node_id;

package/src/lib/dependencies.mjs

@@ -90,3 +90,52 @@ export function orderStories(stories) {
     .sort((a, b) => a - b);
   return { order, cycle };
 }
+
+/**
+ * Comentário com a ordem de execução das Stories (função PURA).
+ *
+ * A decomposição já comentava a lista das Stories criadas, mas na ordem de
+ * criação e sem dizer o que depende de quê — para saber por onde começar, o dev
+ * tinha de rodar `spec-wave order` no terminal. A informação existia fora da
+ * issue, que é onde o time olha.
+ *
+ * Sobre a expectativa: como `normalizeDependsOn` só aceita dependências para
+ * trás, a ordem de criação já é topologicamente válida e `orderStories` devolve
+ * a mesma sequência. O ganho aqui não é reordenar — é tornar a cadeia visível,
+ * com os números clicáveis. Passar por `orderStories` mesmo assim mantém uma só
+ * definição de "ordem de execução" (a que o comando `order` usa) e dá a
+ * detecção de ciclo de graça.
+ *
+ * @param {object} params
+ * @param {number[]} params.sorted números das Stories em ordem topológica
+ * @param {number[]} [params.cycle] Stories que ficaram fora da ordem (ciclo)
+ * @param {Map<number,{title: string, dependsOn: number[]}>} params.byNumber
+ * @returns {string} markdown
+ */
+export function renderOrderComment({ sorted, cycle = [], byNumber }) {
+  const linha = (n, i) => {
+    const s = byNumber.get(n);
+    const deps = s?.dependsOn?.length > 0
+      ? ` — depende de ${s.dependsOn.map(d => `#${d}`).join(', ')}`
+      : '';
+    return `${i + 1}. #${n} ${s?.title ?? ''}${deps}`.trimEnd();
+  };
+
+  const partes = [
+    '📋 **Ordem de execução das Stories**',
+    sorted.map(linha).join('\n'),
+  ];
+
+  // Espelha o aviso que o comando `order` dá no terminal. Estruturalmente o
+  // parser impede ciclo (dependência só para trás), mas se a validação relaxar,
+  // silenciar aqui esconderia Stories do comentário — e ninguém perceberia.
+  if (cycle.length > 0) {
+    partes.push(
+      `⚠️ **Ciclo de dependências:** ${cycle.map(n => `#${n}`).join(', ')} ` +
+      'ficaram FORA da ordem acima. Corrija as linhas "Depende de" (ou as relações ' +
+      'blocked_by) dessas issues.'
+    );
+  }
+
+  return partes.join('\n\n');
+}

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

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.19.0",
+  "version": "0.20.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",