@polymorphism-tech/morph-spec 8.24.3 → 8.26.0

package/src/lib/evaluator-report.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+
+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:**';
+
+const COMPOSITE_SCORE_RE = /\*\*Composite-Score:\*\*\s*([0-9]+(?:\.[0-9]+)?)/;
+
+/** Path canônico do evaluator-report da feature. Fonte única para os dois comandos. */
+export function evaluatorReportPath(cwd, featureName) {
+  return getAbsoluteOutputPath(cwd, featureName, 'evaluatorReport');
+}
+
+/**
+ * Score composto REAL da feature, do token gravado pelo avaliador independente.
+ *
+ * @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;
+  }
+}
+
+/**
+ * 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.
+ *
+ * @returns {{ status: 'ok'|'missing'|'untokenized', score?: 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 };
+}

package/src/lib/risk-detector.js

@@ -11,6 +11,8 @@
  *   - verificationStatus: string      — último `morph-spec verify` ('fail' pausa, qualquer gate)
  *   - verificationStale + gate: bool/str — stamp com sha != HEAD pausa SÓ no
  *     ship (gate 'review') — código mudou depois do último verify
+ *   - evalScoreSource + gate: str     — no ship, score que NÃO veio do avaliador
+ *     independente pausa (auto-avaliação não decide o Gate 3)
  *   - evalScore: number               — morph-eval score (pause if < 9)
  *   - taskCount: number               — total tasks (pause if > 20)
  */
@@ -18,6 +20,13 @@
 const SCOPE_TASK_THRESHOLD = 20;
 const MIN_EVAL_SCORE = 9;
 
+// A ÚNICA procedência de `evalScore` que pode decidir o gate de ship. Escrita
+// por gate-check.js quando o token `**Composite-Score:**` foi lido do
+// evaluator-report.md — o veredito do avaliador independente em contexto
+// fresco. Toda outra procedência (proxy de taskScores, override de --signals,
+// ou nenhuma) é auto-avaliação ou palavra de quem já estava no contexto.
+const TRUSTED_EVAL_SOURCE = 'evaluator-report';
+
 // Work types whose ship gate (review) always pauses for a human, regardless
 // of trust mode — a type policy, not a per-feature risk signal. Mirrors
 // `forcedPauseGates` in src/core/work-types.js (hotfix.review); kept here too
@@ -80,6 +89,28 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
+  // No gate de SHIP, um `evalScore` que não veio do avaliador independente NÃO
+  // é sinal de qualidade da feature — é sinal de qualidade das tasks, dado por
+  // quem as implementou. Observado em campo: 7 tasks com auto-score 9.0-9.3
+  // levaram o gate-check a imprimir "auto-pass, nenhum sinal de risco" sobre um
+  // produto que o avaliador independente pontuou 7.2 e reprovou com 3 P1.
+  //
+  // O predicado é por AUSÊNCIA da fonte confiável, não por presença do proxy,
+  // porque há três maneiras de chegar aqui sem avaliador e todas devem pausar:
+  // proxy de taskScores; override manual via --signals; e nenhuma fonte (sem
+  // task pontuada e sem relatório, `evalScore` é OMITIDO e a regra de score
+  // abaixo nem chega a rodar).
+  //
+  // Fora do review não vale: em plan/uiux/proposal o proxy é exatamente o sinal
+  // certo — não existe avaliador independente antes de haver implementação.
+  if (signals.gate === 'review' && signals.evalScoreSource !== TRUSTED_EVAL_SOURCE) {
+    return {
+      pause: true,
+      reason: `Gate 3 sem score do avaliador independente (fonte: ${signals.evalScoreSource ?? 'nenhuma'})`
+            + ' — auto-avaliação de quem implementou não decide o ship',
+    };
+  }
+
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     return {
       pause: true,
@@ -112,6 +143,9 @@ export function getRiskSignals(signals) {
   if (signals.gate === 'review' && signals.verificationStale === true) {
     out.push('verification stamp desatualizado (stale) no ship');
   }
+  if (signals.gate === 'review' && signals.evalScoreSource !== TRUSTED_EVAL_SOURCE) {
+    out.push(`score do Gate 3 sem avaliador independente (fonte: ${signals.evalScoreSource ?? 'nenhuma'})`);
+  }
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     out.push(`eval score ${signals.evalScore}/10`);
   }
@@ -125,4 +159,5 @@ export const RISK_CONSTANTS = {
   SCOPE_TASK_THRESHOLD,
   MIN_EVAL_SCORE,
   FORCED_PAUSE_WORK_TYPES,
+  TRUSTED_EVAL_SOURCE,
 };