@polymorphism-tech/morph-spec 8.44.0 → 8.45.0

package/src/lib/evaluator-report.js

@@ -1,373 +1,91 @@
-/**
- * Leitura do `4-review/evaluator-report.md` — o relatório BRUTO do avaliador
- * independente despachado pela `morph-review` no Gate 3.
- *
- * Existe como módulo próprio porque DOIS comandos dependem do mesmo arquivo por
- * razões diferentes, e antes o liam de maneiras diferentes:
- *
- *   - `gate-check` lê o token `**Composite-Score:**` para saber o score REAL da
- *     feature (em vez do proxy de médias de auto-avaliação);
- *   - `approve` exige o arquivo como precondição do Gate 3.
- *
- * A divergência era concreta: `approve.js` montava o path à mão com `join(...)`
- * enquanto `gate-check.js` resolvia por `getAbsoluteOutputPath`. Dois caminhos
- * para o mesmo arquivo é a receita de drift silencioso (a lição A5), e a
- * checagem por `existsSync` puro do `approve` aceitava um relatório SEM o token
- * que o `gate-check` então descartava — o Gate 3 passava carimbado `auto` sobre
- * uma média de auto-avaliação, exatamente o que MORPH.md §5 proíbe.
- *
- * ── O TOKEN VIGENTE É O ÚLTIMO ──────────────────────────────────────────────
- *
- * O `evaluator-report.md` é APPEND-ONLY por contrato: uma reavaliação acrescenta
- * ao fim, preservando a análise anterior. Este módulo lia o COMEÇO (`String.match`
- * com regex sem flag `g`), então num relatório reavaliado o gate era decidido
- * pelo score SUPERADO. Medido em campo três vezes na mesma epic — #90 (8.7 →
- * 9.4), #92 (8.2 → 9.0) e #93 (8.9 → 8.3 → 9.1) — e nas três o avaliador teve de
- * desarmar o token antigo à mão para o gate ler a nota vigente.
- *
- * O caso perigoso é o INVERSO e é silencioso: numa reavaliação que BAIXA a nota
- * (o #93 caiu de 8.9 para 8.3 quando uma correção abriu um bloqueante), o gate
- * leria a nota antiga, mais alta, e AUTO-PASSARIA o Gate 3 sobre um produto com
- * bloqueante aberto — a mesma classe de defeito que a v8.26.0 existiu para
- * fechar, voltando por outra porta: lendo um veredito real, porém vencido.
- *
- * DECISÃO EXPLÍCITA — "o último vence", e não "múltiplos tokens viram
- * `report-ambiguous` e recusam":
- *
- *   1. É a semântica do próprio artefato. Append-only significa que o arquivo é
- *      um LOG, e o valor corrente de um log é a sua última entrada. Ler o
- *      primeiro não é uma política conservadora — é ler a entrada errada.
- *   2. Recusar transformaria um veredito REAL e CORRENTE numa pausa que só sai
- *      editando à mão um arquivo declarado append-only. Isto é exatamente o
- *      contorno manual que este conserto existe para eliminar, promovido a
- *      requisito.
- *   3. Recusar não é mais seguro em nenhum dos dois casos observados: com a nota
- *      SUBINDO, o humano é obrigado a mexer no relatório para liberar um gate
- *      que já foi aprovado; com a nota CAINDO, "o último vence" já pausa sozinho
- *      pela regra de score, que é a razão certa a reportar.
- *
- * Ambiguidade não fica silenciosa, ainda assim: `evaluatorReportState` devolve
- * `scoreTokens` (quantos tokens vivos o arquivo tem) e `superseded` (os valores
- * anteriores, na ordem do arquivo). Quem consome pode dizer "9.1, terceira
- * rodada, superando 8.9 e 8.3" em vez de fingir que só havia um veredito.
- */
-
 import { existsSync, readFileSync } from 'fs';
 import { getAbsoluteOutputPath } from '../core/paths/output-schema.js';
 
