@spec-wave/cli 0.29.0 → 0.32.0

package/src/commands/qa-lead.mjs

@@ -0,0 +1,748 @@
+// Orquestrador da trilha de QA — `spec-wave qa-lead <plan|run|report>`
+// (rfc/spec-qa-lead.md).
+//
+// O `qa` valida UMA issue por vez; o `qa-lead` percorre as Features de um
+// MILESTONE (D-QAL1) em duas fases separadas por um portão humano (D-QAL2):
+//
+//   plan   → classifica cada Feature e aplica o gatilho `spec-wave:qa` nas que
+//            não têm plano. PARA no portão de revisão humana (D-QA4).
+//   run    → com a trilha inteira em `qa-ready`, despacha um container isolado
+//            por Feature (D-QAL3), coleta os vereditos dos comentários
+//            `spec-wave:qa-report` e grava o relatório do ciclo (D-QAL4).
+//   report → reimprime o relatório de um ciclo já executado, sem executar nada.
+//
+// Superfície de escrita (§2.1) — exatamente três coisas: a label de GATILHO,
+// os arquivos docs/qa/<slug>/cycle-<n>/ e o bloco na descrição do milestone.
+// Toda mutação de board, Bug e comentário de veredito é do `qa`, que roda
+// DENTRO dos containers.
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  addLabel, getIssue, listMilestones, listIssuesByMilestone,
+  getMilestone, updateMilestoneDescription, listIssueComments,
+} from '../api/github-rest.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadConfig, findConfigPath } from '../lib/project-root.mjs';
+import { loadProjectConfig } from '../lib/board.mjs';
+import { featureDocPaths } from '../lib/doc-paths.mjs';
+import { orderStories } from '../lib/dependencies.mjs';
+import { loadFeatureStories, loadBoardSnapshot } from '../lib/story-graph.mjs';
+import { resolveCacheTtl } from '../lib/net-cache.mjs';
+import { parseQaPlanDoc } from '../lib/qa-plan-doc.mjs';
+import { parseLastQaReport } from '../lib/qa-report.mjs';
+import {
+  resolveLeadConfig, resolveMilestoneRef, qaTrailDir,
+  classifyForPlan, planExitCode, classifyScope, runGate, featureOrderFromStories,
+  featureVerdictFromRun, scenarioCounts, abortedFeatureEntry,
+  buildTrailReport, changedSincePrevious, terminationOf, nextCycleGate, retestPlan,
+  milestoneBlock, upsertMilestoneBlock, renderTrailReportMd,
+} from '../lib/qa-lead.mjs';
+import { createExecutionBackend, containerScript } from '../lib/qa-lead-backend.mjs';
+import { pushWithRebase } from '../lib/git-retry.mjs';
+import { CLI_VERSION } from '../lib/templates.mjs';
+import { CONFIG_FILE, LABEL_QA, LABEL_QA_READY, LABEL_CRITIQUE_FAILED, labelNames } from '../config.mjs';
+
+// Intervalo mínimo entre aplicações de label (§6.1): cada uma dispara um run
+// do Actions, e uma rajada satura a fila.
+const TRIGGER_INTERVAL_MS = 3000;
+
+// Recusa "esperada": mensagem, exit 1, sem stack trace.
+class QaLeadRefusal extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'QaLeadRefusal';
+  }
+}
+
+export async function qaLead({ action, milestone: milestoneArg, ...options }) {
+  const acoes = { plan: qaLeadPlan, run: qaLeadRun, report: qaLeadReport };
+  const fn = acoes[action];
+  if (!fn) {
+    throw new QaLeadRefusal(`Ação inválida: "${action}". Use: qa-lead plan | run | report <milestone>.`);
+  }
+  if (!milestoneArg) {
+    throw new QaLeadRefusal('Informe a milestone (número ou título): `spec-wave qa-lead ' + action + ' <milestone>`.');
+  }
+  return await fn(milestoneArg, options);
+}
+
+// ── bootstrap compartilhado ──────────────────────────────────────────────────
+
+async function bootstrap(milestoneArg) {
+  const configPath = findConfigPath();
+  if (!configPath) {
+    throw new QaLeadRefusal(
+      `Repositório não inicializado (sem ${CONFIG_FILE}). ` +
+      'Rode `npx @spec-wave/cli@latest init` (ou a skill setup) primeiro.'
+    );
+  }
+  const { config, root } = loadConfig();
+  const { owner, repo } = config || {};
+  if (!owner || !repo) {
+    throw new QaLeadRefusal(`${CONFIG_FILE} não contém owner/repo. Rode \`spec-wave init\` novamente.`);
+  }
+  const token = await resolveToken();
+
+  const milestones = await listMilestones(token, owner, repo);
+  const resolved = resolveMilestoneRef(milestones, milestoneArg);
+  if (resolved.error) throw new QaLeadRefusal(resolved.error);
+
+  const lead = resolveLeadConfig(config?.qa?.lead);
+  return { token, owner, repo, root, config, lead, milestone: resolved.milestone };
+}
+
+// Itens do milestone separados por tipo — SEMPRE por Work Item Type (§4.1):
+// Stories e Bugs herdam o milestone do pai (D5), então filtrar por milestone
+// puro mandaria o Lead abrir container para Task.
+async function milestoneItems({ token, owner, repo, milestone }) {
+  const issues = await listIssuesByMilestone(token, owner, repo, milestone.number);
+  const byType = { Feature: [], Story: [], Bug: [] };
+  for (const issue of issues) {
+    const type = detectIssueType(issue);
+    if (byType[type]) byType[type].push(issue);
+  }
+  return byType;
+}
+
+// Ordem das Features = a do `spec-wave order` sem argumento (D-QAL1): ordem
+// topológica das Stories, projetada nas Features donas. Arestas das fontes
+// LOCAIS (dependency-map/doc/body — lib/story-graph): sequenciar a trilha não
+// exige o blocked_by remoto, e era este laço que pagava F+S chamadas por fase.
+async function orderFeatures({ token, owner, repo, root, features, ttlSec }) {
+  const stories = [];
+  const featureOfStory = new Map();
+  const storiesOfFeature = new Map();
+  for (const feature of features) {
+    const carga = await loadFeatureStories({
+      token, owner, repo, root,
+      feature: { number: feature.number, nodeId: feature.node_id, title: feature.title },
+      ttlSec,
+    }).catch(() => ({ stories: [] }));
+    storiesOfFeature.set(feature.number, carga.stories);
+    for (const story of carga.stories) {
+      stories.push({ number: story.number, dependsOn: story.dependsOn });
+      featureOfStory.set(story.number, feature.number);
+    }
+  }
+  const { order } = orderStories(stories);
+  const orderedNumbers = featureOrderFromStories({
+    featureNumbers: features.map(f => f.number),
+    storyOrder: order,
+    featureOfStory,
+  });
+  const byNumber = new Map(features.map(f => [f.number, f]));
+  return {
+    ordered: orderedNumbers.map(n => byNumber.get(n)),
+    featureOfStory,
+    storiesOfFeature,
+  };
+}
+
+function plannedScenarioCount(root, featureTitle) {
+  try {
+    const rel = featureDocPaths(root, { title: featureTitle }, 'Feature')['qa-plan'].rel;
+    const doc = parseQaPlanDoc(readFileSync(path.join(root || process.cwd(), rel), 'utf-8'));
+    return doc.scenarios.length;
+  } catch {
+    return 0;
+  }
+}
+
+// ── fase A — qa-lead plan ────────────────────────────────────────────────────
+
+const PLAN_STATE_LABEL = {
+  pronta: '✅ pronta (qa-ready)',
+  'portao-humano': '⛔ portão humano (critique-failed/needs-human)',
+  'em-voo': '🛫 geração em voo (spec-wave:qa aplicada)',
+  'sem-spec-plan': '📄 sem spec.md+plan.md',
+  gerar: '🏷️ gatilho aplicado agora',
+};
+
+async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {}) {
+  const ctx = await bootstrap(milestoneArg);
+  const { token, owner, repo, root, lead, milestone } = ctx;
+
+  const { Feature: features } = await milestoneItems(ctx);
+  if (features.length === 0) {
+    console.log(`Milestone "${milestone.title}" não tem nenhuma Feature — nada a preparar.`);
+    return;
+  }
+
+  const { ordered } = await orderFeatures({ token, owner, repo, root, features, ttlSec: resolveCacheTtl(ctx.config) });
+
+  const classified = [];
+  for (const feature of ordered) {
+    const paths = featureDocPaths(root, { title: feature.title }, 'Feature');
+    const hasSpecPlan = existsSync(path.join(root, paths.spec.rel))
+      && existsSync(path.join(root, paths.plan.rel));
+    const { state, apply } = classifyForPlan({ labels: labelNames(feature), hasSpecPlan });
+    classified.push({ feature, state, apply });
+  }
+
+  // Aplica o gatilho, uma Feature por vez, com intervalo (§6.1).
+  let applied = 0;
+  for (const item of classified) {
+    if (!item.apply) continue;
+    if (dryRun) {
+      console.log(chalk.dim(`dry-run: aplicaria \`${LABEL_QA}\` na Feature #${item.feature.number}.`));
+      continue;
+    }
+    if (applied > 0) await sleep(TRIGGER_INTERVAL_MS);
+    await addLabel(token, owner, repo, item.feature.number, LABEL_QA);
+    applied += 1;
+    item.state = 'em-voo';
+    console.log(`Feature #${item.feature.number}: \`${LABEL_QA}\` aplicada — plano em geração.`);
+  }
+
+  // --watch: poll até toda disparada resolver, com teto (timeout NÃO é erro
+  // não-tratado — relata as pendentes e sai 1).
+  if (watch && !dryRun && classified.some(c => c.state === 'em-voo')) {
+    const deadline = Date.now() + lead.planWaitTimeoutMin * 60 * 1000;
+    while (Date.now() < deadline && classified.some(c => c.state === 'em-voo')) {
+      await sleep(lead.pollIntervalSec * 1000);
+      for (const item of classified) {
+        if (item.state !== 'em-voo') continue;
+        const issue = await getIssue(token, owner, repo, item.feature.number).catch(() => null);
+        if (!issue) continue;
+        const { state } = classifyForPlan({ labels: labelNames(issue), hasSpecPlan: true });
+        if (state !== 'em-voo') {
+          item.state = state;
+          console.log(`Feature #${item.feature.number}: ${PLAN_STATE_LABEL[state]}.`);
+        }
+      }
+    }
+    const pendentes = classified.filter(c => c.state === 'em-voo');
+    if (pendentes.length > 0) {
+      console.log(chalk.yellow(
+        `--watch estourou ${lead.planWaitTimeoutMin}min com plano(s) ainda em voo: ` +
+        `${pendentes.map(c => `#${c.feature.number}`).join(', ')}.`
+      ));
+    }
+  }
+
+  // Relatório de prontidão — stdout, sem arquivo (§6.1: prontidão é estado
+  // momentâneo, não artefato).
+  console.log(`\nProntidão da trilha — milestone "${milestone.title}" (${classified.length} Feature(s), na ordem da trilha):\n`);
+  for (const item of classified) {
+    console.log(`  #${item.feature.number} ${item.feature.title}`);
+    console.log(`    ${PLAN_STATE_LABEL[item.state] || item.state}`);
+  }
+
+  const humanGate = classified.filter(c => c.state === 'portao-humano');
+  if (humanGate.length > 0) {
+    console.log(chalk.yellow(
+      `\n⛔ Portão humano em: ${humanGate.map(c => `#${c.feature.number}`).join(', ')} — ` +
+      `corrija o documento apontado no comentário 🔎 e remova a label (\`${LABEL_CRITIQUE_FAILED}\`/needs-human).`
+    ));
+  }
+  const prontas = classified.filter(c => c.state === 'pronta').length;
+  console.log(
+    `\n${prontas}/${classified.length} pronta(s). ` +
+    (prontas === classified.length
+      ? chalk.green('Trilha pronta — revise os qa-plan.md e rode `qa-lead run`.')
+      : 'Quando toda Feature estiver `qa-ready`, rode `qa-lead run`.')
+  );
+  process.exitCode = dryRun ? 0 : planExitCode(classified);
+  return { classified: classified.map(c => ({ number: c.feature.number, state: c.state })) };
+}
+
+// ── fase B — qa-lead run ─────────────────────────────────────────────────────
+
+async function qaLeadRun(milestoneArg, {
+  only: onlyArg, maxCycles: maxCyclesArg, dryRun = false,
+} = {}) {
+  const ctx = await bootstrap(milestoneArg);
+  const { token, owner, repo, root, config, lead, milestone } = ctx;
+  const maxCycles = maxCyclesArg ? parseInt(maxCyclesArg, 10) : lead.maxCycles;
+  if (!Number.isInteger(maxCycles) || maxCycles <= 0) {
+    throw new QaLeadRefusal(`--max-cycles inválido: "${maxCyclesArg}".`);
+  }
+
+  if (lead.backend === 'docker' && !lead.container.image) {
+    throw new QaLeadRefusal(
+      'A fase B precisa de `qa.lead.container.image` no .spec-wave.json (§4.5) — é a imagem que ' +
+      'sobe um ambiente isolado por Feature (D-QAL3). Exemplo:\n' +
+      '  "qa": { "lead": { "container": { "image": "ghcr.io/acme/qa-runner:1.4" } } }'
+    );
+  }
+
+  const { Feature: features } = await milestoneItems(ctx);
+  if (features.length === 0) {
+    console.log(`Milestone "${milestone.title}" não tem nenhuma Feature — nada a executar.`);
+    return;
+  }
+  const { ordered, featureOfStory } = await orderFeatures({ token, owner, repo, root, features, ttlSec: resolveCacheTtl(config) });
+
+  // Etapa via snapshot do board (leitura pura — nada de addProjectItem aqui:
+  // o dry-run promete zero escrita, e o run não precisa mutar para ler).
+  const { project, error: projectError } = loadProjectConfig({ cwd: root });
+  let boardIndex = new Map();
+  if (!projectError && project?.id) {
+    // `fresh: true`: o escopo decide O QUE EXECUTA em container — gate de
+    // execução não decide com cache. O snapshot fresco fica gravado para os
+    // comandos seguintes da sessão.
+    boardIndex = (await loadBoardSnapshot({ token, project, root, fresh: true })
+      .catch(() => ({ index: new Map() }))).index;
+  } else {
+    console.warn(chalk.yellow(`⚠️  ${projectError || 'Project não configurado'} — Etapas não legíveis; Features contarão como fora-do-ciclo.`));
+  }
+
+  let trail = ordered.map(f => ({
+    feature: f,
+    scope: classifyScope({ stage: boardIndex.get(f.number)?.fields?.Etapa || null }),
+  }));
+
+  // --only <features>: sub-trilha explícita (decisão humana declarada).
+  if (onlyArg) {
+    const wanted = new Set(String(onlyArg).split(',').map(s => parseInt(s.trim().replace('#', ''), 10)));
+    const unknown = [...wanted].filter(n => !trail.some(t => t.feature.number === n));
+    if (unknown.length > 0) {
+      throw new QaLeadRefusal(`--only cita Feature(s) fora do milestone: ${unknown.map(n => `#${n}`).join(', ')}.`);
+    }
+    trail = trail.filter(t => wanted.has(t.feature.number));
+  }
+
+  // Portão de entrada (D-QAL2): toda Feature em 🧪 QA precisa de qa-ready.
+  const gate = runGate(trail.map(t => ({ number: t.feature.number, labels: t.feature.labels, scope: t.scope })));
+  if (!gate.ok) {
+    throw new QaLeadRefusal(
+      `Feature(s) em 🧪 QA sem \`${LABEL_QA_READY}\`: ${gate.missing.map(n => `#${n}`).join(', ')} — ` +
+      'a fase B só inicia com a trilha inteira revisada (D-QAL2). Rode `qa-lead plan` e revise os planos.'
+    );
+  }
+
+  const inCycle = trail.filter(t => t.scope === 'no-ciclo');
+  const outOfCycle = trail.filter(t => t.scope !== 'no-ciclo');
+
+  // ── ciclo N: estado dos ciclos anteriores ──────────────────────────────────
+  const trailRoot = path.join(root, 'docs', 'qa');
+  const previousReport = lastCycleReport(root, milestone.title);
+  const cycle = (previousReport?.cycle || 0) + 1;
+
+  // Bugs do ciclo anterior que fecharam desde então — o combustível do D-QAL7.
+  const previousBugNumbers = previousReport
+    ? [...new Set([
+        ...previousReport.features.flatMap(f => f.bugsOpened || []),
+        ...(previousReport.bugs?.openBlocking || []),
+      ])]
+    : [];
+  const previousBugs = [];
+  for (const n of previousBugNumbers) {
+    const issue = await getIssue(token, owner, repo, n).catch(() => null);
+    if (issue) previousBugs.push(issue);
+  }
+  const closedBugs = previousBugs.filter(b => b.state === 'closed');
+
+  const cycleGate = nextCycleGate({
+    previousReport, bugsClosedSince: closedBugs.length, maxCycles,
+  });
+  if (!cycleGate.ok) {
+    throw new QaLeadRefusal(`Ciclo ${cycle} não inicia: ${cycleGate.reason}.`);
+  }
+
+  // ── alvos do ciclo ─────────────────────────────────────────────────────────
+  let targets;
+  if (!previousReport) {
+    targets = inCycle.map(t => ({
+      issue: t.feature.number, feature: t.feature.number, only: null, motivo: 'ciclo-1',
+    }));
+  } else {
+    const lastResults = new Map();
+    for (const t of inCycle) {
+      const comments = await listIssueComments(token, owner, repo, t.feature.number).catch(() => []);
+      const parsed = parseLastQaReport(comments);
+      lastResults.set(t.feature.number, [...parsed.results.entries()]
+        .map(([numero, r]) => ({ numero, verdict: r.verdict })));
+    }
+    const plano = retestPlan({
+      previousFeatures: previousReport.features.filter(f =>
+        inCycle.some(t => t.feature.number === f.issue)),
+      lastResults,
+      closedBugs,
+    });
+    targets = plano.targets;
+  }
+
+  // Feature dona de cada alvo (Story herda via sub-issue).
+  const featureOfTarget = (target) => target.feature ?? featureOfStory.get(target.issue) ?? null;
+
+  console.log(`\n🧪 qa-lead run — milestone "${milestone.title}" · ciclo ${cycle}/${maxCycles} · backend ${lead.backend}`);
+  console.log(`Features no ciclo: ${inCycle.map(t => `#${t.feature.number}`).join(', ') || 'nenhuma'}.`);
+  if (outOfCycle.length > 0) {
+    console.log(chalk.dim(
+      outOfCycle.map(t => `  #${t.feature.number}: ${t.scope}`).join('\n')
+    ));
+  }
+  console.log(`Despacho: ${targets.length} alvo(s), até ${lead.maxParallel} container(s) simultâneo(s):`);
+  for (const t of targets) {
+    console.log(`  - qa ${t.issue}${t.only ? ` --only ${t.only.join(',')}` : ''} (${t.motivo})`);
+  }
+
+  if (dryRun) {
+    console.log(chalk.dim('\nDry-run: ZERO container, ZERO escrita.'));
+    return { dryRun: true, cycle, targets };
+  }
+
+  if (targets.length === 0 && inCycle.length === 0) {
+    console.log('Nenhuma Feature em 🧪 QA neste milestone — nada a executar.');
+    return { cycle, targets: [] };
+  }
+
+  // ── backend + preflight global ─────────────────────────────────────────────
+  const backend = createExecutionBackend({
+    backend: lead.backend, image: lead.container.image, checkoutDir: root,
+  });
+  const onSignal = async () => {
+    console.error(chalk.yellow('\nInterrompido — removendo containers do ciclo...'));
+    await backend.cleanup();
+    process.exit(130);
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  const startedAt = new Date().toISOString();
+  const preflight = await runPreflight({ backend, lead, root });
+  if (!preflight.ok) {
+    // Ambiente quebrado é RESULTADO, não crash (§6.2): o relatório sai mesmo
+    // assim, com todos os cenários planejados como blocked/ambiente.
+    const entries = inCycle.map(t => abortedFeatureEntry({
+      issue: t.feature.number,
+      title: t.feature.title,
+      plannedScenarios: plannedScenarioCount(root, t.feature.title),
+    }));
+    entries.push(...outOfCycleEntries(outOfCycle));
+    const report = buildTrailReport({
+      milestone, cycle, startedAt, finishedAt: new Date().toISOString(),
+      preflight, features: entries,
+      previousTotals: previousReport?.totals || null,
+      closedSincePreviousCycle: closedBugs.length,
+      openBlocking: previousBugs.filter(b => b.state !== 'closed').map(b => b.number),
+      terminationReason: 'preflight-falhou',
+    });
+    await publishCycle({ ...ctx, report });
+    process.exitCode = 1;
+    console.error(chalk.red('\nPreflight falhou — ciclo abortado (relatório emitido).'));
+    for (const c of preflight.checks.filter(x => !x.ok)) {
+      console.error(chalk.red(`  ✗ ${c.name}${c.detail ? ` — ${c.detail}` : ''}`));
+    }
+    return { cycle, report };
+  }
+
+  // ── despacho (até maxParallel simultâneos) ─────────────────────────────────
+  const originUrl = gitOriginUrl(root);
+  const containerEnv = resolveContainerEnv({ lead, token });
+  const outcomes = new Map(); // target.issue → { verdictReport, durationSec, aborted }
+
+  const queue = [...targets];
+  const workers = Array.from({ length: Math.min(lead.maxParallel, queue.length) }, async () => {
+    while (queue.length > 0) {
+      const target = queue.shift();
+      const before = parseLastQaReport(
+        await listIssueComments(token, owner, repo, target.issue).catch(() => [])).run;
+      console.log(`▶ despachando container: qa ${target.issue}${target.only ? ` --only ${target.only.join(',')}` : ''}`);
+      const result = await backend.run({
+        name: `qa-${target.issue}`,
+        script: containerScript({
+          issue: target.issue,
+          only: target.only,
+          setup: config?.qa?.setup || null,
+          cliVersion: CLI_VERSION,
+          originUrl,
+        }),
+        env: containerEnv,
+        timeoutMin: lead.featureTimeoutMin,
+        onLog: line => console.log(chalk.dim(`  [#${target.issue}] ${line}`)),
+      }).catch(err => ({ ok: false, timedOut: false, code: null, durationSec: 0, error: err.message }));
+
+      // Coleta pelo COMENTÁRIO da issue (§6.2): o Lead não mantém canal com o
+      // container — quem morreu depois de comentar não perde resultado; quem
+      // morreu antes vira execucao-abortada (§3.3).
+      const parsed = parseLastQaReport(
+        await listIssueComments(token, owner, repo, target.issue).catch(() => []));
+      const fresh = parsed.run > before ? parsed : null;
+      outcomes.set(target.issue, {
+        target,
+        report: fresh,
+        durationSec: result.durationSec ?? null,
+        timedOut: Boolean(result.timedOut),
+      });
+      const status = fresh ? fresh.verdict : (result.timedOut ? 'timeout' : 'sem relatório');
+      console.log(`◀ qa ${target.issue}: ${status} (${result.durationSec ?? '?'}s)`);
+    }
+  });
+  await Promise.all(workers);
+  process.off('SIGINT', onSignal);
+  process.off('SIGTERM', onSignal);
+  await backend.cleanup();
+
+  // ── consolidação por Feature ───────────────────────────────────────────────
+  const entries = [];
+  for (const t of inCycle) {
+    const featureTargets = targets.filter(x => featureOfTarget(x) === t.feature.number);
+    if (featureTargets.length === 0) {
+      // Sem alvo neste ciclo (ex.: vermelha sem Bug fechado): estado herdado.
+      const prev = previousReport?.features.find(f => f.issue === t.feature.number);
+      if (prev) entries.push({ ...prev, durationSec: null });
+      continue;
+    }
+    const merged = { pass: 0, fail: 0, blocked: 0, total: 0, blockedReasons: {} };
+    const bugsOpened = [];
+    let durationSec = 0;
+    let aborted = false;
+    let worst = 'verde';
+    for (const target of featureTargets) {
+      const outcome = outcomes.get(target.issue);
+      durationSec += outcome?.durationSec || 0;
+      if (!outcome?.report) {
+        aborted = true;
+        continue;
+      }
+      const results = [...outcome.report.results.entries()]
+        .map(([numero, r]) => ({ numero, verdict: r.verdict, blockedReason: r.blockedReason }));
+      const counts = scenarioCounts(results);
+      merged.pass += counts.pass;
+      merged.fail += counts.fail;
+      merged.blocked += counts.blocked;
+      merged.total += counts.total;
+      for (const [reason, n] of Object.entries(counts.blockedReasons)) {
+        merged.blockedReasons[reason] = (merged.blockedReasons[reason] || 0) + n;
+      }
+      bugsOpened.push(...outcome.report.bugs.filter(b => !b.existing).map(b => b.number));
+      const verdict = featureVerdictFromRun(outcome.report.verdict);
+      worst = worstOf(worst, verdict);
+    }
+    if (aborted) {
+      // §3.3: container sem veredito → Feature abortada, cenários planejados
+      // como blocked/ambiente. NUNCA lida como verde.
+      const planned = plannedScenarioCount(root, t.feature.title) || merged.total;
+      const entry = abortedFeatureEntry({
+        issue: t.feature.number, title: t.feature.title,
+        plannedScenarios: Math.max(planned - merged.pass - merged.fail - merged.blocked, 0),
+        durationSec,
+      });
+      entry.scenarios.pass = merged.pass;
+      entry.scenarios.fail = merged.fail;
+      entry.scenarios.blocked += merged.blocked;
+      entry.scenarios.total = entry.scenarios.pass + entry.scenarios.fail + entry.scenarios.blocked;
+      entry.blockedReasons = { ...merged.blockedReasons, ambiente: (merged.blockedReasons.ambiente || 0) + (entry.scenarios.blocked - merged.blocked) };
+      entry.bugsOpened = bugsOpened;
+      entries.push(entry);
+      continue;
+    }
+    entries.push({
+      issue: t.feature.number,
+      title: t.feature.title,
+      verdict: worst,
+      scenarios: { pass: merged.pass, fail: merged.fail, blocked: merged.blocked, total: merged.total },
+      blockedReasons: merged.blockedReasons,
+      bugsOpened,
+      durationSec,
+    });
+  }
+  entries.push(...outOfCycleEntries(outOfCycle));
+
+  // Bugs ainda segurando a trilha: os do ciclo anterior que continuam abertos
+  // + os abertos agora.
+  const openBlocking = [...new Set([
+    ...previousBugs.filter(b => b.state !== 'closed').map(b => b.number),
+    ...entries.flatMap(e => e.bugsOpened || []),
+  ])];
+
+  const draft = buildTrailReport({
+    milestone, cycle, startedAt, finishedAt: new Date().toISOString(),
+    preflight, features: entries,
+    previousTotals: previousReport?.totals || null,
+    closedSincePreviousCycle: closedBugs.length,
+    openBlocking,
+  });
+  const changed = changedSincePrevious({
+    previous: previousReport, current: draft, bugsClosedSince: closedBugs.length,
+  });
+  const report = {
+    ...draft,
+    terminationReason: terminationOf({
+      preflightOk: true, trailVerdict: draft.verdict, cycle, maxCycles, changed,
+    }),
+  };
+
+  await publishCycle({ ...ctx, report });
+
+  console.log(`\nVeredito da trilha: ${chalk.bold(report.verdict)}` +
+    (report.terminationReason ? ` · término: ${report.terminationReason}` : ' · outro ciclo possível'));
+  if (report.verdict !== 'liberada') process.exitCode = 1;
+  return { cycle, report };
+}
+
+function worstOf(a, b) {
+  const ordem = ['verde', 'inconclusivo', 'vermelho', 'execucao-abortada'];
+  return ordem.indexOf(b) > ordem.indexOf(a) ? b : a;
+}
+
+function outOfCycleEntries(outOfCycle) {
+  return outOfCycle.map(t => ({
+    issue: t.feature.number,
+    title: t.feature.title,
+    verdict: t.scope === 'ja-aprovada' ? 'ja-aprovada' : 'fora-do-ciclo',
+    scenarios: { pass: 0, fail: 0, blocked: 0, total: 0 },
+    blockedReasons: {},
+    bugsOpened: [],
+    durationSec: null,
+  }));
+}
+
+function gitOriginUrl(root) {
+  try {
+    return execSync('git config --get remote.origin.url', {
+      cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Env dos containers: o token do GitHub (o `qa` lá dentro comenta e move o
+// board) + `qa.lead.container.env`. Valor VAZIO no config significa "vem do
+// ambiente do Lead" — e credencial vazia não entra (withoutBlankCredentials do
+// lado dos Actions tem o mesmo motivo).
+function resolveContainerEnv({ lead, token }) {
+  const out = { GITHUB_TOKEN: token, GH_TOKEN: token };
+  if (process.env.SPEC_WAVE_QA_CMD) out.SPEC_WAVE_QA_CMD = process.env.SPEC_WAVE_QA_CMD;
+  for (const [key, value] of Object.entries(lead.container.env || {})) {
+    const resolved = value === '' || value == null ? process.env[key] : value;
+    if (resolved != null && resolved !== '') out[key] = resolved;
+  }
+  return out;
+}
+
+// Preflight global (§6.2): tudo que quebraria TODOS os containers, testado
+// antes de pagar por qualquer um.
+async function runPreflight({ backend, lead, root }) {
+  const checks = [];
+
+  const avail = backend.available();
+  checks.push({ name: `backend ${lead.backend} acessível`, ok: avail.ok, detail: avail.detail || '' });
+
+  if (avail.ok) {
+    const image = backend.imageAvailable();
+    checks.push({
+      name: `imagem ${lead.container.image || '(não configurada)'}`,
+      ok: image.ok,
+      detail: image.detail || '',
+    });
+  }
+
+  const missingCreds = Object.entries(lead.container.env || {})
+    .filter(([key, value]) => (value === '' || value == null) && !process.env[key])
+    .map(([key]) => key);
+  checks.push({
+    name: 'credenciais de qa.lead.container.env',
+    ok: missingCreds.length === 0,
+    detail: missingCreds.length > 0
+      ? `ausentes no ambiente do Lead: ${missingCreds.join(', ')}`
+      : '',
+  });
+
+  // Espaço em disco: best-effort — ilegível NÃO derruba o preflight.
+  try {
+    const df = execSync(`df -Pk ${JSON.stringify(root)}`, { encoding: 'utf-8' });
+    const availKb = parseInt(df.trim().split('\n').pop().split(/\s+/)[3], 10);
+    checks.push({
+      name: 'espaço em disco',
+      ok: !Number.isInteger(availKb) || availKb > 1024 * 1024,
+      detail: Number.isInteger(availKb) ? `${Math.round(availKb / 1024)}MB livres` : 'não verificável',
+    });
+  } catch {
+    checks.push({ name: 'espaço em disco', ok: true, detail: 'não verificável' });
+  }
+
+  return { ok: checks.every(c => c.ok), checks };
+}
+
+// ── publicação do ciclo (as escritas 2 e 3 do §2.1) ──────────────────────────
+
+async function publishCycle({ token, owner, repo, root, milestone, report }) {
+  const dirRel = qaTrailDir(milestone.title, report.cycle);
+  const dirAbs = path.join(root, dirRel);
+  mkdirSync(dirAbs, { recursive: true });
+  const jsonRel = `${dirRel}/report.json`;
+  const mdRel = `${dirRel}/report.md`;
+  writeFileSync(path.join(root, jsonRel), `${JSON.stringify(report, null, 2)}\n`);
+  writeFileSync(path.join(root, mdRel), renderTrailReportMd(report));
+  console.log(`Relatório do ciclo ${report.cycle} gravado em ${chalk.cyan(dirRel)}/.`);
+
+  // Commit escopado ao diretório do ciclo + push best-effort: o relatório é do
+  // repositório (D-QAL4), mas uma falha de push não pode engolir o veredito.
+  try {
+    execSync(`git add -- ${JSON.stringify(dirRel)}`, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+    execSync(
+      `git commit -m ${JSON.stringify(`docs: relatório de QA da trilha "${milestone.title}" ciclo ${report.cycle} [spec-wave]`)} -- ${JSON.stringify(dirRel)}`,
+      { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+    const push = await pushWithRebase({ cwd: root });
+    if (!push.ok) {
+      console.warn(chalk.yellow(`⚠️  Relatório commitado, mas o push falhou: ${String(push.error).split('\n')[0]} — pushe manualmente.`));
+    }
+  } catch (err) {
+    console.warn(chalk.yellow(`⚠️  Relatório escrito, mas o commit falhou (${String(err.message).split('\n')[0]}) — commite ${dirRel}/ você mesmo.`));
+  }
+
+  // Bloco delimitado na descrição do milestone — SUBSTITUI o bloco, nunca a
+  // descrição (as Release Notes moram no mesmo campo — §4.4).
+  try {
+    const atual = await getMilestone(token, owner, repo, milestone.number);
+    const description = upsertMilestoneBlock(atual.description, milestoneBlock(report, mdRel));
+    await updateMilestoneDescription(token, owner, repo, milestone.number, description);
+    console.log('Bloco de trilha atualizado na descrição do milestone.');
+  } catch (err) {
+    console.warn(chalk.yellow(`⚠️  Não consegui atualizar a descrição do milestone: ${err.message}`));
+  }
+}
+
+// ── qa-lead report ───────────────────────────────────────────────────────────
+
+function lastCycleReport(root, milestoneTitle, cycle = null) {
+  const dirAbs = path.join(root, path.dirname(qaTrailDir(milestoneTitle, 1)));
+  if (!existsSync(dirAbs)) return null;
+  const cycles = readdirSync(dirAbs)
+    .map(n => /^cycle-(\d+)$/.exec(n)?.[1])
+    .filter(Boolean)
+    .map(Number)
+    .sort((a, b) => a - b);
+  const chosen = cycle ?? cycles[cycles.length - 1];
+  if (!chosen || (cycle && !cycles.includes(cycle))) return null;
+  const file = path.join(root, qaTrailDir(milestoneTitle, chosen), 'report.json');
+  if (!existsSync(file)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf-8'));
+    return {
+      ...raw,
+      // resultados como Map não sobrevivem ao JSON — nada a reidratar aqui.
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function qaLeadReport(milestoneArg, { cycle: cycleArg } = {}) {
+  const ctx = await bootstrap(milestoneArg);
+  const { root, milestone } = ctx;
+  const cycle = cycleArg ? parseInt(cycleArg, 10) : null;
+  if (cycleArg && (!Number.isInteger(cycle) || cycle <= 0)) {
+    throw new QaLeadRefusal(`--cycle inválido: "${cycleArg}".`);
+  }
+  const report = lastCycleReport(root, milestone.title, cycle);
+  if (!report) {
+    throw new QaLeadRefusal(
+      cycle
+        ? `Ciclo ${cycle} não encontrado em docs/qa/ para a milestone "${milestone.title}".`
+        : `Nenhum ciclo executado para a milestone "${milestone.title}" — rode \`qa-lead run\` primeiro.`
+    );
+  }
+  console.log(renderTrailReportMd(report));
+  return { report };
+}