@spec-wave/cli 0.29.0 → 0.32.0

package/src/lib/qa-report.mjs

@@ -0,0 +1,396 @@
+// Relatório de execução do QA — módulo PURO, sem I/O.
+//
+// O comentário de veredito é a FONTE DE ESTADO entre execuções: rodar com
+// `--only` lê o último relatório da issue para compor o estado acumulado dos
+// cenários que não rodaram desta vez. O marcador HTML da primeira linha é
+// CONTRATO com a UI do SpecWave — mudar o formato exige bump de versão
+// (`v1` → `v2`).
+
+import { createHash } from 'node:crypto';
+import { REQUIRED_BUG_SECTIONS, QA_BLOCKED_REASONS } from '../config.mjs';
+
+export const QA_REPORT_VERSION = 1;
+
+/** Vereditos aceitos por cenário. */
+export const QA_VERDICTS = ['pass', 'fail', 'blocked'];
+
+export const QA_REPORT_MARKER_RE =
+  /<!--\s*spec-wave:qa-report\s+v(?<version>\d+)\s+issue=(?<issue>\d+)\s+run=(?<run>\d+)\s+verdict=(?<verdict>pass|fail|blocked)\s+planSha=(?<planSha>[0-9a-f]+)\s+headSha=(?<headSha>[0-9a-f?]+)\s*-->/g;
+
+// Origem de um Bug aberto por reprovação de QA — gravado no CORPO da issue do
+// Bug. É a chave da idempotência: re-executar o mesmo cenário reprovado não
+// abre um segundo Bug, comenta no que já existe.
+export const QA_ORIGIN_MARKER_RE =
+  /<!--\s*spec-wave:qa-origin\s+issue=(?<issue>\d+)\s+cenario=(?<cenario>\d+)\s*-->/;
+
+/** Monta o marcador do relatório (função PURA). */
+export function qaReportMarker({ issue, run, verdict, planSha, headSha }) {
+  return `<!-- spec-wave:qa-report v${QA_REPORT_VERSION} issue=${issue} run=${run} ` +
+    `verdict=${verdict} planSha=${planSha} headSha=${headSha || '?'} -->`;
+}
+
+/** Monta o marcador de origem de um Bug de QA (função PURA). */
+export function qaOriginMarker({ issue, cenario }) {
+  return `<!-- spec-wave:qa-origin issue=${issue} cenario=${cenario} -->`;
+}
+
+/**
+ * O corpo de um Bug aberto veio deste cenário? (função PURA)
+ *
+ * @param {string} body corpo da issue do Bug
+ * @param {{issue:number, cenario:number}} origem Story dona + número do cenário
+ * @returns {boolean}
+ */
+export function matchesQaOrigin(body, { issue, cenario }) {
+  const m = QA_ORIGIN_MARKER_RE.exec(String(body || ''));
+  if (!m) return false;
+  return parseInt(m.groups.issue, 10) === issue && parseInt(m.groups.cenario, 10) === cenario;
+}
+
+/** SHA curto (7 hex) do conteúdo do plano — vai no marcador do relatório. */
+export function shortSha(content) {
+  return createHash('sha1').update(String(content ?? ''), 'utf-8').digest('hex').slice(0, 7);
+}
+
+/**
+ * Veredito agregado da execução (função PURA).
+ *
+ * `fail` vence `blocked` de propósito: com um defeito confirmado, o desfecho é
+ * vermelho (abre Bug) mesmo que outro cenário tenha ficado bloqueado. `blocked`
+ * sem nenhum `fail` é INCONCLUSIVO — ambiente quebrado não é defeito de
+ * produto, então nada move e nenhum Bug nasce.
+ *
+ * @param {Array<{verdict:string}>} results
+ * @returns {'pass'|'fail'|'blocked'}
+ */
+export function aggregateVerdict(results = []) {
+  if (results.some(r => r.verdict === 'fail')) return 'fail';
+  if (results.some(r => r.verdict === 'blocked')) return 'blocked';
+  return 'pass';
+}
+
+/**
+ * Valida o payload de resultados escrito pelo executor (função PURA).
+ *
+ * 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 (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, blockedReason:string|null}>}
+ */
+export function validateQaResults(payload, expected = []) {
+  if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.scenarios)) {
+    throw new Error('o arquivo de resultados deveria ser {"scenarios": [...]}.');
+  }
+  const out = new Map();
+  payload.scenarios.forEach((item, i) => {
+    const at = `scenarios[${i}]`;
+    const numero = Number(item?.cenario);
+    if (!Number.isInteger(numero) || numero <= 0) {
+      throw new Error(`${at}.cenario deveria ser o número posicional do cenário, veio ${JSON.stringify(item?.cenario)}.`);
+    }
+    const verdict = String(item?.verdict || '').toLowerCase();
+    if (!QA_VERDICTS.includes(verdict)) {
+      throw new Error(
+        `${at}.verdict = ${JSON.stringify(item?.verdict)} não é aceito ` +
+        `(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,
+      blockedReason: verdict === 'blocked' ? blockedReason : null,
+    });
+  });
+  const missing = expected.filter(n => !out.has(n));
+  if (missing.length > 0) {
+    throw new Error(
+      `faltou o veredito do(s) cenário(s) ${missing.join(', ')} — cenário que não pôde ` +
+      '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));
+}
+
+/**
+ * Compõe o estado acumulado quando a execução foi parcial (`--only`) —
+ * função PURA.
+ *
+ * Cenários não executados nesta corrida herdam o veredito do ÚLTIMO relatório;
+ * sem relatório anterior, contam como pendentes (nunca como pass): a aprovação
+ * exige que todos os alvos tenham passado em ALGUMA corrida registrada.
+ *
+ * @param {object} params
+ * @param {Array<{numero:number, verdict:string, evidencia:string}>} params.executed
+ * @param {Map<number, {verdict:string}>} [params.previous] numero → resultado anterior
+ * @param {number[]} params.allNumbers todos os cenários do escopo
+ * @returns {{ combined: Array, pendingNumbers: number[] }}
+ */
+export function combineWithPrevious({ executed = [], previous = new Map(), allNumbers = [] } = {}) {
+  const executedBy = new Map(executed.map(r => [r.numero, r]));
+  const combined = [];
+  const pendingNumbers = [];
+  for (const n of allNumbers) {
+    if (executedBy.has(n)) {
+      combined.push({ ...executedBy.get(n), carried: false });
+      continue;
+    }
+    const prev = previous.get(n);
+    if (prev) {
+      combined.push({
+        numero: n, verdict: prev.verdict, evidencia: prev.evidencia || '(corrida anterior)',
+        blockedReason: prev.blockedReason || null, carried: true,
+      });
+    } else {
+      pendingNumbers.push(n);
+    }
+  }
+  return { combined, pendingNumbers };
+}
+
+const RESULTS_JSON_RE = /```json spec-wave:qa-results\s*\n([\s\S]*?)\n```/;
+
+/**
+ * Último relatório de QA de uma issue (função PURA).
+ *
+ * Lê os comentários em ordem cronológica; o mais recente vence. O estado por
+ * cenário sai do bloco JSON cercado — reparsear a tabela markdown seria frágil.
+ *
+ * @param {Array<{body?:string}>} comments comentários da issue, em ordem
+ * @returns {{ run: number, verdict: string|null, results: Map<number,object> }}
+ */
+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;
+    const m = QA_REPORT_MARKER_RE.exec(body);
+    if (!m) continue;
+    run = Math.max(run, parseInt(m.groups.run, 10));
+    verdict = m.groups.verdict;
+    const bloco = body.match(RESULTS_JSON_RE);
+    if (!bloco) continue;
+    try {
+      const payload = JSON.parse(bloco[1]);
+      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 || '',
+            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, bugs };
+}
+
+const VERDICT_ICON = { pass: '✅ pass', fail: '❌ fail', blocked: '⚪ blocked' };
+
+// Evidência entra numa célula de tabela markdown: sem quebra de linha, sem pipe
+// e sem fechar o marcador HTML antes da hora.
+function sanitizeCell(text, max = 200) {
+  const clean = String(text ?? '')
+    .replace(/-->/g, '--‑>')
+    .replace(/\|/g, '\\|')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+
+/**
+ * Monta o comentário de relatório de QA (função PURA).
+ *
+ * Primeira linha = marcador (contrato com a UI). O bloco JSON no fim é o que a
+ * próxima execução com `--only` lê para compor o estado acumulado.
+ *
+ * @param {object} params
+ * @param {number} params.issue issue onde o relatório será postado
+ * @param {string} params.scope ex.: "Story #412" ou "Feature #360"
+ * @param {number} params.run número desta execução (1ª, 2ª…)
+ * @param {'pass'|'fail'|'blocked'} params.verdict veredito agregado
+ * @param {string} params.planSha sha curto do qa-plan.md executado
+ * @param {string} [params.headSha] sha curto do HEAD do checkout
+ * @param {Array<{numero, verdict, evidencia, carried?}>} params.results
+ * @param {Array<{number:number, cenario:number, existing?:boolean}>} [params.bugs]
+ * @param {number[]} [params.pendingNumbers] cenários sem veredito em corrida parcial
+ * @param {string} [params.trailer] linha final livre (o que acontece a seguir)
+ * @returns {string} markdown
+ */
+export function renderQaReport({
+  issue, scope, run, verdict, planSha, headSha, results = [], bugs = [],
+  pendingNumbers = [], trailer = '',
+} = {}) {
+  const parts = [
+    qaReportMarker({ issue, run, verdict, planSha, headSha }),
+    '## 🧪 Relatório de QA (spec-wave)',
+    `**Escopo:** ${scope} · **Cenários:** ${results.length} · **Execução:** ${run}ª`,
+  ];
+
+  const linhas = ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
+  for (const r of results) {
+    const carried = r.carried ? ' _(corrida anterior)_' : '';
+    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'));
+
+  if (pendingNumbers.length > 0) {
+    parts.push(
+      `⚠️ Cenário(s) ainda **sem veredito** em nenhuma corrida: ${pendingNumbers.join(', ')} — ` +
+      'a aprovação só sai quando todos tiverem passado.'
+    );
+  }
+  if (bugs.length > 0) {
+    parts.push(
+      '**Bugs abertos:** ' +
+      bugs.map(b => `#${b.number} (cenário ${b.cenario}${b.existing ? ', já existia' : ''})`).join(', ')
+    );
+  }
+  if (trailer) parts.push(trailer);
+
+  parts.push([
+    '```json spec-wave:qa-results',
+    JSON.stringify({
+      issue,
+      run,
+      verdict,
+      scenarios: results.map(r => ({
+        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'));
+
+  return parts.join('\n\n');
+}
+
+/**
+ * bug.md DETERMINÍSTICO de um cenário reprovado (função PURA).
+ *
+ * Exceção documentada à regra "nunca escreva o bug.md à mão" (spec §2.1):
+ * quando o Bug nasce de um cenário de QA reprovado, a reprodução, o
+ * esperado/obtido e o teste de regressão JÁ EXISTEM e são determinísticos — são
+ * o próprio cenário e a saída real da execução. Regenerar por IA só
+ * introduziria alucinação sobre uma execução observada.
+ *
+ * Emite EXATAMENTE as seis seções de REQUIRED_BUG_SECTIONS (o validate compara
+ * byte a byte com `# <seção>`).
+ *
+ * @param {object} params
+ * @param {string} params.title título do Bug (sem o prefixo [BUG])
+ * @param {{anchor, numero, story, criterio, precondicoes, passos, esperado}} params.scenario
+ * @param {string} params.evidence evidência bruta da reprovação
+ * @param {string} params.severity P0–P3
+ * @param {string} [params.headSha] commit do checkout onde a reprova aconteceu
+ * @param {number|null} [params.featureNumber]
+ * @returns {string} markdown
+ */
+export function renderQaBugDoc({
+  title, scenario, evidence, severity, headSha = null, featureNumber = null,
+} = {}) {
+  const [
+    reproducao, esperadoObtido, impacto, causaRaiz, escopo, regressao,
+  ] = REQUIRED_BUG_SECTIONS;
+  const passos = scenario.passos
+    ? scenario.passos
+    : '_(o cenário não declara passos — ver o corpo do cenário no qa-plan.md)_';
+  const pre = scenario.precondicoes ? `**Pré-condições:** ${scenario.precondicoes}\n\n` : '';
+  return [
+    `# [BUG] ${title}`,
+    '',
+    `> Aberto automaticamente pela reprovação do **${scenario.anchor}** do plano de QA` +
+    `${featureNumber ? ` da Feature #${featureNumber}` : ''} (Story #${scenario.story})` +
+    `${headSha ? `, no commit \`${headSha}\`` : ''}. Conteúdo determinístico: cenário + saída real da execução.`,
+    '',
+    `## ${reproducao}`,
+    '',
+    pre + passos,
+    '',
+    `## ${esperadoObtido}`,
+    '',
+    `**Critério:** ${scenario.criterio || '—'}`,
+    '',
+    `**Esperado:** ${scenario.esperado || '—'}`,
+    '',
+    `**Obtido:** ${evidence || '(sem evidência registrada)'}`,
+    '',
+    `## ${impacto}`,
+    '',
+    `Severidade **${severity}**. O critério de aceite acima está descumprido na Story #${scenario.story} — ` +
+    'a Story não avança de 🧪 QA enquanto este Bug estiver aberto.',
+    '',
+    `## ${causaRaiz}`,
+    '',
+    '_A investigar durante a correção — este documento registra uma execução observada, ' +
+    'não uma hipótese de causa._',
+    '',
+    `## ${escopo}`,
+    '',
+    '_A definir na investigação. O fix precisa fazer o cenário abaixo passar sem alterar o critério de aceite._',
+    '',
+    `## ${regressao}`,
+    '',
+    `Re-executar o cenário reprovado após o fix:`,
+    '',
+    '```bash',
+    `npx @spec-wave/cli@latest qa ${scenario.story} --only ${scenario.numero}`,
+    '```',
+    '',
+    `O veredito precisa ser **pass** com o mesmo esperado: ${scenario.esperado || '—'}`,
+    '',
+  ].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 };
+}