-/**
- * O token machine-readable que o avaliador grava por contrato (`morph-review`
- * §4). Espelho de `REVIEWED_SHA_TOKEN` do approve.js — mesma ideia: um relatório
- * de LLM só é auditável por máquina se carregar um campo que a máquina lê.
- */
-export const COMPOSITE_SCORE_TOKEN = '**Composite-Score:**';
-
-/**
- * O token das rubricas de PROVA (`.morph/framework/evals/proof-rubrics/`):
- * `**Proof-Scores:** mutation=9 verde=8 fiacao=9 guard=7 eval=8`. Mesma convenção
- * literal do Composite-Score de propósito — mesmo arquivo, mesmo módulo leitor,
- * mesmo estilo de token. Ele pontua a EVIDÊNCIA que o avaliador produziu, nunca
- * o produto: não entra no composto, impõe teto em `test-coverage`.
- */
-export const PROOF_SCORES_TOKEN = '**Proof-Scores:**';
-
-/** `g` é obrigatório: o arquivo é append-only e o token vigente é o ÚLTIMO. */
-const COMPOSITE_SCORE_RE = /\*\*Composite-Score:\*\*\s*([0-9]+(?:\.[0-9]+)?)/g;
-
-/** Idem — uma reavaliação reescreve os Proof-Scores acrescentando ao fim. */
-const PROOF_SCORES_RE = /\*\*Proof-Scores:\*\*[ \t]*([^\r\n]*)/g;
+export const VERDICT_TOKEN = '**Verdict:**';
+export const VERDICTS = ['SHIP', 'FIX'];
+export const BLOCKER_TYPES = ['uc', 'teste', 'regressao', 'seguranca'];
 
-/**
- * A seção de prova de mutação. Exige `##`: um `# Mutações` é outra estrutura
- * (H1 é título de documento, não seção), e o template que a `morph-review`
- * entrega ao avaliador gera exatamente `## Mutações`. Aceita a grafia sem
- * acento porque um relatório escrito em terminal ASCII continua sendo o mesmo
- * fato — o que não se aceita é o nível errado de cabeçalho.
- */
-const MUTATION_SECTION_RE = /^##\s+Muta[çc][õo]es\s*$/m;
-
-/**
- * A seção de prova de MÍDIA. Mesma disciplina do `## Mutações`: exige `##`, e
- * aceita a grafia sem acento porque um relatório escrito em terminal ASCII
- * continua sendo o mesmo fato. `Mídia gerada` / `Midia gerada`.
- */
+// O relatório é append-only: uma reavaliação acrescenta ao fim, e o token vigente é o ÚLTIMO.
+const VERDICT_RE = /\*\*Verdict:\*\*\s*([A-Za-z]+)/g;
+const BLOCKERS_SECTION_RE = /^##\s+Bloqueadores\s*$/gim;
 const MEDIA_SECTION_RE = /^##\s+M[íi]dia\s+gerada\s*$/m;
-
-/**
- * A seção em que o avaliador confere o checklist de tela do mockup contra a
- * tela entregue (`morph-review` §4). Mesma disciplina: exige `##`.
- */
 const SCREEN_CHECKLIST_SECTION_RE = /^##\s+Checklist\s+de\s+tela\s*$/gim;
 
