@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/src/lib/installers/templates-reconcile.js

@@ -16,8 +16,8 @@
  */
 
 import { existsSync } from 'fs';
-import fs from 'fs-extra';
 import { compareVersions } from '../../utils/version-checker.js';
+import { realEffects } from './effects.js';
 
 /**
  * Last CLI version whose `update`/`setup-infra` still wrote
@@ -62,7 +62,7 @@ export const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
  *   version BEFORE this run (e.g. `checkProjectOutdated().current`)
  * @returns {'absent'|'removed-legacy'|'preserved-override'}
  */
-export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion) {
+export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion, fx = realEffects()) {
   if (!existsSync(templatesDest)) return 'absent';
 
   const isLegacy = !priorProjectVersion
@@ -71,7 +71,7 @@ export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion)
   if (!isLegacy) return 'preserved-override';
 
   try {
-    fs.removeSync(templatesDest);
+    fx.remove(templatesDest);
     return 'removed-legacy';
   } catch {
     // Couldn't remove — don't risk a half-broken state; leave it and let

package/src/lib/risk-detector.js

@@ -9,10 +9,18 @@
  *   - designSystemDivergence: boolean — conflicting design sources detected
  *   - standardsViolations: string[]   — violations of mandate.md proibições
  *   - verificationStatus: string      — último `morph-spec verify` ('fail' pausa, qualquer gate)
+ *   - e2eStatus + e2eReason + gate    — nó e2e do último verify. Um `skip`
+ *     cuja razão NÃO seja dispensa legítima pausa SÓ no ship (gate 'review')
+ *   - verificationScope: string       — escopo do stamp que carimbou esse
+ *     `skip`. Dispensa legítima só conta vinda de 'feature' (ver abaixo)
  *   - 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)
+ *   - mutationProof + gate: object    — { section, min, productionCode } lido do
+ *     evaluator-report.md. No ship, relatório SEM a seção `## Mutações` numa
+ *     feature com código de produção pausa: score é opinião, mutação é prova
+ *   - mediaClaims + gate: object      — { section, score, featureGeneratesMedia }
  *   - evalScore: number               — morph-eval score (pause if < 9)
  *   - taskCount: number               — total tasks (pause if > 20)
  */
@@ -34,6 +42,95 @@ const TRUSTED_EVAL_SOURCE = 'evaluator-report';
 // the work-type config object.
 const FORCED_PAUSE_WORK_TYPES = ['hotfix'];
 
