@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/src/lib/evaluator-report.js

@@ -15,6 +15,41 @@
  * 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';
@@ -27,29 +62,133 @@ import { getAbsoluteOutputPath } from '../core/paths/output-schema.js';
  */
 export const COMPOSITE_SCORE_TOKEN = '**Composite-Score:**';
 
-const COMPOSITE_SCORE_RE = /\*\*Composite-Score:\*\*\s*([0-9]+(?:\.[0-9]+)?)/;
+/**
+ * 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;
+
+/**
+ * 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`.
+ */
+const MEDIA_SECTION_RE = /^##\s+M[íi]dia\s+gerada\s*$/m;
+
+/**
+ * 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');
+  } 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]));
+}
+
 /**
  * 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) {
-  try {
-    const p = evaluatorReportPath(cwd, featureName);
-    if (!existsSync(p)) return undefined;
-    const m = readFileSync(p, 'utf8').match(COMPOSITE_SCORE_RE);
-    return m ? Number(m[1]) : undefined;
-  } catch {
-    return undefined;
-  }
+  const text = readReport(cwd, featureName);
+  if (text === null) return undefined;
+  const scores = compositeScoresIn(text);
+  return scores.length === 0 ? undefined : scores[scores.length - 1];
 }
 
 /**
@@ -60,13 +199,128 @@ export function evaluatorCompositeScore(cwd, featureName) {
  * "o avaliador rodou mas o relatório está oco — ele não seguiu o contrato";
  * e só o terceiro caso é aprovável.
  *
- * @returns {{ status: 'ok'|'missing'|'untokenized', score?: number, path: string }}
+ * `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 }}
  */
 export function evaluatorReportState(cwd, featureName) {
   const path = evaluatorReportPath(cwd, featureName);
-  if (!existsSync(path)) return { status: 'missing', path };
-  const score = evaluatorCompositeScore(cwd, featureName);
-  return score === undefined
-    ? { status: 'untokenized', path }
-    : { status: 'ok', score, path };
+  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]);
+  }
+  return Object.keys(out).length === 0 ? undefined : out;
+}
+
+/**
+ * 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]);
+
+  return {
+    mutationSection: MUTATION_SECTION_RE.test(text),
+    mediaSection: MEDIA_SECTION_RE.test(text),
+    proofScores,
+    path,
+  };
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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;
 }