-/**
- * As chaves reconhecidas de `**Proof-Scores:**`, uma por rubrica de prova.
- * Chave fora desta lista é IGNORADA (não vira score, não vira erro): o relatório
- * é texto de LLM e uma chave inventada não deve nem contaminar nenhum mínimo nem
- * derrubar a leitura das outras.
- *
- * `media` PRECISA estar aqui. Sem isso a rubrica `media-claims.md` seria
- * decorativa: o avaliador escreveria `media=7` e o número seria descartado em
- * silêncio, que é o caso "campo publicado sem nenhum leitor".
- */
-export const PROOF_SCORE_KEYS = ['mutation', 'verde', 'fiacao', 'guard', 'eval', 'media', 'obs'];
-
-/**
- * As chaves que NÃO entram no `min` de `test-coverage` porque impõem teto em
- * OUTRA dimensão: `media` (teto em `architecture`) e `obs` (teto em
- * `code-quality`).
- *
- * **`obs` chegou exatamente pelo caminho que o parágrafo abaixo antecipou**, e
- * vale registrar porque o aviso não bastou. A feature irmã (#94) criou a rubrica
- * `observabilidade-genai.md`, escreveu `obs=` onze vezes no seu próprio
- * `evaluator-report.md` — e a chave não estava em `PROOF_SCORE_KEYS`, nem lá nem
- * na base dela. O parser a descartava em silêncio (ver o `continue` de
- * `parseProofScores`), então a rubrica nasceu DECORATIVA e atravessou **onze
- * rodadas de Gate 3** sem que ninguém percebesse: o número era escrito, lido por
- * um humano no relatório, e nunca chegava ao gate. Só o rebase, que põe as duas
- * features na mesma árvore, tornou o buraco visível.
- *
- * **Isto é uma exclusão, e a forma importa mais que a lista.** A primeira versão
- * era o inverso — uma lista fechada das quatro chaves que entram. Ela responde
- * certo hoje e erra sozinha amanhã: a feature irmã acrescenta uma quinta chave
- * (`eval`) com rubrica própria, e depois do rebase esse `eval=N` cairia do teto
- * **em silêncio** — o "campo publicado sem nenhum leitor" que este mesmo arquivo
- * existe para impedir, produzido pela correção.
- *
- * Por exclusão, uma chave nova nasce DENTRO do mínimo por padrão, e tirá-la de lá
- * passa a ser um ato deliberado e visível: uma linha aqui, com a dimensão que ela
- * limita escrita ao lado. Errar para o lado de "conta no mínimo" custa um teto a
- * mais; errar para o outro lado devolve o gate cego.
- *
- * O motivo de `media` estar fora continua o mesmo: as quatro do mínimo perguntam
- * "a evidência é real?"; `media` pergunta "a chamada mora no lugar certo? que
- * estados existem? o que é publicado?". Um `media=4` derrubando o teto de TESTE
- * seriam dois fatos diferentes lidos como um só.
- */
-export const NON_MUTATION_PROOF_KEYS = ['media', 'obs'];
-
-/**
- * As chaves que entram no `min` que impõe teto em `test-coverage`: DERIVADA de
- * {@link PROOF_SCORE_KEYS} menos {@link NON_MUTATION_PROOF_KEYS} — nunca digitada.
- * Ver o racional da exclusão acima.
- */
-export const MUTATION_PROOF_KEYS =
-  PROOF_SCORE_KEYS.filter((k) => !NON_MUTATION_PROOF_KEYS.includes(k));
-
-/** Path canônico do evaluator-report da feature. Fonte única para os dois comandos. */
 export function evaluatorReportPath(cwd, featureName) {
   return getAbsoluteOutputPath(cwd, featureName, 'evaluatorReport');
 }
 
-/** Conteúdo do relatório, ou null quando ausente/ilegível. Nunca lança. */
 function readReport(cwd, featureName) {
   try {
     const p = evaluatorReportPath(cwd, featureName);
-    if (!existsSync(p)) return null;
-    return readFileSync(p, 'utf8');
+    return existsSync(p) ? readFileSync(p, 'utf8') : null;
   } catch {
     return null;
   }
 }
 
