@spec-wave/cli 0.30.0 → 0.33.0

package/src/lib/qa-report.mjs

@@ -7,7 +7,7 @@
 // (`v1` → `v2`).
 
 import { createHash } from 'node:crypto';
-import { REQUIRED_BUG_SECTIONS } from '../config.mjs';
+import { REQUIRED_BUG_SECTIONS, QA_BLOCKED_REASONS } from '../config.mjs';
 
 export const QA_REPORT_VERSION = 1;
 
@@ -74,11 +74,21 @@ export function aggregateVerdict(results = []) {
  *
  * O executor (o agente acionado por `qa.command`) grava um JSON com o veredito
  * de cada cenário. Fora do contrato → erro nomeando o campo: um resultado
- * ilegível não pode virar aprovação nem reprovação.
+ * ilegível não pode virar aprovação nem reprovação (D-QAL5 — falha alta, nunca
+ * inferência).
+ *
+ * O contrato é o formato ADOTADO da implementação original (`cenario` /
+ * `evidencia` — ver `protocol/qa-result.v1.json`), estendido pela
+ * rfc/spec-qa-lead.md:
+ *  • `blocked` exige `blockedReason` do enum fechado (D-QAL6) — o agregado por
+ *    motivo do relatório de trilha depende dele;
+ *  • `fail` exige `evidencia` não vazia — sem evidência não há bug.md
+ *    determinístico;
+ *  • `blockedReason: outro` exige `evidencia` não vazia (é o texto livre).
  *
  * @param {*} payload objeto lido do arquivo de resultados
  * @param {number[]} expected números dos cenários que DEVIAM ter sido executados
- * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string}>}
+ * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string, blockedReason:string|null}>}
  */
 export function validateQaResults(payload, expected = []) {
   if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.scenarios)) {
@@ -98,10 +108,30 @@ export function validateQaResults(payload, expected = []) {
         `(aceitos, exatamente: ${QA_VERDICTS.join(' | ')}).`
       );
     }
+    const evidencia = String(item?.evidencia ?? '').trim();
+    const blockedReason = item?.blockedReason == null ? null : String(item.blockedReason).trim();
+    if (verdict === 'blocked') {
+      if (!blockedReason || !QA_BLOCKED_REASONS.includes(blockedReason)) {
+        throw new Error(
+          `${at}: verdict "blocked" exige blockedReason do enum ` +
+          `(${QA_BLOCKED_REASONS.join(' | ')}), veio ${JSON.stringify(item?.blockedReason)}.`
+        );
+      }
+      if (blockedReason === 'outro' && !evidencia) {
+        throw new Error(`${at}: blockedReason "outro" exige evidencia com o motivo em texto livre.`);
+      }
+    }
+    if (verdict === 'fail' && !evidencia) {
+      throw new Error(
+        `${at}: verdict "fail" sem evidencia — sem a evidência bruta não há bug.md ` +
+        'determinístico, e reprovação sem registro não abre Bug.'
+      );
+    }
     out.set(numero, {
       numero,
       verdict,
-      evidencia: String(item?.evidencia ?? '').trim(),
+      evidencia,
+      blockedReason: verdict === 'blocked' ? blockedReason : null,
     });
   });
   const missing = expected.filter(n => !out.has(n));
@@ -111,6 +141,13 @@ export function validateQaResults(payload, expected = []) {
       'ser executado deve vir como "blocked", nunca ser omitido.'
     );
   }
+  const extra = [...out.keys()].filter(n => !expected.includes(n));
+  if (extra.length > 0) {
+    throw new Error(
+      `veredito para cenário(s) fora do alvo: ${extra.join(', ')} — o escopo desta corrida é ` +
+      `${expected.join(', ') || '(vazio)'}. Resultado sobrando indica plano trocado ou corrida velha.`
+    );
+  }
   return expected.map(n => out.get(n));
 }
 