+// As razões literais que `framework/hooks/shared/e2e-check.js` emite quando o
+// nó e2e pula. Casadas por PADRÃO e não por igualdade porque duas delas
+// carregam dado variável (o nome do grupo da task). Ordem irrelevante: os
+// padrões são disjuntos.
+const E2E_SKIP_PATTERNS = [
+  // "docker is not available in this environment — e2e could not run"
+  // (e2e-check.js). A app não foi exercida porque a MÁQUINA não podia.
+  [/docker is not available/i, 'environment'],
+  // `--skip-e2e` — o operador pediu para pular.
+  [/^requested$/i, 'requested'],
+  // "project does not containerize (no compose file)" — não há app para subir.
+  [/does not containerize/i, 'project'],
+  // 'task group "docs" does not touch runtime' — escopo da task, não da app.
+  [/does not touch runtime/i, 'scope'],
+];
+
+// Classes de skip que NÃO são dispensa: o e2e não rodou e nada no repositório
+// diz que ele não precisava rodar. `unknown` está aqui de propósito — inclui a
+// razão vazia/nula, e uma dispensa sem motivo é o mesmo no-op silencioso que
+// esta regra existe para eliminar.
+const E2E_SKIP_CLASSES_THAT_PAUSE = ['environment', 'requested', 'unknown'];
+
+// O ÚNICO escopo de stamp que responde pela feature inteira. `morph-spec verify
+// {f} {task}` carimba `scope: 'task:{id}'`, e o nó e2e de um verify por task
+// pula com a razão do GRUPO daquela task ('task group "docs" does not touch
+// runtime') — uma afirmação sobre UMA task, nunca sobre a app. Sem este teste,
+// a última task de uma feature (tipicamente `group: docs`) compra o Gate 3 da
+// feature que ela mesma acabou de escrever, numa máquina onde a app nunca
+// subiu. Ausente/desconhecido cai do mesmo lado seguro que `unknown`: recusar
+// é barato, aprovar sem prova não é.
+const FEATURE_SCOPE = 'feature';
+
+/**
+ * Classifica a razão literal de um `skip` do nó e2e — de QUEM é a ausência de
+ * prova. Existe porque `verificationStatus` é o rollup do `verify` e um nó que
+ * pula NÃO o reprova: sem classificar a razão, "o e2e rodou e passou" e "o e2e
+ * nunca rodou" chegam ao gate como o mesmo `pass`.
+ *
+ * A assimetria é o ponto: `project`/`scope` descrevem o REPOSITÓRIO dizendo que
+ * não há runtime a exercer (dispensa legítima, registrada com motivo);
+ * `environment`/`requested` descrevem a MÁQUINA ou o operador, e nenhum dos
+ * dois é evidência sobre o código. `unknown` cai no lado seguro pelo mesmo
+ * motivo: recusar é barato, aprovar sem prova não é.
+ *
+ * @param {string|null|undefined} reason - `verification.e2eReason` (a razão
+ *   literal que o `morph-spec verify` carimbou). Vazia/ausente ⇒ 'unknown' —
+ *   DESCONHECIDO, jamais lido como dispensa.
+ * @returns {'environment'|'requested'|'project'|'scope'|'unknown'}
+ */
+export function classifyE2eSkip(reason) {
+  const text = typeof reason === 'string' ? reason.trim() : '';
+  if (text === '') return 'unknown';
+  for (const [pattern, klass] of E2E_SKIP_PATTERNS) {
+    if (pattern.test(text)) return klass;
+  }
+  return 'unknown';
+}
+
+/** Mensagem de pausa por classe — nomeia SEMPRE a razão literal do verify. */
+function e2ePauseReason(klass, reason) {
+  const literal = typeof reason === 'string' && reason.trim() !== '' ? reason.trim() : null;
+  if (klass === 'environment') {
+    return `e2e não verificado (ambiente): ${literal} — a app não foi exercida;`
+         + ' rode o e2e onde ele possa rodar, ou registre a dispensa com `morph-spec gate-decision`';
+  }
+  if (klass === 'requested') {
+    return 'e2e pulado a pedido (--skip-e2e) — pular a pedido não é dispensa;'
+         + ' rode `morph-spec verify {feature}` sem a flag antes do ship';
+  }
+  if (literal === null) {
+    return 'e2e pulado SEM motivo registrado — uma dispensa sem motivo não é dispensa';
+  }
+  return `e2e pulado por razão não classificada: "${literal}" — sem classificação, não há dispensa`;
+}
+
+/**
+ * Mensagem de recusa por ESCOPO do stamp: a razão do skip É uma dispensa
+ * legítima (`project`/`scope`), mas quem a carimbou foi um verify que não
+ * responde pela feature. Nomeia o escopo real para que o leitor saiba qual
+ * comando rodar, em vez de rodar o mesmo de novo.
+ */
+function e2eScopeRefusal(klass, scope, reason) {
+  const literal = typeof reason === 'string' && reason.trim() !== '' ? reason.trim() : 'sem motivo registrado';
+  const where = typeof scope === 'string' && scope.trim() !== '' ? scope.trim() : 'ausente';
+  return `dispensa de e2e [${klass}] veio de um verify de escopo "${where}", não da feature:`
+       + ` "${literal}" — um stamp de task responde por UMA task, não pela app inteira;`
+       + ' rode `morph-spec verify {feature}` (sem task) antes do ship';
+}
+
 /**
  * @param {object} config - .morph/config/config.json contents (uses `trust`)
  * @param {object} signals
@@ -75,6 +172,43 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
+  // No gate de SHIP apenas: o nó e2e do último verify PULOU. Um skip não
+  // reprova o rollup, então `verificationStatus` sai 'pass' e o gate ficava
+  // cego — auto-passando um Gate 3 sobre uma app que ninguém subiu. A razão
+  // literal decide: dispensa legítima (o projeto não containeriza; o grupo da
+  // task não toca runtime) passa e fica REGISTRADA nos signals; ausência de
+  // prova (docker indisponível, `--skip-e2e`, razão nenhuma) pausa. É a prosa
+  // do morph-review virando regra — "docker indisponível não é dispensa" — e
+  // é o que dispensa o `gate-decision --pause false` manual que ela mandava
+  // rodar. Só no review: pausar o Gate 1/2 numa máquina sem docker travaria
+  // trabalho legítimo de planejamento.
+  if (signals.gate === 'review' && signals.e2eStatus === 'skip') {
+    const klass = classifyE2eSkip(signals.e2eReason);
+    if (E2E_SKIP_CLASSES_THAT_PAUSE.includes(klass)) {
+      return { pause: true, reason: e2ePauseReason(klass, signals.e2eReason) };
+    }
+    // Segunda pergunta, que a razão sozinha não responde: QUEM carimbou. O
+    // `verification` é um stamp SINGULAR sobrescrito por qualquer verify, de
+    // qualquer escopo — então um stamp de escopo `task:{id}` no momento do
+    // ship significa literalmente que o último verify NÃO foi o da feature. A
+    // razão que ele carrega descreve outra corrida: 'task group "docs" does
+    // not touch runtime' é dispensa legítima do que AQUELA task verificou, e a
+    // última task de uma feature tipicamente é `group: docs` — ela compraria o
+    // Gate 3 da feature que acabou de escrever, numa máquina onde a app nunca
+    // subiu. Vale para as duas classes de dispensa, e não só para `scope`:
+    // mesmo um "project does not containerize" carimbado por task é a resposta
+    // a uma pergunta que o gate não fez. O caminho de volta é barato e nomeado
+    // (rodar `verify {feature}`), e é o que morph-review já manda fazer antes
+    // do Gate 3. Narrow, nunca widen: nenhuma razão nova passa a valer aqui —
+    // uma que já valia deixa de valer fora do escopo que responde pela app.
+    if (signals.verificationScope !== FEATURE_SCOPE) {
+      return {
+        pause: true,
+        reason: e2eScopeRefusal(klass, signals.verificationScope, signals.e2eReason),
+      };
+    }
+  }
+
   // Furo 2: no gate de SHIP (review) apenas, um stamp de verification cujo
   // sha diverge do HEAD atual significa que código mudou depois do último
   // `morph-spec verify` — o resultado carimbado não cobre mais o que está
@@ -111,6 +245,103 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
+  // No gate de SHIP: o relatório do avaliador chegou SEM a seção `## Mutações`.
+  // O score diz o que o avaliador ACHOU; a seção diz o que ele PROVOU — e um
+  // teste verde só prova que o código roda, nunca que o teste morde. Medido:
+  // 11 testes verdes sobre um artefato que o build recusava, porque nenhum
+  // deles CARREGAVA o arquivo; e um caminho de escrita reduzido a `return 0;`
+  // que passou 23 de 23, todos de recusa.
+  //
+  // DEPOIS da cláusula de procedência e ANTES da de score, e a ordem é
+  // POLÍTICA, não acaso: quando faltam avaliador E seção, a razão reportada tem
+  // de ser a mais fundamental ("sem avaliador independente"), porque exigir a
+  // prova de um relatório que nem devia decidir o gate manda o humano consertar
+  // a coisa errada.
+  //
+  // FAIL-OPEN POR AUSÊNCIA, em duas direções: `productionCode === true` é
+  // exigido EXPLICITAMENTE, então uma feature legada (sinal ausente, `undefined`)
+  // não pausa, e uma feature 100% `docs` — que não tem o que mutar — também
+  // não. Quem decide as duas coisas é gate-check.js, lendo o disco; aqui só se
+  // aplica a política sobre fatos já reunidos.
+  if (signals.gate === 'review'
+      && signals.mutationProof?.productionCode === true
+      && signals.mutationProof?.section !== true) {
+    return {
+      pause: true,
+      reason: 'relatório do avaliador sem a seção `## Mutações` — prova de mutação não registrada'
+            + ' (rubrica evals/proof-rubrics/mutation-proof.md): um teste verde prova que o código'
+            + ' roda, não que o teste morde',
+    };
+  }
+
+  // No gate de SHIP apenas: a feature mexeu num caminho que o PROJETO declarou
+  // como prompt ou modelo, e não há eval verde carimbado. Prompt e modelo são a
+  // única parte do produto cujo comportamento não é lido por build nem por teste
+  // unitário: os dois continuam verdes com o prompt trocado.
+  //
+  // DEPOIS da cláusula de procedência do score, de propósito: quando as duas
+  // valem, "Gate 3 sem score do avaliador independente" continua sendo a razão
+  // reportada — é o defeito mais grave dos dois.
+  //
+  // PAUSA, jamais bloqueia: `approve review` não ganha precondição nova. Uma
+  // segunda precondição dura ali tornaria inaprovável, inclusive por decisão
+  // humana, toda feature legada. Pausa é a severidade certa — o humano lê a
+  // razão e decide.
+  if (signals.gate === 'review' && (signals.promptModel?.touched?.length ?? 0) > 0) {
+    const touched = signals.promptModel.touched;
+    const where = `${touched.slice(0, 3).join(', ')}${touched.length > 3 ? ` (+${touched.length - 3})` : ''}`;
+
+    // `null` é "o projeto não declara nó de eval"; 'skip' é "declara, e esta
+    // corrida não o executou". Razões distintas porque as ações são distintas.
+    if (signals.evalsStatus === null || signals.evalsStatus === undefined) {
+      return {
+        pause: true,
+        reason: `mudou prompt/modelo (${where}) e o projeto não declara nó de eval`
+              + ' — nenhum build ou teste unitário fica vermelho por um prompt trocado;'
+              + ' declare um `runner: "evals"` em project.tests[] ou registre a dispensa com `morph-spec gate-decision`',
+      };
+    }
+    if (signals.evalsStatus === 'skip') {
+      return {
+        pause: true,
+        reason: `mudou prompt/modelo (${where}) e o eval não foi executado neste verify`
+              + ' — rode `morph-spec verify {feature}` (escopo de feature) antes do ship',
+      };
+    }
+    // 'fail' cai fora: um eval vermelho já avermelha o rollup e a regra de
+    // `verificationStatus` acima pausou antes daqui. 'pass' com stamp velho
+    // também já pausou, por `verificationStale`.
+  }
+
+  // No gate de SHIP: uma feature que GERA MÍDIA cujo relatório chegou sem a
+  // seção `## Mídia gerada`. As quatro afirmações que essa seção carrega —
+  // custo, revisão humana, marcação e hot path não bloqueado — são fáceis de
+  // escrever e difíceis de provar, e a mais cara delas é a que ninguém percebe
+  // falhando: mídia gerada dentro de um turno de conversa, com latência
+  // documentada de até 2 min, custo por chamada e ZERO revisão possível.
+  //
+  // DEPOIS da cláusula de procedência e da de mutação, e a ordem é POLÍTICA,
+  // como lá: quando faltam avaliador, seção de mutação E seção de mídia, a razão
+  // reportada tem de ser a mais fundamental, porque mandar o humano consertar a
+  // terceira enquanto a primeira está aberta manda consertar a coisa errada.
+  //
+  // FAIL-OPEN POR AUSÊNCIA, igual: `featureGeneratesMedia === true` é exigido
+  // EXPLICITAMENTE, então uma feature legada (sinal ausente, `undefined`) não
+  // pausa, e a maioria das features — que não gera mídia — fica isenta
+  // automaticamente, sem ninguém precisar lembrar de aplicar a exceção. Quem
+  // decide isso é gate-check.js, lendo `standards[]` das tasks; aqui só se
+  // aplica a política sobre fatos já reunidos.
+  if (signals.gate === 'review'
+      && signals.mediaClaims?.featureGeneratesMedia === true
+      && signals.mediaClaims.section !== true) {
+    return {
+      pause: true,
+      reason: 'relatório do avaliador sem a seção `## Mídia gerada` — as quatro afirmações de mídia'
+            + ' (custo, revisão humana, marcação, hot path) não foram provadas'
+            + ' (rubrica evals/proof-rubrics/media-claims.md)',
+    };
+  }
+
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     return {
       pause: true,
@@ -140,18 +371,70 @@ export function getRiskSignals(signals) {
     out.push(`standards violations: ${signals.standardsViolations.join(', ')}`);
   }
   if (signals.verificationStatus === 'fail') out.push('verify vermelho');
+  // Listado mesmo quando NÃO pausa: uma dispensa que passa silenciosamente é
+  // indistinguível de uma omissão. A classe diz de quem é a ausência de prova.
+  if (signals.gate === 'review' && signals.e2eStatus === 'skip') {
+    const klass = classifyE2eSkip(signals.e2eReason);
+    const literal = typeof signals.e2eReason === 'string' && signals.e2eReason.trim() !== ''
+      ? signals.e2eReason.trim()
+      : 'sem motivo registrado';
+    const where = typeof signals.verificationScope === 'string' && signals.verificationScope.trim() !== ''
+      ? signals.verificationScope.trim()
+      : 'escopo ausente';
+    out.push(`e2e pulado [${klass}] (stamp de ${where}): ${literal}`);
+  }
   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'})`);
   }
+  // Listado mesmo quando NÃO pausa (feature só de docs, ou prova presente com
+  // score baixo): a prova é o insumo do teto de `test-coverage.md`, e um teto
+  // que ninguém enxerga não é aplicado por ninguém.
+  if (signals.gate === 'review' && signals.mutationProof) {
+    const { section, min, productionCode } = signals.mutationProof;
+    if (section !== true) {
+      out.push(productionCode === true
+        ? 'relatório sem a seção `## Mutações` (prova de mutação ausente)'
+        : 'relatório sem a seção `## Mutações` — feature sem código de produção, não pausa');
+    } else if (typeof min === 'number') {
+      out.push(`prova de mutação registrada (menor Proof-Score: ${min})`);
+    } else {
+      out.push('prova de mutação registrada (sem `**Proof-Scores:**` — nenhum teto a aplicar)');
+    }
+  }
+  // Listado mesmo quando NÃO pausa, pela mesma razão do e2e: um projeto que não
+  // declara caminho de prompt/modelo é indistinguível, no relatório, de um que
+  // declara e não tocou em nada — e as duas coisas significam coisas diferentes.
+  if (signals.gate === 'review' && signals.promptModel) {
+    const { declared, touched } = signals.promptModel;
+    if (!declared) {
+      out.push('projeto não declara caminhos de prompt/modelo (project.evals.watch)');
+    } else if ((touched?.length ?? 0) > 0) {
+      out.push(`prompt/modelo tocado (${touched.length}) com eval ${signals.evalsStatus ?? 'não declarado'}`);
+    }
+  }
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     out.push(`eval score ${signals.evalScore}/10`);
   }
   if (typeof signals.taskCount === 'number' && signals.taskCount > SCOPE_TASK_THRESHOLD) {
     out.push(`${signals.taskCount} tasks (over threshold)`);
   }
+  // Listado mesmo quando NÃO pausa, pela mesma razão do sinal irmão: a isenção
+  // de uma feature que não gera mídia tem de ser VISÍVEL, senão é
+  // indistinguível de uma omissão.
+  if (signals.gate === 'review' && signals.mediaClaims?.featureGeneratesMedia === true) {
+    const { section, score } = signals.mediaClaims;
+    if (section !== true) {
+      out.push('relatório sem a seção `## Mídia gerada` (prova de mídia ausente)');
+    } else if (typeof score === 'number') {
+      out.push(`prova de mídia registrada (media=${score}; teto em arquitetura)`);
+    } else {
+      out.push('prova de mídia registrada (sem `media=` nos Proof-Scores — nenhum teto a aplicar)');
+    }
+  }
+
   return out;
 }
 
@@ -160,4 +443,5 @@ export const RISK_CONSTANTS = {
   MIN_EVAL_SCORE,
   FORCED_PAUSE_WORK_TYPES,
   TRUSTED_EVAL_SOURCE,
+  E2E_SKIP_CLASSES_THAT_PAUSE,
 };

package/src/lib/standards/verified-against.js

@@ -0,0 +1,276 @@
+/**
+ * src/lib/standards/verified-against.js
+ *
+ * THE parser for a standard's verification header and for its age against the
+ * AI package pin. Single source of truth, on purpose.
+ *
+ * A standard declares what it was checked against, and when:
+ *
+ *     **Verified against:** Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08);
+ *     provado por `templates/dotnet/ai-kit/.../AgentFactory.cs`. Last-verified: 2026-09-08.
+ *
+ * Three places need to read that same fact — `scripts/check-freshness.js`
+ * (the freshness gate), `test/framework/standard-header.test.js` (the header
+ * contract) and the "ai-agents vs ai-pin" report. Three copies of the regex
+ * would drift apart, which is exactly the failure mode CLAUDE.md's Dependency
+ * Matrix exists to catalogue. So the regex lives here, once.
+ *
+ * The age is measured against `framework/ai-pin.json`'s `pinnedAt`, never
+ * against "today": `pinnedAt` is the date a human checked the packages, so the
+ * obligation is tied to a human act. Measuring against today would make a
+ * parked repository change colour on its own.
+ *
+ * NOTE on the 90-day window: this module EXPOSES the age and the threshold; it
+ * enforces nothing — enforcement lives in its consumers. Issue #93 re-verified
+ * the `ai-agents` standards and turned the window into a HARD FAIL in
+ * scripts/check-freshness.js, so the number below is no longer only a warning.
+ * The name kept the `WARN` in it because renaming an export is a change to the
+ * module's surface, not to its documentation; scripts/check-freshness.js aliases
+ * it to `AI_PIN_STALE_DAYS` rather than re-declaring `90` — see that file's
+ * docblock and CONTRIBUTING.md's "two rulers" table.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+/** Repository root, resolved from this file: src/lib/standards → ../../.. */
+const DEFAULT_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/** Path of the pin relative to a root. */
+const AI_PIN_RELATIVE = join('framework', 'ai-pin.json');
+
+/**
+ * The verification header, on ONE line.
+ *
+ * Group 1 is the subject (what the standard was checked against), group 2 the
+ * ISO date. `[^\n]*?` keeps the match inside a single line: a `Last-verified:`
+ * two paragraphs below belongs to another claim, and stitching the two would
+ * date a header that never carried a date.
+ *
+ * @type {RegExp}
+ */
+export const LAST_VERIFIED_RE = /\*\*Verified against:\*\*([^\n]*?)Last-verified:\s*(\d{4}-\d{2}-\d{2})/;
+
+/**
+ * An unresolved `// VERIFY` marker: a code detail the author could not confirm
+ * against the installed package.
+ *
+ * Deliberately broader than the regex it replaces (`/^\s*\/\/\s*VERIFY:/`),
+ * which demanded line-start AND a colon. Every real marker in
+ * `framework/standards/ai-agents/` is an end-of-line comment without a colon —
+ *
+ *     using OpenAI.Batch;   // VERIFY namespace — confirme contra o pacote OpenAI 2.*
+ *
+ * — so the old counter reported 0 while two standards openly declared
+ * unconfirmed C# API. `\b` keeps `// VERIFYING` out; the fence requirement is
+ * NOT in the regex (a regex cannot see a fence) — it lives in
+ * {@link countVerifyMarkers}, so prose quoting `// VERIFY:` never counts.
+ *
+ * @type {RegExp}
+ */
+export const VERIFY_MARKER_RE = /(^|\s)\/\/\s*VERIFY\b/;
+
+/**
+ * Age, in days against `pinnedAt`, above which an `ai-agents/**` standard is
+ * due for re-verification.
+ *
+ * READ UNDER TWO NAMES, ONE VALUE. `scripts/check-freshness.js` imports it as
+ * `AI_PIN_STALE_DAYS` and **hard-fails** the run above it (issue #93), for
+ * standards under `framework/standards/ai-agents/` measured against `pinnedAt`.
+ * The alias exists so the number is declared once: a second literal `90` is the
+ * same drift that once blinded the `// VERIFY` counter.
+ *
+ * The `WARN` in the name is now historical — it shipped in issue #92, when the
+ * window was a measurement. Kept because renaming an export changes the module's
+ * surface; this comment changes only what the reader is told.
+ *
+ * @type {number}
+ */
+export const AI_AGENTS_WARN_DAYS = 90;
+
+/** ISO calendar date, the only date shape this module accepts. */
+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/**
+ * Parse a standard's verification header.
+ *
+ * @param {string} text - Full markdown text of the standard.
+ * @returns {{ verifiedAgainst: string, lastVerified: string }|null}
+ *   `null` when the standard carries no parseable header — the caller decides
+ *   whether that is a warning (the backfill backlog) or a failure
+ *   (`ai-agents/**`, where a new standard must be born dated).
+ */
+export function parseVerifiedAgainst(text) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  const m = LAST_VERIFIED_RE.exec(text);
+  if (!m) return null;
+  return { verifiedAgainst: m[1].trim(), lastVerified: m[2] };
+}
+
+/**
+ * The `provado por` clause, and the path token that may follow it.
+ *
+ * THREE TYPESETTINGS EXIST IN THE ACERVO, and all three are real claims.
+ * Counted by re-deriving every one of the 78 standards on disk and summing the
+ * resulting paths — 27 paths across 16 entries:
+ *
+ *     A  ; provado por `templates/…/AgentFactory.cs` e `.../ConversationStore.cs`
+ *     B  ; `provado por templates/…/AgentFactory.cs` para a **ordem do pipeline**
+ *     C  . O timeout é **provado por** `.../AgentSpecOptions.cs` e `.../AgentFactory.cs`
+ *
+ * B opens the code span BEFORE the clause; C wraps the clause in bold and can
+ * appear MID-SENTENCE, after an earlier clause already closed. Each one was
+ * found by measuring, and each was missing from the rule that preceded it:
+ *
+ *   - ignoring B dropped 4 of 16 claims (`middleware-patterns`,
+ *     `observability-patterns`, `rag-custom-pgvector`, `structured-output`);
+ *   - ignoring C dropped 2 paths from `llm-runtime-defaults` — 25 instead of 27.
+ *
+ * READ THE SHAPE OF THAT SECOND MISS, because it is why counting entries is not
+ * enough: `llm-runtime-defaults` had two OTHER paths from a clause of form A, so
+ * it stayed in the "16 entries with proof" bucket either way. No counter moved,
+ * `--check` stayed green, exit 0. The only ruler that saw it is the SUM of
+ * paths. A canary that pins entry counts would have gone green over it — which
+ * is why `standards-registry.test.js` pins the paths themselves, written out by
+ * hand, and not a total produced by this function.
+ *
+ * The DENIALS must stay empty, and they are the majority (61 of the 77 headers
+ * derive to `[]`; 16 say some variant of "sem cláusula `provado por`" or
+ * "NÃO carimba `provado por`"). Three properties keep them out without a
+ * blacklist of prose:
+ *
+ *   1. a path must contain a `/` — so "`provado por`. Os nomes" and
+ *      "`provado por`: o ai-kit" match nothing;
+ *   2. a path must be CLOSED BY A BACKTICK — so prose that merely follows the
+ *      clause ("para a **ordem do pipeline**") cannot be mistaken for a path;
+ *   3. the clause must not be the tail of a LONGER word — `aprovado por` and
+ *      `comprovado por` are different claims. The corpus already contains
+ *      "aprovado por lucas@…" inside a code sample, so this is a live shape,
+ *      not a hypothetical.
+ *
+ * @type {RegExp}
+ */
+export const PROVED_BY_TRIGGER_RE = /(?:^|[^a-zA-Z])provado por/gi;
+
+/**
+ * One path token after the clause, plus the separator that may precede it:
+ * whitespace, backtick, `,`, `;`, the word `e`, and the markdown emphasis
+ * characters `*` and `_`. The emphasis characters are in the class because of
+ * typesetting C — without them, `**provado por**` armed the trigger and then
+ * matched no path at all, losing both of its files in silence.
+ *
+ * Anchored: it only ever reads from the cursor, so prose ends the scan instead
+ * of being searched through.
+ *
+ * @type {RegExp}
+ */
+export const PROVED_BY_PATH_RE =
+  /^[\s`,;*_]*(?:\be\b[\s`,;*_]*)?([A-Za-z0-9_.][A-Za-z0-9_.\-]*(?:\/[A-Za-z0-9_.\-]*)+)`/;
+
+/**
+ * Derive the list of files a standard claims to be *proved by*.
+ *
+ * Reads the SAME header {@link parseVerifiedAgainst} reads — deliberately, and
+ * from this module, because a second regex over the same sentence in
+ * `scripts/generate-standards-registry.js` is precisely the drift the module
+ * docblock opens with.
+ *
+ * @param {string} verifiedAgainst - The subject captured by
+ *   {@link parseVerifiedAgainst} (group 1), not the whole markdown file.
+ * @returns {string[]} Paths in declaration order, de-duplicated. `[]` means
+ *   "the header was read and declares no proof" — a documental verification —
+ *   never "not asked". The caller distinguishes the two by whether the header
+ *   parsed at all.
+ */
+export function deriveProvedBy(verifiedAgainst) {
+  if (typeof verifiedAgainst !== 'string' || verifiedAgainst.length === 0) return [];
+  const paths = [];
+  const trigger = new RegExp(PROVED_BY_TRIGGER_RE.source, PROVED_BY_TRIGGER_RE.flags);
+  let clause;
+  while ((clause = trigger.exec(verifiedAgainst)) !== null) {
+    let rest = verifiedAgainst.slice(clause.index + clause[0].length);
+    let hit;
+    while ((hit = PROVED_BY_PATH_RE.exec(rest)) !== null) {
+      if (!paths.includes(hit[1])) paths.push(hit[1]);
+      rest = rest.slice(hit[0].length);
+    }
+  }
+  return paths;
+}
+
+/**
+ * Count unresolved `// VERIFY` markers that sit INSIDE a fenced code block.
+ *
+ * The fence rule is what separates a real marker from prose that merely quotes
+ * one (`marcados \`// VERIFY:\` no código`). It lives here, next to the regex,
+ * so every consumer counts the same thing.
+ *
+ * @param {string} text - Full markdown text of the standard.
+ * @returns {number}
+ */
+export function countVerifyMarkers(text) {
+  if (typeof text !== 'string' || text.length === 0) return 0;
+  let inFence = false;
+  let count = 0;
+  for (const line of text.split('\n')) {
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence && VERIFY_MARKER_RE.test(line)) count++;
+  }
+  return count;
+}
+
+/**
+ * Read and parse `framework/ai-pin.json`.
+ *
+ * Throws — never falls back to a default — when the pin is missing or invalid:
+ * without a pin there is no ruler, and pretending there is one is the original
+ * defect this feature removes. The message names the file so the failure is
+ * diagnosable from a CI log alone.
+ *
+ * @param {string} [root=DEFAULT_ROOT] - Repository root that contains `framework/`.
+ * @returns {{ pinnedAt: string, source: string, targetFramework: string, sdk: string,
+ *             packages: Record<string, {version: string, published: string, role: string}>,
+ *             toolchain: Record<string, {version: string}> }}
+ * @throws {Error} When the file is absent or is not valid JSON.
+ */
+export function readAiPin(root = DEFAULT_ROOT) {
+  const pinPath = join(root, AI_PIN_RELATIVE);
+  if (!existsSync(pinPath)) {
+    throw new Error(`ai-pin.json não encontrado em ${pinPath} — sem pin não há régua de frescor.`);
+  }
+  try {
+    return JSON.parse(readFileSync(pinPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`ai-pin.json inválido em ${pinPath}: ${err.message}`);
+  }
+}
+
+/** Parse an ISO calendar date into a UTC epoch, timezone-independent. */
+function isoToUtc(value, label) {
+  const m = typeof value === 'string' ? ISO_DATE_RE.exec(value) : null;
+  if (!m) {
+    throw new TypeError(`${label} deve ser uma data ISO YYYY-MM-DD, recebido ${JSON.stringify(value)}`);
+  }
+  return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+}
+
+/**
+ * Age of a standard's verification, in whole days, measured against the pin.
+ *
+ * Both dates are read as UTC calendar days, so the result does not depend on
+ * the runner's timezone. The value is NEGATIVE when the standard is newer than
+ * the pin — the caller must treat that as a PIN error (a `pinnedAt` in the
+ * future), never as a fresh standard: otherwise every standard could be
+ * "renewed" by editing one date.
+ *
+ * @param {string} lastVerified - ISO date from the standard's header.
+ * @param {string} pinnedAt - ISO date from `framework/ai-pin.json`.
+ * @returns {number} Whole days between the two, possibly negative.
+ * @throws {TypeError} When either argument is not an ISO date.
+ */
+export function ageInDaysAgainstPin(lastVerified, pinnedAt) {
+  const verified = isoToUtc(lastVerified, 'lastVerified');
+  const pinned = isoToUtc(pinnedAt, 'pinnedAt');
+  return Math.round((pinned - verified) / 86400000);
+}