-/**
- * Todos os valores de `**Composite-Score:**` do arquivo, NA ORDEM DO ARQUIVO.
- * O último é o vigente; os anteriores são rodadas superadas.
- *
- * @param {string} text
- * @returns {number[]}
- */
-function compositeScoresIn(text) {
-  return [...text.matchAll(COMPOSITE_SCORE_RE)].map((m) => Number(m[1]));
+function lastSectionBody(text, re) {
+  const matches = [...text.matchAll(re)];
+  if (matches.length === 0) return null;
+  const last = matches[matches.length - 1];
+  const rest = text.slice(last.index + last[0].length);
+  const next = rest.search(/^#{1,2}\s/m);
+  return next === -1 ? rest : rest.slice(0, next);
 }
 
-/**
- * Score composto REAL da feature, do token gravado pelo avaliador independente.
- *
- * Num relatório reavaliado (append-only), é o token do FIM — o veredito
- * vigente. Ver o bloco "O TOKEN VIGENTE É O ÚLTIMO" no topo do arquivo.
- *
- * @returns {number|undefined} undefined quando o relatório não existe, não é
- *   legível, ou existe sem o token (relatório legado ou oco). `undefined` é
- *   deliberado e não 0: quem chama distingue "sem veredito" de "veredito ruim".
- */
-export function evaluatorCompositeScore(cwd, featureName) {
-  const text = readReport(cwd, featureName);
-  if (text === null) return undefined;
-  const scores = compositeScoresIn(text);
-  return scores.length === 0 ? undefined : scores[scores.length - 1];
-}
+const normalizeType = (s) => s.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').trim();
 
 /**
- * Estado do relatório para a precondição do Gate 3.
- *
- * Três valores em vez de booleano PORQUE AS TRÊS SITUAÇÕES PEDEM MENSAGENS
- * DIFERENTES: arquivo ausente é "despache o avaliador"; arquivo sem token é
- * "o avaliador rodou mas o relatório está oco — ele não seguiu o contrato";
- * e só o terceiro caso é aprovável.
- *
- * `scoreTokens`/`superseded` só aparecem no caso `ok` e existem para que uma
- * reavaliação nunca passe silenciosa: o score é o último, mas quem consome sabe
- * quantas rodadas o arquivo carrega e quais notas foram superadas.
- *
- * @returns {{ status: 'ok'|'missing'|'untokenized', score?: number,
- *   scoreTokens?: number, superseded?: number[], path: string }}
+ * Linhas de tabela da última `## Bloqueadores`: `| id | tipo | onde | evidência |`.
+ * Cabeçalho e separador não contam; `untyped` são as linhas cujo tipo não é de {@link BLOCKER_TYPES}.
  */
-export function evaluatorReportState(cwd, featureName) {
-  const path = evaluatorReportPath(cwd, featureName);
-  const text = readReport(cwd, featureName);
-  if (text === null) return { status: 'missing', path };
-  const scores = compositeScoresIn(text);
-  if (scores.length === 0) return { status: 'untokenized', path };
-  return {
-    status: 'ok',
-    score: scores[scores.length - 1],
-    scoreTokens: scores.length,
-    superseded: scores.slice(0, -1),
-    path,
-  };
-}
-
-/**
- * Parseia o corpo de UMA linha `**Proof-Scores:**` — pares `chave=N` separados
- * por espaço.
- *
- * @param {string} body
- * @returns {Record<string, number>|undefined} undefined quando nenhum par
- *   VÁLIDO foi lido (linha vazia, só chaves desconhecidas, ou só valores
- *   não-numéricos). `undefined` e não `{}` pela mesma disciplina do
- *   `evaluatorCompositeScore`: "sem veredito" tem de ser distinguível de
- *   "veredito vazio".
- */
-function parseProofScores(body) {
-  const out = {};
-  for (const m of body.matchAll(/([A-Za-zÀ-ÿ][\w-]*)\s*=\s*([^\s]+)/g)) {
-    const key = m[1].toLowerCase();
-    if (!PROOF_SCORE_KEYS.includes(key)) continue;
-    if (!/^[0-9]+(?:\.[0-9]+)?$/.test(m[2])) continue;
-    out[key] = Number(m[2]);
+function parseBlockers(body) {
+  const blockers = [];
+  const untyped = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (!/^\s*\|/.test(line)) continue;
+    const cells = line.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+    if (cells.every((c) => /^:?-{2,}:?$/.test(c) || c === '')) continue;
+    if (/^#$|^id$/i.test(cells[0]) && /^tipo$/i.test(cells[1] ?? '')) continue;
+    const row = { id: cells[0], type: normalizeType(cells[1] ?? ''), where: cells[2] ?? '', evidence: cells[3] ?? '' };
+    (BLOCKER_TYPES.includes(row.type) ? blockers : untyped).push(row);
   }
-  return Object.keys(out).length === 0 ? undefined : out;
+  return { blockers, untyped };
 }
 
-/**
- * Estado de PROVA do relatório: a seção `## Mutações` está lá, e quais
- * Proof-Scores o avaliador registrou.
- *
- * Deriva do disco e não julga: quem decide se a ausência pausa o Gate 3 é
- * `risk-detector.js` (a divisão "gate-check coleta, risk-detector decide"), e
- * quem decide o teto é a rubrica `test-coverage.md`. O `min` NÃO é gravado
- * aqui — é derivado por quem consome, para que exista um só lugar onde
- * "mínimo de quantas chaves" é definido.
- *
- * Arquivo ausente ou ilegível: `{ mutationSection: false, mediaSection: false,
- * proofScores: undefined }`. Nunca lança, e nunca devolve `0` no lugar de
- * `undefined`.
- *
- * `mediaSection` é lido do MESMO arquivo pelo MESMO módulo, de propósito: uma
- * segunda leitura do relatório noutro lugar é como duas superfícies passam a
- * discordar sobre o que ele diz.
- *
- * @param {string} cwd
- * @param {string} featureName
- * @returns {{ mutationSection: boolean, mediaSection: boolean, proofScores: Record<string, number>|undefined, path: string }}
- */
-export function evaluatorProofState(cwd, featureName) {
-  const path = evaluatorReportPath(cwd, featureName);
-  const text = readReport(cwd, featureName);
-  if (text === null) {
-    return { mutationSection: false, mediaSection: false, proofScores: undefined, path };
-  }
-
-  // Append-only outra vez: numa reavaliação a linha nova vai para o fim, e é
-  // ela que vale. A primeira linha descreveria a prova de uma rodada superada.
-  const lines = [...text.matchAll(PROOF_SCORES_RE)];
-  const proofScores = lines.length === 0
-    ? undefined
-    : parseProofScores(lines[lines.length - 1][1]);
-
+export function evaluatorVerdictFromText(text) {
+  if (typeof text !== 'string') return { verdict: undefined, blockers: [], untyped: [], superseded: [] };
+  const verdicts = [...text.matchAll(VERDICT_RE)].map((m) => m[1].toUpperCase());
+  const body = lastSectionBody(text, BLOCKERS_SECTION_RE);
+  const { blockers, untyped } = body === null ? { blockers: [], untyped: [] } : parseBlockers(body);
   return {
-    mutationSection: MUTATION_SECTION_RE.test(text),
-    mediaSection: MEDIA_SECTION_RE.test(text),
-    proofScores,
-    path,
+    verdict: verdicts.length ? verdicts[verdicts.length - 1] : undefined,
+    blockers,
+    untyped,
+    superseded: verdicts.slice(0, -1),
   };
 }
 
 /**
- * A seção `## Checklist de tela` do relatório, com o corpo da ÚLTIMA ocorrência
- * — append-only outra vez: numa reavaliação a conferência nova vai para o fim.
- * O corpo vai cru para `checklistCoverage` (`src/lib/specs/screen-checklist.js`),
- * dono único do parser de linha do checklist.
- *
- * @returns {{ section: boolean, body: string }} arquivo ausente ou sem a seção:
- *   `{ section: false, body: '' }`. Nunca lança.
+ * `missing`: sem relatório. `unverdicted`: relatório sem `**Verdict:** SHIP|FIX` válido.
+ * `ok`: veredito legível — quem decide se ele libera o ship é o risk-detector.
  */
-export function evaluatorScreenChecklist(cwd, featureName) {
+export function evaluatorReportState(cwd, featureName) {
+  const path = evaluatorReportPath(cwd, featureName);
   const text = readReport(cwd, featureName);
-  const matches = text === null ? [] : [...text.matchAll(SCREEN_CHECKLIST_SECTION_RE)];
-  if (matches.length === 0) return { section: false, body: '' };
-  const last = matches[matches.length - 1];
-  const rest = text.slice(last.index + last[0].length);
-  const next = rest.search(/^#{1,2}\s/m);
-  return { section: true, body: next === -1 ? rest : rest.slice(0, next) };
-}
-
-/**
- * O menor Proof-Score das provas de EVIDÊNCIA — o que impõe o teto em
- * `test-coverage`.
- *
- * Calculado sobre {@link MUTATION_PROOF_KEYS} — que é
- * {@link PROOF_SCORE_KEYS} MENOS {@link NON_MUTATION_PROOF_KEYS}, e não uma lista
- * digitada. `media` responde a outra pergunta e limita outra dimensão
- * (`architecture`); ler as duas famílias como um mínimo só faria um `media=4`
- * derrubar o teto de teste sem que nada de teste tivesse acontecido. Uma chave
- * NOVA de prova entra aqui sozinha: excluí-la exige uma linha deliberada em
- * `NON_MUTATION_PROOF_KEYS`, e nunca acontece por esquecimento.
- *
- * @param {Record<string, number>|undefined} proofScores
- * @returns {number|null} null quando não há nenhum score do mínimo: SEM TETO A
- *   APLICAR, jamais "teto 0". A mesma razão pela qual `count: null` do verify
- *   não é 0.
- */
-export function minProofScore(proofScores) {
-  if (!proofScores) return null;
-  const values = MUTATION_PROOF_KEYS
-    .map((key) => proofScores[key])
-    .filter((n) => typeof n === 'number' && Number.isFinite(n));
-  return values.length === 0 ? null : Math.min(...values);
+  if (text === null) return { status: 'missing', path };
+  const parsed = evaluatorVerdictFromText(text);
+  if (!VERDICTS.includes(parsed.verdict)) return { status: 'unverdicted', path };
+  return { status: 'ok', path, ...parsed };
 }
 
-/**
- * O Proof-Score de MÍDIA, lido à parte. Impõe teto em `architecture` (tabela em
- * `framework/evals/rubrics/architecture.md`, "Tetos de prova de mídia").
- *
- * @param {Record<string, number>|undefined} proofScores
- * @returns {number|null} null quando a chave não foi registrada — o caso normal
- *   de uma feature que não gera mídia, e nunca "teto 0".
- */
-export function mediaProofScore(proofScores) {
-  const value = proofScores?.media;
-  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+export function evaluatorMediaSection(cwd, featureName) {
+  const text = readReport(cwd, featureName);
+  return text !== null && MEDIA_SECTION_RE.test(text);
 }
 
-/**
- * Os dois vereditos do relatório lidos de um TEXTO já em mãos — o score
- * composto vigente e os Proof-Scores vigentes, pela mesma regra append-only
- * (o último token vale) dos leitores por `cwd` acima.
- *
- * Existe para quem tem o relatório fora do caminho canônico — o dashboard lê
- * features arquivadas em `.morph/archive/{f}/4-review/` —, sem que ele
- * precise de uma segunda cópia dos regexes.
- *
- * @param {string} text
- * @returns {{ score: number|undefined, proofScores: Record<string, number>|undefined }}
- */
-export function evaluatorVerdictFromText(text) {
-  if (typeof text !== 'string') return { score: undefined, proofScores: undefined };
-  const scores = compositeScoresIn(text);
-  const lines = [...text.matchAll(PROOF_SCORES_RE)];
-  return {
-    score: scores.length === 0 ? undefined : scores[scores.length - 1],
-    proofScores: lines.length === 0 ? undefined : parseProofScores(lines[lines.length - 1][1]),
-  };
+export function evaluatorScreenChecklist(cwd, featureName) {
+  const text = readReport(cwd, featureName);
+  const body = text === null ? null : lastSectionBody(text, SCREEN_CHECKLIST_SECTION_RE);
+  return body === null ? { section: false, body: '' } : { section: true, body };
 }