@@ -139,7 +176,10 @@ export function combineWithPrevious({ executed = [], previous = new Map(), allNu
     }
     const prev = previous.get(n);
     if (prev) {
-      combined.push({ numero: n, verdict: prev.verdict, evidencia: prev.evidencia || '(corrida anterior)', carried: true });
+      combined.push({
+        numero: n, verdict: prev.verdict, evidencia: prev.evidencia || '(corrida anterior)',
+        blockedReason: prev.blockedReason || null, carried: true,
+      });
     } else {
       pendingNumbers.push(n);
     }
@@ -162,6 +202,7 @@ export function parseLastQaReport(comments = []) {
   let run = 0;
   let verdict = null;
   let results = new Map();
+  let bugs = [];
   for (const comment of comments) {
     const body = String(comment?.body || '');
     QA_REPORT_MARKER_RE.lastIndex = 0;
@@ -176,11 +217,20 @@ export function parseLastQaReport(comments = []) {
       if (Array.isArray(payload?.scenarios)) {
         results = new Map(payload.scenarios
           .filter(s => Number.isInteger(s?.cenario))
-          .map(s => [s.cenario, { verdict: s.verdict, evidencia: s.evidencia || '' }]));
+          .map(s => [s.cenario, {
+            verdict: s.verdict,
+            evidencia: s.evidencia || '',
+            blockedReason: s.blockedReason || null,
+          }]));
       }
+      // Bugs abertos pela corrida — o `qa-lead` compõe o `bugsOpened` do
+      // relatório de trilha a partir daqui, nunca parseando o markdown.
+      bugs = Array.isArray(payload?.bugs)
+        ? payload.bugs.filter(b => Number.isInteger(b?.number))
+        : [];
     } catch { /* bloco ilegível não vira estado */ }
   }
-  return { run, verdict, results };
+  return { run, verdict, results, bugs };
 }
 
 const VERDICT_ICON = { pass: '✅ pass', fail: '❌ fail', blocked: '⚪ blocked' };
@@ -228,7 +278,8 @@ export function renderQaReport({
   const linhas = ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
   for (const r of results) {
     const carried = r.carried ? ' _(corrida anterior)_' : '';
-    linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict} | ${sanitizeCell(r.evidencia)}${carried} |`);
+    const reason = r.verdict === 'blocked' && r.blockedReason ? ` (${r.blockedReason})` : '';
+    linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict}${reason} | ${sanitizeCell(r.evidencia)}${carried} |`);
   }
   parts.push(linhas.join('\n'));
 
@@ -253,8 +304,13 @@ export function renderQaReport({
       run,
       verdict,
       scenarios: results.map(r => ({
-        cenario: r.numero, verdict: r.verdict, evidencia: sanitizeCell(r.evidencia, 400),
+        cenario: r.numero,
+        verdict: r.verdict,
+        evidencia: sanitizeCell(r.evidencia, 400),
+        ...(r.verdict === 'blocked' && r.blockedReason ? { blockedReason: r.blockedReason } : {}),
       })),
+      // Aditivo ao v1: o `qa-lead` lê daqui os Bugs da corrida.
+      bugs: bugs.map(b => ({ number: b.number, cenario: b.cenario, existing: !!b.existing })),
     }, null, 2),
     '```',
   ].join('\n'));

package/src/lib/skill-compose.mjs

