@spec-wave/cli 0.29.0 → 0.32.0

package/src/lib/qa-lead.mjs

@@ -0,0 +1,627 @@
+// Decisões PURAS do orquestrador de trilha de QA (`spec-wave qa-lead`,
+// rfc/spec-qa-lead.md).
+//
+// O comando (commands/qa-lead.mjs) coleta o estado — milestone, Features,
+// labels, Etapas, relatórios — e as decisões moram aqui, testáveis sem rede:
+// como classificar cada Feature nas duas fases, quando um ciclo termina
+// (D-QAL7), o que re-testar, e como compor o relatório de trilha (§4.3) e o
+// bloco da descrição do milestone (§4.4).
+//
+// Superfície de escrita do Lead (§2.1 — QUALQUER outra escrita é bug):
+//  1. a label de GATILHO `spec-wave:qa` na fase A;
+//  2. os arquivos docs/qa/<slug-milestone>/cycle-<n>/{report.md,report.json};
+//  3. o bloco delimitado na descrição do milestone.
+// Etapa, `qa-approved`, Bugs e comentários de veredito são do `qa`.
+
+import {
+  STAGE_ORDER, STAGE_QA,
+  LABEL_QA, LABEL_QA_READY, LABEL_QA_APPROVED, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN,
+  QA_BLOCKED_REASONS, labelNames,
+} from '../config.mjs';
+import { QA_ORIGIN_MARKER_RE } from './qa-report.mjs';
+import { slugify } from './slugify.mjs';
+
+export const QA_TRAIL_REPORT_VERSION = 1;
+
+/** Defaults do bloco `qa.lead` do .spec-wave.json (§4.5). */
+export const QA_LEAD_DEFAULTS = {
+  maxParallel: 4,
+  maxCycles: 3,
+  featureTimeoutMin: 45,
+  pollIntervalSec: 30,
+  planWaitTimeoutMin: 20,
+};
+
+/**
+ * Configuração efetiva do Lead (função PURA) — §4.5.
+ *
+ * Valor inválido (não inteiro positivo) cai no default em silêncio; a ausência
+ * de `container.image` NÃO é resolvida aqui — a fase B recusa orientando,
+ * porque só ela precisa de container.
+ *
+ * @param {object} [qaLead] bloco `qa.lead` do .spec-wave.json
+ */
+export function resolveLeadConfig(qaLead = {}) {
+  const cfg = qaLead && typeof qaLead === 'object' ? qaLead : {};
+  const out = { ...QA_LEAD_DEFAULTS };
+  for (const key of Object.keys(QA_LEAD_DEFAULTS)) {
+    if (Number.isInteger(cfg[key]) && cfg[key] > 0) out[key] = cfg[key];
+  }
+  return {
+    ...out,
+    backend: cfg.backend === 'sandbox' ? 'sandbox' : 'docker',
+    container: {
+      image: typeof cfg.container?.image === 'string' && cfg.container.image.trim()
+        ? cfg.container.image.trim()
+        : null,
+      env: cfg.container?.env && typeof cfg.container.env === 'object' ? cfg.container.env : {},
+    },
+  };
+}
+
+/** Diretório (relativo à raiz) do relatório de um ciclo — D-QAL4. */
+export function qaTrailDir(milestoneTitle, cycle) {
+  // Ponto de versão vira separador ("v1.4" → "v1-4", como no exemplo da spec):
+  // o slugify sozinho o descartaria e "v1.4"/"v14" colidiriam no mesmo diretório.
+  const title = String(milestoneTitle ?? '').replace(/\./g, '-');
+  return `docs/qa/${slugify(title)}/cycle-${cycle}`;
+}
+
+/**
+ * Resolve a referência de milestone (número ou título) — função PURA.
+ *
+ * Título ambíguo ou inexistente → erro listando os candidatos (§6.1): mandar o
+ * usuário adivinhar entre nome errado e API fora do ar é o anti-padrão.
+ *
+ * @param {Array<{number:number, title:string, state?:string}>} milestones
+ * @param {string|number} ref
+ * @returns {{ milestone?: object, error?: string }}
+ */
+export function resolveMilestoneRef(milestones = [], ref) {
+  const text = String(ref ?? '').trim();
+  if (/^#?\d+$/.test(text)) {
+    const number = parseInt(text.replace('#', ''), 10);
+    const found = milestones.find(m => m.number === number);
+    return found
+      ? { milestone: found }
+      : { error: `Milestone #${number} não existe. Existem: ${listMilestoneTitles(milestones)}.` };
+  }
+  const matches = milestones.filter(m => String(m.title).toLowerCase() === text.toLowerCase());
+  if (matches.length === 1) return { milestone: matches[0] };
+  if (matches.length > 1) {
+    return {
+      error: `Título "${text}" é ambíguo: ${matches.map(m => `#${m.number}`).join(', ')}. Use o número.`,
+    };
+  }
+  return { error: `Milestone "${text}" não encontrada. Existem: ${listMilestoneTitles(milestones)}.` };
+}
+
+function listMilestoneTitles(milestones) {
+  if (milestones.length === 0) return '(nenhuma)';
+  return milestones.map(m => `#${m.number} "${m.title}"`).join(', ');
+}
+
+// ── Fase A — prontidão dos planos ────────────────────────────────────────────
+
+/**
+ * Classifica uma Feature para a fase de planos (função PURA) — §5/§6.1.
+ *
+ *  • `pronta`         — qa-ready (ou já qa-approved): nada a fazer;
+ *  • `portao-humano`  — critique-failed/needs-human: NUNCA aplicar gatilho;
+ *  • `em-voo`         — `spec-wave:qa` ainda na issue: geração/crítica rodando;
+ *  • `sem-spec-plan`  — sem spec.md+plan.md na base: não há de onde gerar;
+ *  • `gerar`          — aplicar `spec-wave:qa` (gera, ou re-critica o existente).
+ *
+ * @param {object} params
+ * @param {Array<string|{name:string}>} [params.labels]
+ * @param {boolean} [params.hasSpecPlan] spec.md e plan.md existem
+ * @returns {{ state: string, apply: boolean }}
+ */
+export function classifyForPlan({ labels = [], hasSpecPlan = true } = {}) {
+  const names = new Set(labelNames(labels));
+  if (names.has(LABEL_QA_READY) || names.has(LABEL_QA_APPROVED)) {
+    return { state: 'pronta', apply: false };
+  }
+  if (names.has(LABEL_CRITIQUE_FAILED) || names.has(LABEL_NEEDS_HUMAN)) {
+    return { state: 'portao-humano', apply: false };
+  }
+  if (names.has(LABEL_QA)) {
+    return { state: 'em-voo', apply: false };
+  }
+  if (!hasSpecPlan) {
+    return { state: 'sem-spec-plan', apply: false };
+  }
+  return { state: 'gerar', apply: true };
+}
+
+/**
+ * Exit code da fase A (função PURA): 0 só se TODA Feature elegível está pronta.
+ *
+ * `sem-spec-plan` conta como não-pronta de propósito — uma Feature do milestone
+ * sem spec/plan é pendência da trilha, não caso fora do escopo.
+ *
+ * @param {Array<{state:string}>} classified
+ * @returns {number}
+ */
+export function planExitCode(classified = []) {
+  return classified.every(c => c.state === 'pronta') ? 0 : 1;
+}
+
+// ── Fase B — escopo, portão e despacho ───────────────────────────────────────
+
+/**
+ * Escopo de uma Feature no ciclo pela Etapa (função PURA) — §6.2.
+ *
+ * Etapa desconhecida/ilegível conta como `fora-do-ciclo`: na dúvida, o Lead não
+ * abre container — subir ambiente para uma Feature que talvez nem esteja em QA
+ * é custo sem veredito possível.
+ */
+export function classifyScope({ stage = null } = {}) {
+  const idx = stage ? STAGE_ORDER.indexOf(stage) : -1;
+  const qaIdx = STAGE_ORDER.indexOf(STAGE_QA);
+  if (idx === -1 || idx < qaIdx) return 'fora-do-ciclo';
+  if (idx === qaIdx) return 'no-ciclo';
+  return 'ja-aprovada';
+}
+
+/**
+ * Portão de entrada da fase B (função PURA) — D-QAL2.
+ *
+ * TODA Feature em 🧪 QA precisa de `qa-ready`; faltando qualquer uma, a fase B
+ * recusa listando-as. Feature fora do ciclo não bloqueia (é contabilizada).
+ *
+ * @param {Array<{number:number, labels?:Array, scope:string}>} features
+ * @returns {{ ok: boolean, missing: number[] }}
+ */
+export function runGate(features = []) {
+  const missing = features
+    .filter(f => f.scope === 'no-ciclo' && !labelNames(f.labels || []).includes(LABEL_QA_READY))
+    .map(f => f.number);
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Ordem das Features derivada da ordem topológica das Stories (função PURA).
+ *
+ * D-QAL1: a trilha usa a MESMA ordenação do `spec-wave order` sem argumento —
+ * uma Feature vem antes de outra quando alguma Story dela aparece antes na
+ * ordem topológica. Features sem Story ordenada ficam no fim, na ordem de
+ * entrada (a do milestone).
+ *
+ * @param {object} params
+ * @param {number[]} params.featureNumbers na ordem de entrada
+ * @param {number[]} params.storyOrder ordem topológica (números de Story)
+ * @param {Map<number, number>} params.featureOfStory Story → Feature dona
+ * @returns {number[]}
+ */
+export function featureOrderFromStories({ featureNumbers = [], storyOrder = [], featureOfStory = new Map() } = {}) {
+  const known = new Set(featureNumbers);
+  const ordered = [];
+  const seen = new Set();
+  for (const story of storyOrder) {
+    const feature = featureOfStory.get(story);
+    if (feature != null && known.has(feature) && !seen.has(feature)) {
+      seen.add(feature);
+      ordered.push(feature);
+    }
+  }
+  for (const feature of featureNumbers) {
+    if (!seen.has(feature)) {
+      seen.add(feature);
+      ordered.push(feature);
+    }
+  }
+  return ordered;
+}
+
+// ── Coleta e veredito ────────────────────────────────────────────────────────
+
+/**
+ * Veredito de Feature a partir do veredito do qa-report (função PURA).
+ *
+ * `null` (nenhum relatório novo apareceu) é `execucao-abortada` — §3.3: uma
+ * Feature sem NENHUM veredito nunca pode ser lida como verde, e o silêncio de
+ * um container morto viraria exatamente isso.
+ */
+export function featureVerdictFromRun(reportVerdict) {
+  if (reportVerdict === 'pass') return 'verde';
+  if (reportVerdict === 'fail') return 'vermelho';
+  if (reportVerdict === 'blocked') return 'inconclusivo';
+  return 'execucao-abortada';
+}
+
+/**
+ * Contagem de cenários de um conjunto de resultados (função PURA).
+ *
+ * @param {Array<{verdict:string, blockedReason?:string|null}>} results
+ * @returns {{ pass:number, fail:number, blocked:number, total:number, blockedReasons:Record<string,number> }}
+ */
+export function scenarioCounts(results = []) {
+  const out = { pass: 0, fail: 0, blocked: 0, total: 0, blockedReasons: {} };
+  for (const r of results) {
+    if (r.verdict === 'pass') out.pass += 1;
+    else if (r.verdict === 'fail') out.fail += 1;
+    else if (r.verdict === 'blocked') {
+      out.blocked += 1;
+      const reason = QA_BLOCKED_REASONS.includes(r.blockedReason) ? r.blockedReason : 'outro';
+      out.blockedReasons[reason] = (out.blockedReasons[reason] || 0) + 1;
+    }
+    out.total += 1;
+  }
+  return out;
+}
+
+/**
+ * Entrada de Feature abortada (função PURA) — §3.3: os cenários PLANEJADOS
+ * contam como blocked/ambiente, registrados pelo LEAD (o `qa` nunca soube da
+ * morte do container).
+ */
+export function abortedFeatureEntry({ issue, title, plannedScenarios = 0, durationSec = null }) {
+  return {
+    issue,
+    title,
+    verdict: 'execucao-abortada',
+    scenarios: { pass: 0, fail: 0, blocked: plannedScenarios, total: plannedScenarios },
+    blockedReasons: plannedScenarios > 0 ? { ambiente: plannedScenarios } : {},
+    bugsOpened: [],
+    durationSec,
+  };
+}
+
+// ── Relatório de trilha (§4.3) ───────────────────────────────────────────────
+
+/**
+ * Compõe o report.json de um ciclo (função PURA) — contrato em
+ * protocol/qa-trail-report.v1.json.
+ *
+ * @param {object} params
+ * @param {{number:number, title:string}} params.milestone
+ * @param {number} params.cycle
+ * @param {string|null} [params.startedAt]
+ * @param {string|null} [params.finishedAt]
+ * @param {{ok:boolean, checks:Array}} [params.preflight]
+ * @param {Array} params.features entradas por Feature (ver abortedFeatureEntry)
+ * @param {{pass:number, blocked:number}|null} [params.previousTotals] do ciclo N-1
+ * @param {number} [params.closedSincePreviousCycle]
+ * @param {number[]} [params.openBlocking] Bugs abertos segurando a trilha
+ * @param {string|null} [params.terminationReason]
+ */
+export function buildTrailReport({
+  milestone, cycle, startedAt = null, finishedAt = null,
+  preflight = { ok: true, checks: [] },
+  features = [], previousTotals = null, closedSincePreviousCycle = 0,
+  openBlocking = [], terminationReason = null,
+} = {}) {
+  const totals = { pass: 0, fail: 0, blocked: 0, naoExecutado: 0, total: 0 };
+  const blockedByReason = {};
+  let opened = 0;
+  for (const f of features) {
+    totals.pass += f.scenarios?.pass || 0;
+    totals.fail += f.scenarios?.fail || 0;
+    totals.blocked += f.scenarios?.blocked || 0;
+    totals.naoExecutado += f.naoExecutado || 0;
+    for (const [reason, n] of Object.entries(f.blockedReasons || {})) {
+      blockedByReason[reason] = (blockedByReason[reason] || 0) + n;
+    }
+    opened += (f.bugsOpened || []).length;
+  }
+  totals.total = totals.pass + totals.fail + totals.blocked + totals.naoExecutado;
+
+  const inCycle = features.filter(f =>
+    ['verde', 'vermelho', 'inconclusivo', 'execucao-abortada'].includes(f.verdict));
+  let verdict;
+  if (preflight.ok === false) verdict = 'ciclo-abortado';
+  // Feature abortada NUNCA é lida como verde (§3.3) — está no filtro abaixo.
+  else if (inCycle.length > 0 && inCycle.every(f => f.verdict === 'verde')) verdict = 'liberada';
+  else verdict = 'nao-liberada';
+
+  return {
+    version: QA_TRAIL_REPORT_VERSION,
+    milestone: { number: milestone.number, title: milestone.title },
+    cycle,
+    startedAt,
+    finishedAt,
+    preflight,
+    features: features.map(f => ({
+      issue: f.issue,
+      title: f.title,
+      verdict: f.verdict,
+      scenarios: f.scenarios || { pass: 0, fail: 0, blocked: 0, total: 0 },
+      bugsOpened: f.bugsOpened || [],
+      durationSec: f.durationSec ?? null,
+    })),
+    totals,
+    blockedByReason,
+    bugs: {
+      opened,
+      closedSincePreviousCycle,
+      openBlocking,
+    },
+    delta: previousTotals
+      ? { pass: totals.pass - (previousTotals.pass || 0), blocked: totals.blocked - (previousTotals.blocked || 0) }
+      : null,
+    verdict,
+    terminationReason,
+  };
+}
+
+/**
+ * Houve mudança de estado desde o ciclo anterior? (função PURA — D-QAL7)
+ *
+ * Mudança = algum Bug fechado desde o ciclo N, ou os totais de pass/fail/blocked
+ * se moveram. Sem ciclo anterior, a pergunta não se aplica (null).
+ */
+export function changedSincePrevious({ previous = null, current, bugsClosedSince = 0 } = {}) {
+  if (!previous) return null;
+  if (bugsClosedSince > 0) return true;
+  const a = previous.totals || {};
+  const b = current.totals || {};
+  return a.pass !== b.pass || a.fail !== b.fail || a.blocked !== b.blocked;
+}
+
+/**
+ * terminationReason do ciclo recém-terminado (função PURA) — D-QAL7 + §4.3.
+ *
+ * Preenchido só quando este é o ÚLTIMO ciclo; null = outro ciclo pode vir.
+ */
+export function terminationOf({
+  preflightOk = true, trailVerdict, cycle, maxCycles, changed = null,
+} = {}) {
+  if (!preflightOk) return 'preflight-falhou';
+  if (trailVerdict === 'liberada') return 'todas-verdes';
+  if (changed === false) return 'sem-mudanca-de-estado';
+  if (cycle >= maxCycles) return 'teto-de-ciclos';
+  return null;
+}
+
+/**
+ * O ciclo N+1 pode começar? (função PURA — D-QAL7)
+ *
+ * Só se, desde o ciclo N, algum Bug foi fechado OU o ciclo N deixou cenários
+ * bloqueados (um bloqueio pode ter caído — só rodando se descobre; o pós-ciclo
+ * detecta a passada vazia e para com `sem-mudanca-de-estado`).
+ *
+ * @param {object} params
+ * @param {object|null} params.previousReport report.json do ciclo N
+ * @param {number} [params.bugsClosedSince]
+ * @param {number} [params.maxCycles]
+ */
+export function nextCycleGate({ previousReport = null, bugsClosedSince = 0, maxCycles = QA_LEAD_DEFAULTS.maxCycles } = {}) {
+  if (!previousReport) return { ok: true, reason: null }; // ciclo 1
+  if (previousReport.verdict === 'liberada') {
+    return { ok: false, reason: 'trilha já liberada no ciclo anterior — nada a re-testar' };
+  }
+  if (previousReport.cycle >= maxCycles) {
+    return {
+      ok: false,
+      reason: `teto de ${maxCycles} ciclos atingido (D-QAL7) — escale para humano`,
+    };
+  }
+  if (previousReport.terminationReason === 'sem-mudanca-de-estado' && bugsClosedSince === 0) {
+    return {
+      ok: false,
+      reason: 'o ciclo anterior terminou sem mudança de estado e nenhum Bug foi fechado desde então',
+    };
+  }
+  if (bugsClosedSince > 0) return { ok: true, reason: null };
+  if ((previousReport.totals?.blocked || 0) > 0) return { ok: true, reason: null };
+  return {
+    ok: false,
+    reason:
+      'nenhum Bug foi fechado desde o ciclo anterior e não havia cenário bloqueado — ' +
+      're-executar produziria o mesmo resultado (D-QAL7)',
+  };
+}
+
+// ── Retestes (§5) ────────────────────────────────────────────────────────────
+
+/** Origem de QA gravada no corpo de um Bug (função PURA). */
+export function bugOriginOf(body) {
+  const m = QA_ORIGIN_MARKER_RE.exec(String(body || ''));
+  if (!m) return null;
+  return { issue: parseInt(m.groups.issue, 10), cenario: parseInt(m.groups.cenario, 10) };
+}
+
+/**
+ * Alvos do ciclo N+1 (função PURA) — retestes derivados do ciclo N:
+ *
+ *  • Story com Bug filho FECHADO desde N → `qa <story> --only <cenários de origem>`;
+ *  • Feature inconclusiva → re-executa só os cenários blocked;
+ *  • Feature abortada → re-executa inteira (não há veredito parcial confiável);
+ *  • Feature verde no ciclo N → NÃO re-executa (§8 — regressão de aprovadas é
+ *    follow-up);
+ *  • Feature vermelha sem Bug fechado → nada a re-testar nela ainda.
+ *
+ * @param {object} params
+ * @param {Array} params.previousFeatures entradas `features` do report N
+ * @param {Map<number, Array<{numero:number, verdict:string}>>} params.lastResults
+ *        issue da Feature → resultados por cenário do último qa-report
+ * @param {Array<{number:number, body?:string}>} params.closedBugs Bugs (de QA)
+ *        fechados desde o ciclo N
+ * @returns {{ targets: Array<{issue:number, feature:number|null, only:number[]|null, motivo:string}> }}
+ */
+export function retestPlan({ previousFeatures = [], lastResults = new Map(), closedBugs = [] } = {}) {
+  const targets = [];
+  const seen = new Set();
+
+  // 1. Bugs fechados → re-teste dos cenários de origem, agrupados por Story.
+  const byStory = new Map();
+  for (const bug of closedBugs) {
+    const origin = bugOriginOf(bug.body);
+    if (!origin) continue;
+    if (!byStory.has(origin.issue)) byStory.set(origin.issue, new Set());
+    byStory.get(origin.issue).add(origin.cenario);
+  }
+  for (const [story, cenarios] of byStory) {
+    seen.add(`story:${story}`);
+    targets.push({
+      issue: story,
+      feature: null,
+      only: [...cenarios].sort((a, b) => a - b),
+      motivo: 'bug-fechado',
+    });
+  }
+
+  // 2. Features inconclusivas → só os cenários blocked; abortadas → inteiras.
+  for (const f of previousFeatures) {
+    if (f.verdict === 'inconclusivo') {
+      const blocked = (lastResults.get(f.issue) || [])
+        .filter(r => r.verdict === 'blocked')
+        .map(r => r.numero)
+        .sort((a, b) => a - b);
+      targets.push({
+        issue: f.issue,
+        feature: f.issue,
+        only: blocked.length > 0 ? blocked : null,
+        motivo: 'inconclusiva',
+      });
+    } else if (f.verdict === 'execucao-abortada') {
+      targets.push({ issue: f.issue, feature: f.issue, only: null, motivo: 'execucao-abortada' });
+    }
+  }
+  return { targets };
+}
+
+// ── Bloco da descrição do milestone (§4.4) ───────────────────────────────────
+
+const TRAIL_BLOCK_RE =
+  /<!--\s*spec-wave:qa-trail\s+v\d+[^>]*-->[\s\S]*?<!--\s*\/spec-wave:qa-trail\s*-->/;
+
+const TRAIL_VERDICT_LABEL = {
+  liberada: 'liberada',
+  'nao-liberada': 'não liberada',
+  'ciclo-abortado': 'ciclo abortado',
+};
+
+function ddmmyyyy(iso) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso || ''));
+  return m ? `${m[3]}/${m[2]}/${m[1]}` : '';
+}
+
+/**
+ * O bloco delimitado do milestone (função PURA) — resumo CURTO de tamanho fixo;
+ * o detalhe vive no arquivo commitado.
+ *
+ * @param {object} report report.json do ciclo
+ * @param {string} reportMdRel caminho do report.md relativo à raiz do repo
+ * @returns {string}
+ */
+export function milestoneBlock(report, reportMdRel) {
+  const openCount = countOpenBugs(report);
+  const linhas = [
+    `<!-- spec-wave:qa-trail v${QA_TRAIL_REPORT_VERSION} milestone=${report.milestone.number} cycle=${report.cycle} -->`,
+    `### 🧪 QA — ciclo ${report.cycle}${report.finishedAt ? ` (${ddmmyyyy(report.finishedAt)})` : ''}`,
+    `🟢 ${report.totals.pass} · 🔴 ${report.totals.fail} · ⛔ ${report.totals.blocked} · ` +
+      `Bugs abertos: ${openCount} · **Veredito: ${TRAIL_VERDICT_LABEL[report.verdict] || report.verdict}**`,
+  ];
+  const bloqueadores = report.bugs?.openBlocking || [];
+  const partes = [];
+  if (bloqueadores.length > 0) partes.push(`Bloqueadores: ${bloqueadores.map(n => `#${n}`).join(', ')}`);
+  partes.push(`[Relatório completo](${reportMdRel})`);
+  linhas.push(partes.join(' · '));
+  linhas.push('<!-- /spec-wave:qa-trail -->');
+  return linhas.join('\n');
+}
+
+function countOpenBugs(report) {
+  // "Bugs abertos" do resumo = os que seguram a trilha agora; na falta da
+  // lista, o total aberto no ciclo.
+  const blocking = report.bugs?.openBlocking;
+  if (Array.isArray(blocking) && blocking.length > 0) return blocking.length;
+  return report.bugs?.opened || 0;
+}
+
+/**
+ * Substitui o bloco entre os marcadores na descrição do milestone (função
+ * PURA). SUBSTITUI, nunca acrescenta um segundo bloco — a descrição também
+ * hospeda as Release Notes, e sobrescrever a descrição inteira apagaria
+ * trabalho de outra feature (§4.4).
+ *
+ * @param {string|null} description descrição atual do milestone
+ * @param {string} block bloco novo (milestoneBlock)
+ * @returns {string}
+ */
+export function upsertMilestoneBlock(description, block) {
+  const atual = String(description ?? '');
+  if (TRAIL_BLOCK_RE.test(atual)) {
+    return atual.replace(TRAIL_BLOCK_RE, block);
+  }
+  if (!atual.trim()) return block;
+  return `${atual.replace(/\s+$/, '')}\n\n${block}`;
+}
+
+// ── report.md (§4.3 — o irmão legível do report.json) ────────────────────────
+
+const FEATURE_VERDICT_ICON = {
+  verde: '🟢 verde',
+  vermelho: '🔴 vermelho',
+  inconclusivo: '⚪ inconclusivo',
+  'execucao-abortada': '💥 execução abortada',
+  'fora-do-ciclo': '⏭️ fora do ciclo',
+  'ja-aprovada': '✅ já aprovada',
+};
+
+/**
+ * Renderiza o report.md de um ciclo (função PURA).
+ *
+ * @param {object} report report.json (buildTrailReport)
+ * @returns {string} markdown
+ */
+export function renderTrailReportMd(report) {
+  const t = report.totals;
+  const parts = [
+    `# 🧪 QA da trilha — milestone "${report.milestone.title}" · ciclo ${report.cycle}`,
+    '',
+    `**Veredito da trilha:** ${TRAIL_VERDICT_LABEL[report.verdict] || report.verdict}` +
+      (report.terminationReason ? ` · **término:** ${report.terminationReason}` : ''),
+    '',
+    `**Cenários:** 🟢 ${t.pass} pass · 🔴 ${t.fail} fail · ⛔ ${t.blocked} blocked · ` +
+      `${t.naoExecutado} não executado(s) · ${t.total} no total`,
+  ];
+  if (report.startedAt || report.finishedAt) {
+    parts.push('', `Início: ${report.startedAt || '—'} · fim: ${report.finishedAt || '—'}`);
+  }
+
+  if (report.preflight && report.preflight.ok === false) {
+    parts.push('', '## ⛔ Preflight falhou — ciclo abortado', '');
+    for (const c of report.preflight.checks || []) {
+      parts.push(`- ${c.ok ? '✅' : '❌'} ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);
+    }
+  }
+
+  parts.push('', '## Features', '', '| Feature | Veredito | 🟢 | 🔴 | ⛔ | Bugs abertos | Duração |', '|---|---|---|---|---|---|---|');
+  for (const f of report.features) {
+    const s = f.scenarios || {};
+    const bugs = (f.bugsOpened || []).map(n => `#${n}`).join(', ') || '—';
+    const dur = f.durationSec != null ? `${Math.round(f.durationSec / 60)}min` : '—';
+    parts.push(
+      `| #${f.issue} ${f.title} | ${FEATURE_VERDICT_ICON[f.verdict] || f.verdict} | ` +
+      `${s.pass ?? 0} | ${s.fail ?? 0} | ${s.blocked ?? 0} | ${bugs} | ${dur} |`
+    );
+  }
+
+  const reasons = Object.entries(report.blockedByReason || {});
+  if (reasons.length > 0) {
+    parts.push('', '## Bloqueios por motivo', '');
+    for (const [reason, n] of reasons.sort((a, b) => b[1] - a[1])) {
+      parts.push(`- \`${reason}\`: ${n}`);
+    }
+  }
+
+  parts.push(
+    '',
+    '## Bugs',
+    '',
+    `- Abertos neste ciclo: ${report.bugs?.opened ?? 0}`,
+    `- Fechados desde o ciclo anterior: ${report.bugs?.closedSincePreviousCycle ?? 0}`,
+    `- Segurando a trilha: ${(report.bugs?.openBlocking || []).map(n => `#${n}`).join(', ') || 'nenhum'}`,
+  );
+
+  if (report.delta) {
+    const sig = n => (n > 0 ? `+${n}` : String(n));
+    parts.push('', `**Delta vs ciclo anterior:** pass ${sig(report.delta.pass)} · blocked ${sig(report.delta.blocked)}`);
+  }
+
+  parts.push('');
+  return parts.join('\n');
+}