@spec-wave/cli 0.18.1 → 0.20.0

package/bin/spec-wave.mjs

@@ -11,7 +11,19 @@ const pkg = JSON.parse(readFileSync(path.join(__dir, '..', 'package.json'), 'utf
 program
   .name('spec-wave')
   .description('Setup spec-driven GitHub workflow with Projects v2')
-  .version(pkg.version);
+  .version(pkg.version)
+  // Conta do `gh` a usar nesta execução. Existe porque um GH_TOKEN exportado no
+  // shell (um `.envrc` na raiz de um diretório de projetos, por exemplo) vale
+  // para repositórios de QUALQUER org abaixo dele — e o GraphQL do GitHub
+  // mascara o 403 resultante como "Could not resolve to a Repository".
+  .option('--account <login>', 'Conta do gh a usar (vence GITHUB_TOKEN/GH_TOKEN fora do CI)')
+  .hook('preAction', async (thisCommand) => {
+    const { account } = thisCommand.opts();
+    if (account) {
+      const { setAccountOverride } = await import('../src/api/auth.mjs');
+      setAccountOverride(account);
+    }
+  });
 
 program
   .command('init')
@@ -172,8 +184,11 @@ program
 
 program
   .command('critique')
-  .description('Re-critica o plan.md COMO ESTÁ, sem regerar — para depois de corrigi-lo à mão')
-  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .description('Critica um documento COMO ESTÁ, sem regerar — para depois de corrigi-lo à mão')
+  .option('--issue-number <n>', 'Número da issue: critica o plan.md dela e comenta (fluxo canônico)')
+  .option('--file <caminho>', 'Critica ESTE arquivo e imprime o resultado — sem issue, sem label, sem contar tentativa')
+  .option('--kind <tipo>', 'plan | spec | stories | bug (default: inferido do nome do arquivo)')
+  .option('--fail-on-grave', 'Sai com código 1 se houver finding grave (útil em script)')
   .action(async (options) => {
     const { critique } = await import('../src/commands/generate-plan.mjs');
     await critique(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -220,6 +235,7 @@ program
   .command('code-review')
   .description('Move Feature para Code Review ao abrir um PR (usado pelo GitHub Action)')
   .requiredOption('--pr-number <n>', 'Número do Pull Request')
+  .option('--resolve-only', 'Só descobre a Feature-alvo e imprime feature=<n>, sem tocar no board')
   .action(async (options) => {
     const { codeReview } = await import('../src/commands/code-review.mjs');
     await codeReview(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -276,6 +292,21 @@ program
       .catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('repair-stage')
+  .description('Corrige a Etapa de itens que a automação errou — inclusive retrocedendo. Exige --yes e --reason, e registra o reparo na issue')
+  .argument('<issues>', 'Número(s) da(s) issue(s), ex.: 529 ou 529,530,531')
+  .argument('<etapa>', 'Etapa correta, com ou sem emoji, ex.: "ready", "✅ Ready"')
+  .option('--reason <motivo>', 'Por que o reparo é necessário (vai para o comentário de auditoria)')
+  .option('--status <valor>', 'Também corrige o Status: Todo, In Progress ou Done (default: não mexe)')
+  .option('--yes', 'Confirma o reparo (obrigatório)')
+  .option('--dry-run', 'Mostra o que seria reparado sem alterar nada')
+  .action(async (issues, etapa, options) => {
+    const { repairStage } = await import('../src/commands/repair-stage.mjs');
+    await repairStage(issues, etapa, options)
+      .catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('story')
   .description('Gerencia uma Story no board: review (move para Code Review)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.18.1",
+  "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/agent/anthropic-agent.mjs

@@ -25,6 +25,7 @@
 import path from 'node:path';
 import { withTrace, startObservation, updateSpan, endObservation } from './tracing.mjs';
 import { ENV_FILE_PATTERN } from './tools.mjs';
+import { summarizeToolCalls } from './errors.mjs';
 import { TruncatedOutputError } from './errors.mjs';
 
 const DEFAULT_TOOLS = ['Read', 'Glob', 'Grep'];
@@ -68,6 +69,9 @@ export async function runAnthropicAgent(prompt, options) {
     numTurns: 0,
     structured: null,
     usage: { inputTokens: 0, outputTokens: 0 },
+    // Simétrico ao backend openrouter: sem isto, um run que estoura o teto de
+    // turnos não deixa registro do que o modelo esteve fazendo.
+    toolCalls: [],
   };
   const quiet = options.quiet !== false;
 
@@ -154,6 +158,7 @@ export async function runAnthropicAgent(prompt, options) {
                 };
               }
 
+              runResult.toolCalls.push(input.tool_name);
               if (options.verbose) {
                 console.log(`\n[Tool] ${input.tool_name}(${JSON.stringify(input.tool_input)})`);
               }
@@ -288,7 +293,10 @@ export async function runAnthropicAgent(prompt, options) {
               }
             } else {
               output = `[${message.subtype}]`;
-              console.warn(`\n[Agent] Run ended without success: ${message.subtype}`);
+              console.warn(
+                `\n[Agent] Run ended without success: ${message.subtype} — ` +
+                `ferramentas chamadas: ${summarizeToolCalls(runResult.toolCalls) || 'nenhuma'}`
+              );
             }
             updateSpan(span, {
               output,
@@ -328,6 +336,7 @@ export async function runAnthropicAgent(prompt, options) {
           maxTokens: options.maxTokens ?? null,
           reason: lastStopReason,
           chars: runResult.outputText.length,
+          action: options.action ?? null,
         });
       }
     },

package/src/agent/errors.mjs

@@ -19,15 +19,69 @@ export function isTruncationReason(reason) {
 // custo. Por isso NÃO é marcado como transitório: o erro sobe, o Action falha
 // visível, destrava a label e comenta na issue o que ajustar.
 export class TruncatedOutputError extends Error {
-  constructor({ provider, model, maxTokens, reason, chars }) {
+  constructor({ provider, model, maxTokens, reason, chars, action }) {
+    // O remédio depende da AÇÃO: dizer "aumente ai.maxTokens" a quem viu a
+    // crítica cortar manda mexer no teto errado se houver
+    // `maxTokensByAction.critique` configurado — e é o teto por ação que está
+    // apertando. Nomear a chave exata poupa uma rodada de tentativa e erro.
+    const knob = action
+      ? `\`ai.maxTokensByAction.${action}\` (ou \`ai.maxTokens\`)`
+      : '`ai.maxTokens` (ou `ai.maxTokensByAction`)';
+    const extra = action === 'critique'
+      ? ' Em modelo que raciocina por padrão, o raciocínio consome o teto antes de a resposta sair — ' +
+        'a crítica não conclui e a rodada se perde.'
+      : '';
     super(
       `Saída truncada pelo teto de tokens (${provider} · ${model} · max_tokens=${maxTokens} · ` +
-      `motivo=${reason}). Foram gerados ~${chars} caracteres antes do corte. ` +
-      'Aumente `ai.maxTokens` (ou `ai.maxTokensByAction`) no .spec-wave.json, ou reduza o ' +
+      `motivo=${reason}${action ? ` · ação=${action}` : ''}). ` +
+      `Foram gerados ~${chars} caracteres antes do corte.${extra} ` +
+      `Aumente ${knob} no .spec-wave.json, ou reduza o ` +
       'tamanho da issue de origem. O documento NÃO foi gravado — um documento cortado ' +
       'passaria na validação de seções e valeria menos que nenhum.'
     );
     this.name = 'TruncatedOutputError';
     this.truncated = true;
+    this.action = action || null;
   }
 }
+
+// Teto de turnos esgotado: o modelo respondeu com tool calls em TODOS os turnos
+// e nunca produziu o documento. Como o truncamento acima, NÃO é transitório —
+// repetir a mesma requisição dá a mesma perambulação, só que mais cara.
+//
+// Marcá-lo como transitório custou 55 minutos de Action num caso real: três
+// tentativas de 25 turnos (4min → 19min → 32min) para a mesma falha
+// determinística, que devia ter aparecido na primeira.
+export class MaxTurnsError extends Error {
+  constructor({ provider, model, turns, action, toolCalls = [] }) {
+    // O que o modelo ficou fazendo é a informação que decide o remédio: muitas
+    // leituras distintas sugerem teto baixo; a mesma chamada repetida é loop
+    // degenerado, e aí subir o teto só encarece.
+    const resumo = toolCalls.length > 0
+      ? ` Ferramentas mais chamadas: ${summarizeToolCalls(toolCalls)}.`
+      : '';
+    super(
+      `O modelo esgotou o teto de ${turns} turnos sem produzir o documento ` +
+      `(${provider} · ${model}${action ? ` · ação=${action}` : ''}): respondeu com chamadas de ` +
+      `ferramenta em todos eles.${resumo} ` +
+      'Repetir não ajuda — o erro é determinístico. Ou o modelo não fecha o loop de ' +
+      'ferramentas nesta tarefa (troque-o, por `ai.models` ou pela label ' +
+      '`spec-wave:model:<apelido>`), ou a exploração precisa de mais turnos.'
+    );
+    this.name = 'MaxTurnsError';
+    this.maxTurns = true;
+    this.turns = turns;
+    this.action = action || null;
+    this.toolCalls = toolCalls;
+  }
+}
+
+/** Contagem por nome de ferramenta, da mais chamada para a menos (função PURA). */
+export function summarizeToolCalls(toolCalls) {
+  const counts = new Map();
+  for (const name of toolCalls) counts.set(name, (counts.get(name) || 0) + 1);
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([name, n]) => `${name}×${n}`)
+    .join(', ');
+}

package/src/agent/openrouter-agent.mjs

@@ -22,7 +22,7 @@ import {
   toolDefinitionsFor,
 } from './tools.mjs';
 import { withTrace, startObservation, updateSpan, endObservation } from './tracing.mjs';
-import { TruncatedOutputError, isTruncationReason } from './errors.mjs';
+import { TruncatedOutputError, isTruncationReason, summarizeToolCalls } from './errors.mjs';
 
 const DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
 const DEFAULT_TOOLS = ['Read', 'Glob', 'Grep'];
@@ -179,6 +179,11 @@ export async function runOpenRouterAgent(prompt, options) {
     numTurns: 0,
     structured: null,
     usage: { inputTokens: 0, outputTokens: 0 },
+    // Nomes das ferramentas chamadas, na ordem. Só o `verbose` imprimia as tool
+    // calls, e ele fica DESLIGADO no Action — quando um modelo queimou os 25
+    // turnos sem escrever nada, o log não dizia no que ele se perdeu, e o
+    // diagnóstico exigiu reconstruir o run à mão.
+    toolCalls: [],
   };
   const quiet = options.quiet !== false;
 
@@ -279,6 +284,7 @@ export async function runOpenRouterAgent(prompt, options) {
               // corte, que é o que distingue teto nosso de teto do provider.
               reason: `${choice.finish_reason}${choice.native_finish_reason ? `/${choice.native_finish_reason}` : ''}`,
               chars: (runResult.outputText + text).length,
+              action: options.action ?? null,
             });
           }
 
@@ -326,6 +332,7 @@ export async function runOpenRouterAgent(prompt, options) {
               parseError = `Could not parse tool arguments as JSON: ${errorMessage(err)}`;
             }
 
+            runResult.toolCalls.push(call.function.name);
             if (options.verbose) console.log(`\n[Tool] ${call.function.name}(${call.function.arguments})`);
 
             const observation = startObservation(
@@ -351,7 +358,10 @@ export async function runOpenRouterAgent(prompt, options) {
 
         if (runResult.resultSubtype === null) {
           runResult.resultSubtype = 'error_max_turns';
-          console.warn(`\n[Agent] Run ended without success: error_max_turns (${maxTurns} turns)`);
+          console.warn(
+            `\n[Agent] Run ended without success: error_max_turns (${maxTurns} turns) — ` +
+            `ferramentas chamadas: ${summarizeToolCalls(runResult.toolCalls) || 'nenhuma'}`
+          );
         }
 
         updateSpan(span, {

package/src/api/auth.mjs

@@ -1,22 +1,230 @@
+// Resolução do token do GitHub.
+//
+// A precedência é env-first porque o CI depende disso: no GitHub Actions o
+// `GITHUB_TOKEN` é injetado e não existe `gh` para consultar. Mas fora do CI a
+// mesma regra já causou estrago: um `export GH_TOKEN=$(gh auth token -u fulano)`
+// num `.envrc` vale para TODOS os repositórios abaixo daquele diretório,
+// inclusive os de outra org. O token responde no REST (ele existe e tem escopo
+// `repo`), e o GraphQL devolve "Could not resolve to a Repository" — que é como
+// o GitHub mascara 403. O diagnóstico fica caríssimo para o sintoma.
+//
+// A saída não é inverter a precedência (quebraria o CI), e sim deixar a conta
+// ser DECLARADA: `--account`, `SPEC_WAVE_GH_ACCOUNT` ou `github.account` no
+// .spec-wave.json. Havendo conta declarada, ela vence o env fora do CI — o
+// repositório passa a dizer de quem é a conta, em vez de depender do ambiente.
 import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { findConfigPath } from '../lib/project-root.mjs';
 
-export async function resolveToken() {
-  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
-  if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
+// Conta escolhida via `spec-wave --account <login>`. O bin grava aqui antes de
+// despachar o comando; passar por parâmetro exigiria mudar toda a cadeia de
+// chamadas por um caso que é global à execução.
+let accountOverride = null;
+
+/** Define a conta do `gh` a usar nesta execução (flag global `--account`). */
+export function setAccountOverride(login) {
+  accountOverride = typeof login === 'string' && login.trim() ? login.trim() : null;
+}
+
+function gh(args) {
+  return execSync(`gh ${args}`, { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+}
+
+// Conta declarada, na ordem: flag → env → .spec-wave.json.
+function declaredAccount(cwd = process.cwd()) {
+  if (accountOverride) return { login: accountOverride, source: '--account' };
+  const fromEnv = (process.env.SPEC_WAVE_GH_ACCOUNT || '').trim();
+  if (fromEnv) return { login: fromEnv, source: 'SPEC_WAVE_GH_ACCOUNT' };
+  try {
+    const configPath = findConfigPath(cwd);
+    if (configPath) {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+      const login = (cfg?.github?.account || '').trim();
+      if (login) return { login, source: 'github.account' };
+    }
+  } catch {
+    // config ausente ou ilegível — segue sem conta declarada
+  }
+  return null;
+}
+
+/**
+ * Conta ativa do `gh` (função quase pura — só lê `gh auth status`).
+ *
+ * @returns {string|null} login, ou null se o gh não estiver disponível/logado
+ */
+export function activeGhAccount() {
+  try {
+    return parseActiveAccount(gh('auth status'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Conta ativa a partir da saída de `gh auth status` (função PURA).
+ *
+ * Formato: "✓ Logged in to github.com account <login> (...)" seguido de
+ * "- Active account: true". Com VÁRIAS contas, a primeira listada não é
+ * necessariamente a ativa — pegar a primeira é o erro que faria este módulo
+ * avisar sobre a conta errada, que é pior que não avisar.
+ *
+ * @param {string} out saída de `gh auth status`
+ * @returns {string|null}
+ */
+export function parseActiveAccount(out) {
+  let active = null;
+  let last = null;
+  for (const line of String(out || '').split('\n')) {
+    const m = line.match(/account\s+(\S+)/);
+    if (m) {
+      last = m[1];
+      if (!active) active = last; // versões antigas não têm "Active account"
+    }
+    if (/Active account:\s*true/i.test(line) && last) active = last;
+  }
+  return active;
+}
+
+/**
+ * Decide a ORIGEM do token (função PURA — testável sem env nem gh).
+ *
+ * @param {object} params
+ * @param {object} params.env objeto tipo process.env
+ * @param {{login:string,source:string}|null} params.account conta declarada
+ * @returns {{ kind: 'env'|'gh-account'|'gh-active', name?: string, login?: string, source?: string }}
+ */
+export function resolveTokenSource({ env = {}, account = null } = {}) {
+  // Em CI o ambiente é a autoridade: é ele que injeta o GITHUB_TOKEN do run, e
+  // não há `gh` instalado para consultar.
+  const inCi = Boolean(env.GITHUB_ACTIONS || env.CI);
+  if (inCi) {
+    if (env.GITHUB_TOKEN) return { kind: 'env', name: 'GITHUB_TOKEN' };
+    if (env.GH_TOKEN) return { kind: 'env', name: 'GH_TOKEN' };
+    return { kind: 'gh-active' };
+  }
+  // Fora do CI, conta declarada vence a variável de ambiente — é a declaração
+  // explícita ganhando de um default herdado do shell.
+  if (account?.login) return { kind: 'gh-account', login: account.login, source: account.source };
+  if (env.GITHUB_TOKEN) return { kind: 'env', name: 'GITHUB_TOKEN' };
+  if (env.GH_TOKEN) return { kind: 'env', name: 'GH_TOKEN' };
+  return { kind: 'gh-active' };
+}
+
+/**
+ * Aviso de divergência entre a conta ativa do `gh` e a do token (função PURA).
+ *
+ * A comparação é entre os TOKENS, não entre logins: descobrir o login de um
+ * token exige uma chamada à API, e um aviso que custa rede em todo comando não
+ * se paga. O token da conta ativa vem de `gh auth token` (execução local), e se
+ * for igual ao do ambiente não há divergência nenhuma — é o caso comum de quem
+ * exportou a variável a partir da própria conta ativa.
+ *
+ * Sem os dois tokens para comparar, NÃO avisa: um aviso que dispara sempre vira
+ * ruído, e ruído em aviso de diagnóstico é pior que silêncio.
+ *
+ * @param {object} params
+ * @param {{kind:string,name?:string}} params.source origem do token em uso
+ * @param {string} [params.tokenValue] token que será usado
+ * @param {string} [params.activeToken] token da conta ativa do gh
+ * @param {string} [params.activeLogin] login da conta ativa do gh
+ * @returns {string|null} a linha de aviso, ou null quando não há o que dizer
+ */
+export function accountMismatchWarning({
+  source, tokenValue, activeToken, activeLogin,
+} = {}) {
+  if (source?.kind !== 'env') return null;
+  if (!activeLogin || !activeToken || !tokenValue) return null;
+  if (activeToken === tokenValue) return null; // mesma credencial — nada a dizer
+  return (
+    `⚠️  Usando o token da variável ${source.name}, que NÃO é o da conta ativa do gh (${activeLogin}).\n` +
+    `   Se o comando falhar com "Could not resolve to a Repository", é isto: o token não enxerga o repo.\n` +
+    `   Corrija com \`--account ${activeLogin}\` ou grave \`"github": { "account": "${activeLogin}" }\` no .spec-wave.json.`
+  );
+}
+
+// Token da conta ativa do gh — usado só para comparar com o do ambiente.
+// Execução local, sem rede; sem gh, devolve null e o aviso não sai.
+function activeGhToken() {
   try {
-    const token = execSync('gh auth token', { stdio: ['pipe', 'pipe', 'pipe'] })
-      .toString()
-      .trim();
+    return gh('auth token') || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Token do GitHub para esta execução.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.quiet=false] não imprime o aviso de divergência
+ * @returns {Promise<string>}
+ */
+export async function resolveToken({ quiet = false } = {}) {
+  const source = resolveTokenSource({ env: process.env, account: declaredAccount() });
+
+  if (source.kind === 'env') {
+    const token = process.env[source.name];
+    // O aviso custa duas execuções locais do gh (sem rede). Só fora do CI.
+    if (!quiet && !process.env.GITHUB_ACTIONS && !process.env.CI) {
+      const warning = accountMismatchWarning({
+        source,
+        tokenValue: token,
+        activeToken: activeGhToken(),
+        activeLogin: activeGhAccount(),
+      });
+      if (warning) console.warn(warning);
+    }
+    return token;
+  }
+
+  if (source.kind === 'gh-account') {
+    try {
+      const token = gh(`auth token -u ${source.login}`);
+      if (token) return token;
+    } catch (err) {
+      throw new Error(
+        `Não consegui obter o token da conta "${source.login}" (declarada em ${source.source}).\n` +
+        `Rode \`gh auth login -u ${source.login}\` ou ajuste a conta declarada.\n` +
+        `Detalhe: ${err.message.split('\n')[0]}`
+      );
+    }
+    throw new Error(`\`gh auth token -u ${source.login}\` não devolveu token.`);
+  }
+
+  try {
+    const token = gh('auth token');
     if (token) return token;
   } catch {
-    // gh not installed or not authenticated
+    // gh não instalado ou sem login
   }
   throw new Error(
-    'GitHub token not found.\n' +
-    'Set GITHUB_TOKEN or GH_TOKEN environment variable, or run: gh auth login'
+    'Token do GitHub não encontrado.\n' +
+    'Defina GITHUB_TOKEN/GH_TOKEN, rode `gh auth login`, ou declare a conta com ' +
+    '`--account <login>` (ou "github": { "account": "<login>" } no .spec-wave.json).'
   );
 }
 
+/** De onde o token desta execução viria — usado pelo `doctor` no relatório. */
+export function tokenMismatchWarning() {
+  if (process.env.GITHUB_ACTIONS || process.env.CI) return null;
+  const source = resolveTokenSource({ env: process.env, account: declaredAccount() });
+  if (source.kind !== 'env') return null;
+  return accountMismatchWarning({
+    source,
+    tokenValue: process.env[source.name],
+    activeToken: activeGhToken(),
+    activeLogin: activeGhAccount(),
+  });
+}
+
+export function describeTokenSource(cwd = process.cwd()) {
+  const source = resolveTokenSource({ env: process.env, account: declaredAccount(cwd) });
+  if (source.kind === 'env') return `variável ${source.name}`;
+  if (source.kind === 'gh-account') return `gh auth token -u ${source.login} (${source.source})`;
+  return 'gh auth token (conta ativa)';
+}
+
 export async function verifyTokenScopes(token) {
   const { Octokit } = await import('@octokit/rest');
   const octokit = new Octokit({ auth: token });

package/src/api/github-graphql.mjs

@@ -220,6 +220,9 @@ export async function listSubIssues(token, issueNodeId) {
               number
               title
               body
+              createdAt
+              state
+              stateReason
               labels(first: 20) { nodes { name } }
             }
           }
@@ -233,10 +236,40 @@ export async function listSubIssues(token, issueNodeId) {
     title: n.title,
     body: n.body || '',
     nodeId: n.id,
+    // `createdAt` é o que permite ao code-review ignorar sub-issues nascidas
+    // depois da abertura do PR — ver partitionByCreation em code-review.mjs.
+    createdAt: n.createdAt || null,
+    // OPEN/CLOSED e COMPLETED/NOT_PLANNED/REOPENED — o doctor usa o par para
+    // distinguir "entregue" de "descartada no rescopo".
+    state: (n.state || '').toLowerCase() || null,
+    stateReason: (n.stateReason || '').toLowerCase() || null,
     labels: (n.labels?.nodes || []).map(l => l.name),
   }));
 }
 
+/**
+ * Issues que o GitHub reconhece como fechadas por este PR
+ * (`Closes #N` e o vínculo feito pela UI). É a MESMA lista que fecha as issues
+ * no merge — por isso é a fonte primária de vínculo do code-review, acima do
+ * parse do corpo.
+ *
+ * @returns {Promise<number[]>} números das issues vinculadas
+ */
+export async function getPRClosingIssues(token, owner, repo, prNumber) {
+  const client = makeClient(token);
+  const result = await client(`
+    query ClosingIssues($owner: String!, $repo: String!, $number: Int!) {
+      repository(owner: $owner, name: $repo) {
+        pullRequest(number: $number) {
+          closingIssuesReferences(first: 50) { nodes { number } }
+        }
+      }
+    }
+  `, { owner, repo, number: prNumber });
+  const nodes = result.repository?.pullRequest?.closingIssuesReferences?.nodes || [];
+  return nodes.map(n => n.number).filter(Boolean);
+}
+
 // Lê o parent (issue pai) de uma sub-issue. Retorna { number, title, nodeId }
 // ou null se a issue não tiver pai. Usado para subir a cadeia Task→Story→Feature.
 export async function getIssueParent(token, issueNodeId) {