@@ -0,0 +1,234 @@
+// Composição da skill MONOLÍTICA a partir das skills do plugin.
+//
+// A monolítica (`src/templates/skill/SKILL.md`) e as skills por comando
+// (`src/plugin/skills/<cmd>/SKILL.md`) diziam a mesma coisa em dois lugares, e
+// toda mudança era feita duas vezes — o PR do QA editou as duas, e nada
+// impedia as cópias de divergirem. Agora a monolítica é GERADA: o preâmbulo
+// fixo mora em `core.md` (visão de conjunto: fluxo, labels, Regra fundamental,
+// referência da CLI) e as seções de sub-comando saem das skills do plugin, que
+// viram a única fonte de verdade por comando.
+//
+// Mesmo padrão do docs:gen: o arquivo é gerado, COMMITADO, e um teste de
+// paridade (test/skill-compose.test.mjs) regenera em memória e compara com o
+// disco — a divergência vira falha de teste, não descoberta em produção.
+//
+// Dois níveis, e a escolha é deliberada: compor TODAS as 26 skills verbatim
+// dobraria o tamanho do arquivo (que vai inteiro para AGENTS.md e afins).
+// Os SUB-COMANDOS que o roteador despacha entram com o corpo completo; os
+// fluxos de orquestração e utilitários de board entram como lista com a
+// descrição (quem os usa direto tem a skill dedicada do plugin ou o --help).
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { TEMPLATES_DIR } from './templates.mjs';
+import { listPluginSkills } from './plugin-skills.mjs';
+import { parseSkill } from './skill-file.mjs';
+import { fenceScanner } from './decomposition-doc.mjs';
+
+/** Preâmbulo fixo, editado à mão — a única metade autoral da monolítica. */
+export const SKILL_CORE_FILE = path.join(TEMPLATES_DIR, 'skill', 'core.md');
+
+/** Saída gerada — o que o install-skill instala em todos os agentes. */
+export const SKILL_OUTPUT_FILE = path.join(TEMPLATES_DIR, 'skill', 'SKILL.md');
+
+/** Placeholder do core.md substituído pelas seções compostas. */
+export const SUBCOMMANDS_PLACEHOLDER = '{{SUBCOMANDOS}}';
+
+// Aviso de arquivo gerado, logo após o frontmatter. O install-skill insere o
+// banner de versão no mesmo ponto na INSTALAÇÃO — os dois coexistem.
+export const GENERATED_MARKER =
+  '<!-- GERADO por scripts/generate-skill.mjs a partir de core.md + src/plugin/skills/*/SKILL.md.\n' +
+  '     NÃO edite este arquivo à mão: edite o core.md (visão de conjunto) ou a skill do\n' +
+  '     comando no plugin, e rode `npm run skill:gen`. -->';
+
+/**
+ * Sub-comandos com corpo COMPLETO, na ordem do fluxo. São os que o roteador
+ * (`/spec-wave <cmd>`) despacha — o leitor de arquivo único precisa do passo a
+ * passo deles sem ter as skills granulares por perto.
+ */
+export const SKILL_FULL_ORDER = [
+  'info', 'setup', 'update', 'doctor',
+  'issue',
+  'spec', 'plan', 'ready',
+  'decompose', 'implement', 'qa',
+  'bug', 'triage',
+  'rfc', 'fix-pr', 'uninstall',
+];
+
+/**
+ * Skills que entram como LISTA (nome + descrição + ponteiro): fluxos de
+ * orquestração (grandes demais para um arquivo único) e utilitários de board
+ * que a Referência da CLI do core já documenta flag a flag.
+ */
+export const SKILL_SUMMARY_ORDER = [
+  'workflow', 'preparar-feature', 'preparar-specs',
+  'audit', 'order', 'merge', 'run',
+  'qa-lead', 'qa-executor',
+  'task', 'story', 'move',
+];
+
+/**
+ * Reescritas para o contexto de ARQUIVO ÚNICO (função PURA via applyRewrites).
+ *
+ * Uma skill do plugin pode apontar para um arquivo de apoio "ao lado" dela
+ * (ex.: `reference/tech-context.md` da skill plan) — ao lado da monolítica
+ * esse arquivo não existe, mas o conteúdo correspondente existe como seção do
+ * core. Substituição por string EXATA, de propósito: se a frase de origem
+ * mudar, a reescrita vira no-op (o ponteiro fica só impreciso) em vez de
+ * corromper texto parecido.
+ */
+export const SINGLE_FILE_REWRITES = [
+  [
+    'o passo a passo está em `reference/tech-context.md`, ao lado deste arquivo',
+    'o passo a passo está na seção **Tech Context** deste documento',
+  ],
+  [
+    'o passo a passo está na skill **plan** (`reference/tech-context.md`)',
+    'o passo a passo está na seção **Tech Context** deste documento',
+  ],
+];
+
+/** Aplica as reescritas de arquivo único (função PURA). */
+export function applyRewrites(body, rewrites = SINGLE_FILE_REWRITES) {
+  let out = String(body ?? '');
+  for (const [from, to] of rewrites) out = out.split(from).join(to);
+  return out;
+}
+
+/**
+ * Rebaixa os headings de um corpo markdown (função PURA, ciente de fences).
+ *
+ * `## Passos` dentro de uma skill vira `#### Passos` dentro da seção
+ * `### /spec-wave <cmd>` da monolítica. Linhas dentro de blocos de código não
+ * são tocadas (o mesmo rastreador do decomposition.md decide o que é código).
+ *
+ * @param {string} body
+ * @param {number} [by] níveis a rebaixar (teto em ######)
+ * @returns {string}
+ */
+export function demoteHeadings(body, by = 2) {
+  const scan = fenceScanner();
+  return String(body ?? '').split('\n').map((line) => {
+    if (scan.inFence(line)) return line;
+    const m = /^(#{1,6})([ \t].*)$/.exec(line);
+    if (!m) return line;
+    const level = Math.min(6, m[1].length + by);
+    return '#'.repeat(level) + m[2];
+  }).join('\n');
+}
+
+// "spec-wave implement — etapa 🚧 Desenvolvimento" → "etapa 🚧 Desenvolvimento".
+function h1Tail(h1Text, name) {
+  const text = String(h1Text ?? '').trim();
+  const m = new RegExp(`^spec-wave[ \\t]+${name}[ \\t]*(?:[—–:-][ \\t]*(.*))?$`, 'i').exec(text);
+  if (m) return (m[1] || '').trim();
+  return text; // H1 fora do padrão: vira o subtítulo inteiro
+}
+
+// Separa o H1 do restante do corpo (o H1 vira o título da seção composta).
+function splitH1(body) {
+  const lines = String(body ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const scan = fenceScanner();
+  for (let i = 0; i < lines.length; i++) {
+    if (scan.inFence(lines[i])) continue;
+    const m = /^#[ \t]+(.*)$/.exec(lines[i]);
+    if (m) return { h1: m[1].trim(), rest: lines.slice(i + 1).join('\n').trim() };
+    if (lines[i].trim()) break; // primeiro conteúdo não é H1 — não há o que separar
+  }
+  return { h1: null, rest: String(body ?? '').trim() };
+}
+
+/**
+ * Renderiza a seção de UM sub-comando de corpo completo (função PURA).
+ *
+ * @param {{name: string, meta: object, body: string}} skill
+ * @returns {string}
+ */
+export function renderFullSection({ name, meta, body }) {
+  const { h1, rest } = splitH1(body);
+  const tail = h1 ? h1Tail(h1, name) : '';
+  const header = `### \`/spec-wave ${name}\`${tail ? ` — ${tail}` : ''}`;
+  const quando = meta?.description
+    ? `> **Quando usar:** ${String(meta.description).replace(/\s+/g, ' ').trim()}`
+    : '';
+  return [header, quando, applyRewrites(demoteHeadings(rest, 2))].filter(Boolean).join('\n\n');
+}
+
+/**
+ * Renderiza a lista das skills resumidas (função PURA).
+ *
+ * @param {Array<{name: string, meta: object}>} skills na ordem de SKILL_SUMMARY_ORDER
+ * @returns {string}
+ */
+export function renderSummarySection(skills) {
+  const linhas = [
+    '### Outras skills (fluxos e utilitários)',
+    '',
+    'Cada uma existe como skill dedicada do plugin (`/spec-wave:<nome>`) — e os',
+    'utilitários de board estão flag a flag na *Referência da CLI* acima. Rode',
+    '`npx @spec-wave/cli@latest <comando> --help` para os parâmetros.',
+    '',
+  ];
+  for (const { name, meta } of skills) {
+    const desc = String(meta?.description || '').replace(/\s+/g, ' ').trim();
+    linhas.push(`- **\`${name}\`** — ${desc}`);
+  }
+  return linhas.join('\n');
+}
+
+/**
+ * Compõe a monolítica inteira (função PURA — testável sem fs).
+ *
+ * @param {object} params
+ * @param {string} params.core conteúdo do core.md (com o placeholder)
+ * @param {Map<string, {meta: object, body: string}>} params.skills por nome de diretório
+ * @returns {string} SKILL.md final
+ */
+export function renderMonolithicSkill({ core, skills }) {
+  const raw = String(core ?? '');
+  if (!raw.includes(SUBCOMMANDS_PLACEHOLDER)) {
+    throw new Error(`core.md não contém o placeholder ${SUBCOMMANDS_PLACEHOLDER}.`);
+  }
+
+  const faltando = [...SKILL_FULL_ORDER, ...SKILL_SUMMARY_ORDER].filter(n => !skills.has(n));
+  if (faltando.length > 0) {
+    throw new Error(`skill(s) declaradas na ordem mas ausentes do plugin: ${faltando.join(', ')}.`);
+  }
+
+  const cheias = SKILL_FULL_ORDER
+    .map(name => renderFullSection({ name, ...skills.get(name) }))
+    .join('\n\n---\n\n');
+  const resumidas = renderSummarySection(
+    SKILL_SUMMARY_ORDER.map(name => ({ name, meta: skills.get(name).meta })),
+  );
+  const sections = `${cheias}\n\n---\n\n${resumidas}`;
+
+  let out = raw.replace(SUBCOMMANDS_PLACEHOLDER, sections);
+
+  // Marcador de "gerado" logo após o frontmatter — quem abrir o arquivo para
+  // editar precisa ser mandado de volta para a fonte antes da primeira linha útil.
+  const fm = /^---\n[\s\S]*?\n---\n/.exec(out);
+  if (!fm) throw new Error('core.md sem frontmatter YAML — a monolítica precisa dele.');
+  out = `${fm[0]}\n${GENERATED_MARKER}\n${out.slice(fm[0].length)}`;
+
+  return out.endsWith('\n') ? out : `${out}\n`;
+}
+
+/**
+ * Lê as fontes do disco e compõe (I/O). É o que o gerador e o teste de
+ * paridade chamam — os dois produzem exatamente o mesmo texto.
+ *
+ * @returns {{ content: string, skillNames: string[] }}
+ */
+export function composeMonolithicSkill() {
+  const core = readFileSync(SKILL_CORE_FILE, 'utf-8');
+  const skills = new Map();
+  const skillNames = [];
+  for (const skill of listPluginSkills()) {
+    const { meta, body } = parseSkill(readFileSync(path.join(skill.dir, 'SKILL.md'), 'utf-8'));
+    skills.set(skill.name, { meta, body });
+    skillNames.push(skill.name);
+  }
+  return { content: renderMonolithicSkill({ core, skills }), skillNames };
+}

package/src/lib/story-graph.mjs

@@ -0,0 +1,256 @@
+// Carregamento do grafo de Stories e do snapshot do board — a CÓPIA ÚNICA do
+// laço que order/implement/merge/qa-lead mantinham cada um por si (e que
+// custava 1..3 chamadas POR STORY em cada comando).
+//
+// Fontes das ARESTAS, da mais barata para a mais cara:
+//  1. `docs/features/<slug>/dependency-map.json` — artefato COMMITADO, escrito
+//     pelo decompose --apply e atualizado pelo `order --sync`;
+//  2. `decomposition.md` aplicado (mesma informação, formato de prosa);
+//  3. linhas "Depende de: #N" do corpo das sub-issues — que o listSubIssues já
+//     devolve DE GRAÇA (zero chamada extra);
+//  4. `remote: true` → blocked_by nativo via API, 1 chamada por Story (cache
+//     `blockedby-*` com TTL). É a única fonte que enxerga aresta criada SÓ
+//     pela UI — por isso o merge --yes a exige fresca.
+// 1–3 são sempre UNIDAS (são grátis); a origem informada ao usuário diz o que
+// entrou.
+//
+// Etapa/estado vêm do snapshot (`listProjectItems`, 1 chamada paginada),
+// cacheado com TTL — NUNCA do par addProjectItem+getItemSingleSelectValue, que
+// além de custar 2 chamadas por item é MUTAÇÃO em caminho de leitura.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { listSubIssues, listProjectItems } from '../api/github-graphql.mjs';
+import { listBlockedBy, getIssue } from '../api/github-rest.mjs';
+import { detectIssueType } from './issue-type.mjs';
+import { featureDocPaths } from './doc-paths.mjs';
+import { parseDecompositionDoc } from './decomposition-doc.mjs';
+import { parseDependencies } from './dependencies.mjs';
+import { indexBoardItems } from './board.mjs';
+import {
+  parseDependencyMap, storiesFromAppliedDoc, mergeDependencyEdges, isFresh,
+  DEPENDENCY_MAP_FILE,
+} from './dependency-map.mjs';
+import {
+  readCacheEntry, writeCacheEntry, DEFAULT_CACHE_TTL_SEC,
+} from './net-cache.mjs';
+
+/**
+ * Stories de uma Feature com as arestas resolvidas — fonte híbrida.
+ *
+ * @param {object} params
+ * @param {string} params.token
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.root raiz do projeto (docs/ e cache moram nela)
+ * @param {{number:number, nodeId?:string, node_id?:string, title:string}} params.feature
+ * @param {boolean} [params.remote] une também o blocked_by da API (S chamadas)
+ * @param {boolean} [params.refresh] ignora TODO cache na leitura (mas grava)
+ * @param {number} [params.ttlSec]
+ * @returns {Promise<{
+ *   stories: Array<{number, title, nodeId, body, state, stateReason, createdAt,
+ *                   milestone, labels, dependsOn:number[]}>,
+ *   allSubs: Array<object>,
+ *   origin: { edges: string, mapGeneratedAt: string|null, subsFrom: 'cache'|'api',
+ *             fetchedAt: string|null },
+ *   warnings: string[],
+ * }>}
+ */
+export async function loadFeatureStories({
+  token, owner, repo, root, feature, remote = false, refresh = false,
+  ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const warnings = [];
+  const nodeId = feature.nodeId || feature.node_id;
+
+  // ── sub-issues (com body!) — cache subissues-<n> ───────────────────────────
+  const subsKey = `subissues-${feature.number}`;
+  const cached = refresh ? null : readCacheEntry(root, subsKey, { owner, repo });
+  let allSubs;
+  let subsFrom;
+  let fetchedAt;
+  if (cached && isFresh(cached, ttlSec)) {
+    allSubs = cached.data;
+    subsFrom = 'cache';
+    fetchedAt = cached.fetchedAt;
+  } else {
+    allSubs = await listSubIssues(token, nodeId);
+    subsFrom = 'api';
+    fetchedAt = new Date().toISOString();
+    writeCacheEntry(root, subsKey, 'sub-issues', allSubs, { owner, repo });
+  }
+  const storySubs = allSubs
+    .filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+
+  // ── fontes de aresta locais (grátis — sempre unidas) ───────────────────────
+  const sources = [];
+  const parts = [];
+  let mapGeneratedAt = null;
+
+  const paths = root ? safeDocPaths(root, feature.title) : null;
+  if (paths) {
+    const mapAbs = path.join(root, paths['dependency-map'].rel);
+    if (existsSync(mapAbs)) {
+      try {
+        const parsed = parseDependencyMap(JSON.parse(readFileSync(mapAbs, 'utf-8')));
+        if (parsed.ok) {
+          sources.push(parsed.map.stories);
+          parts.push('map');
+          mapGeneratedAt = parsed.map.generatedAt || null;
+        } else {
+          warnings.push(`${DEPENDENCY_MAP_FILE} ignorado: ${parsed.reason} — regenere com \`order ${feature.number} --sync\`.`);
+        }
+      } catch {
+        warnings.push(`${DEPENDENCY_MAP_FILE} ilegível — regenere com \`order ${feature.number} --sync\`.`);
+      }
+    }
+    if (parts.length === 0) {
+      const docAbs = path.join(root, paths.decomposition.rel);
+      if (existsSync(docAbs)) {
+        try {
+          const converted = storiesFromAppliedDoc(parseDecompositionDoc(readFileSync(docAbs, 'utf-8')));
+          if (converted.ok) {
+            sources.push(converted.stories);
+            parts.push('doc');
+          }
+        } catch { /* doc ilegível → segue com o body */ }
+      }
+    }
+  }
+
+  // Body: as linhas "Depende de: #N" que o apply gravou (ou o humano editou).
+  sources.push(storySubs.map(s => ({ number: s.number, dependsOn: parseDependencies(s.body) })));
+  parts.push('body');
+
+  // ── blocked_by remoto (opcional — a única fonte com aresta só-da-UI) ───────
+  if (remote) {
+    const remoteEdges = [];
+    for (const s of storySubs) {
+      const key = `blockedby-${s.number}`;
+      const hit = refresh ? null : readCacheEntry(root, key, { owner, repo });
+      if (hit && isFresh(hit, ttlSec)) {
+        remoteEdges.push({ number: s.number, dependsOn: hit.data });
+        continue;
+      }
+      try {
+        const deps = (await listBlockedBy(token, owner, repo, s.number)).map(b => b.number);
+        remoteEdges.push({ number: s.number, dependsOn: deps });
+        writeCacheEntry(root, key, 'blocked-by', deps, { owner, repo });
+      } catch (err) {
+        // Falha de rede NÃO entra no cache e não derruba: as fontes locais
+        // seguem valendo — mas o usuário precisa saber que o remoto ficou fora.
+        warnings.push(`blocked_by de #${s.number} não consultável agora (${err.message}).`);
+      }
+    }
+    sources.push(remoteEdges);
+    parts.push('remote');
+  }
+
+  const edges = mergeDependencyEdges(...sources);
+  return {
+    stories: storySubs.map(s => ({ ...s, dependsOn: edges.get(s.number) || [] })),
+    allSubs,
+    origin: { edges: parts.join('+'), mapGeneratedAt, subsFrom, fetchedAt },
+    warnings,
+  };
+}
+
+/**
+ * Sub-issues de um item, com cache `subissues-<n>` (TTL).
+ *
+ * Para quem precisa dos filhos CRUS (ex.: as Tasks de uma Story no implement)
+ * sem o resto do grafo.
+ *
+ * @returns {Promise<{subs:Array, fromCache:boolean, fetchedAt:string}>}
+ */
+export async function cachedSubIssues({
+  token, owner, repo, root, parent, refresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const key = `subissues-${parent.number}`;
+  if (!refresh) {
+    const hit = readCacheEntry(root, key, { owner, repo });
+    if (hit && isFresh(hit, ttlSec)) return { subs: hit.data, fromCache: true, fetchedAt: hit.fetchedAt };
+  }
+  const subs = await listSubIssues(token, parent.nodeId || parent.node_id);
+  writeCacheEntry(root, key, 'sub-issues', subs, { owner, repo });
+  return { subs, fromCache: false, fetchedAt: new Date().toISOString() };
+}
+
+// featureDocPaths lança para título vazio/eslug inválido — aqui vira "sem docs".
+function safeDocPaths(root, title) {
+  try {
+    return featureDocPaths(root, { title }, 'Feature');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Snapshot do board (Etapa/estado/milestone de todos os itens) — 1 chamada
+ * paginada, cacheada com TTL.
+ *
+ * `fresh: true` = caminho de DECISÃO QUE ESCREVE (gates do implement, escopo do
+ * qa-lead run): ignora o cache na leitura, mas grava — o comando seguinte da
+ * sessão ganha o snapshot de graça.
+ *
+ * @param {object} params
+ * @param {string} params.token
+ * @param {{id:string}} params.project
+ * @param {string} params.root
+ * @param {boolean} [params.refresh] força reconsulta (flag do usuário)
+ * @param {boolean} [params.fresh] exige dado novo (decisão de escrita)
+ * @param {number} [params.ttlSec]
+ * @returns {Promise<{items:Array, index:Map<number,object>, fetchedAt:string, fromCache:boolean}>}
+ */
+export async function loadBoardSnapshot({
+  token, project, root, refresh = false, fresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const key = 'board-items';
+  if (!refresh && !fresh) {
+    const hit = readCacheEntry(root, key, { projectId: project.id });
+    if (hit && isFresh(hit, ttlSec)) {
+      return {
+        items: hit.data,
+        index: indexBoardItems(hit.data),
+        fetchedAt: hit.fetchedAt,
+        fromCache: true,
+      };
+    }
+  }
+  const items = await listProjectItems(token, project.id);
+  writeCacheEntry(root, key, 'board-items', items, { projectId: project.id });
+  return {
+    items,
+    index: indexBoardItems(items),
+    fetchedAt: new Date().toISOString(),
+    fromCache: false,
+  };
+}
+
+/**
+ * Estado (aberta/fechada, título) de uma issue externa — cache `issue-<n>`.
+ *
+ * Só para EXIBIÇÃO (a lista "Bloqueadas por fora" do order); decisão de escrita
+ * nunca passa por aqui.
+ *
+ * @returns {Promise<{title:string, state:string|null, aberta:boolean, fromCache:boolean}>}
+ */
+export async function externalIssueInfo({
+  token, owner, repo, root, number, refresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const key = `issue-${number}`;
+  if (!refresh) {
+    const hit = readCacheEntry(root, key, { owner, repo });
+    if (hit && isFresh(hit, ttlSec)) return { ...hit.data, fromCache: true };
+  }
+  const issue = await getIssue(token, owner, repo, number).catch(() => null);
+  if (!issue) {
+    // Falha não entra no cache: "não foi possível ler" com cara de fresco por
+    // 10 minutos esconderia uma issue que voltou a ser legível.
+    return { title: '(não foi possível ler)', state: null, aberta: true, fromCache: false };
+  }
+  const data = { title: issue.title, state: issue.state, aberta: issue.state === 'open' };
+  writeCacheEntry(root, key, 'issue', data, { owner, repo });
+  return { ...data, fromCache: false };
+}

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

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

package/src/plugin/skills/merge/SKILL.md

@@ -22,6 +22,7 @@ O `implement` empilha os PRs de propósito (cada Story revisável sozinha, diff
 ## O que saber antes de rodar
 
 - **Sem `--yes` nada é mergeado** — a saída é o plano: a fila na ordem, qual base será reapontada, o que já está mergeado.
+- O **plano** calcula a ordem pelas fontes locais (dependency-map.json/decomposition.md/corpo — barato); a **execução com `--yes` reconsulta tudo FRESCO da API**, incluindo o blocked_by nativo: merge de pilha é irreversível e não decide com cache.
 - **PR em rascunho bloqueia o plano inteiro.** Marcar pronto é a revisão humana (e o que dispara o CI) — revise e marque cada PR como pronto antes. O comando não faz isso por você, de propósito.
 - **Rodar de novo retoma.** PR mergeado sai do plano sozinho; uma falha no meio (check pendente, conflito) para a fila com as branches dos dependentes intactas.
 - Story **sem PR** vira aviso, não bloqueio — mas se um PR da fila depende do código dela, o merge leva esse código junto; confira antes de confirmar.