@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/ai/ai-project-scan.js

@@ -1,28 +1,10 @@
-/**
- * ai-project-scan.js — varredura READ-ONLY dos `.csproj` / `Directory.Packages.props`
- * de um projeto .NET, para responder "o que este projeto declara sobre pacotes de IA?".
- *
- * Três invariantes deste módulo, todas cobradas por canário:
- *
- * 1. **Nada aqui escreve.** Nenhum import de `fs` que mute, nenhum `spawn`.
- *    A auditoria não pode inventar o estado que reporta — é a lição do T10 da
- *    #90, onde a auditoria de portas ia ALOCAR um bloco ao auditar.
- * 2. **`null` é DESCONHECIDO, `[]` é "perguntei e não achei".** Colapsar os
- *    dois é a doutrina que `src/lib/git/pr-index.js` já pinou neste repositório.
- *    Aqui: `scanAiPackageRefs` devolve `null` quando havia arquivos candidatos
- *    e NENHUM foi legível; devolve um resultado com `projectFiles: []` quando
- *    varreu e não achou `.csproj` nenhum.
- * 3. **Worktree é o checkout de OUTRA feature.** `worktrees/` e `.worktrees/`
- *    ficam fora da varredura pela mesma razão pinada em `test-runner.js`:
- *    varrê-los reporta sobre código fora da árvore avaliada. Os nomes vêm de
- *    `src/lib/worktree/dirs.js`, nunca duplicados aqui.
- */
+// Nada aqui escreve: a auditoria não pode inventar o estado que reporta. `null` é DESCONHECIDO,
+// `[]` é "perguntei e não achei". Worktrees ficam fora: são o checkout de outra feature.
 
 import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
 
-/** Diretórios que a varredura nunca desce. */
 export const SCAN_IGNORED_DIRS = new Set([
   'node_modules',
   'bin',
@@ -31,14 +13,8 @@ export const SCAN_IGNORED_DIRS = new Set([
   ...WORKTREE_DIR_NAMES,
 ]);
 
-/**
- * Prefixos de pacote NuGet que caracterizam "pacote de IA".
- *
- * Deliberadamente curto: a lista existe para decidir se há assunto (condição 3
- * do silêncio do `doctor --ai`), não para catalogar o ecossistema. Um pacote de
- * IA fora desta lista aparece na varredura como pacote comum e, se estiver no
- * pin, `pin-drift` o pega mesmo assim — o pin é a outra metade do predicado.
- */
+// Deliberadamente curto: decide se há assunto, não cataloga o ecossistema; um pacote de IA fora daqui
+// que esteja no pin ainda é pego por `pin-drift`.
 export const AI_PACKAGE_PREFIXES = [
   'Microsoft.Agents.AI',
   'Microsoft.Extensions.AI',
@@ -50,10 +26,6 @@ export const AI_PACKAGE_PREFIXES = [
   'Anthropic.',
 ];
 
-/**
- * @param {string} name - nome do pacote NuGet
- * @returns {boolean} true quando o nome casa com um dos prefixos de IA
- */
 export function isAiPackage(name) {
   if (typeof name !== 'string' || name.length === 0) return false;
   return AI_PACKAGE_PREFIXES.some(
@@ -61,22 +33,11 @@ export function isAiPackage(name) {
   );
 }
 
-/** Remove o BOM UTF-8 do início do texto (mesmo cuidado de `doctor.js` e `env.js`). */
 function stripBom(text) {
   return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
 
-/**
- * Checagem de boa-formação de XML suficiente para MSBuild, sem dependência nova.
- *
- * Não valida schema: valida que as tags fecham na ordem certa e que todo `<`
- * tem o seu `>`. É o predicado que separa "li o arquivo" de "não pude
- * perguntar" — e é ele que faz um `.csproj` truncado virar `unreadable` em vez
- * de virar "sem drift".
- *
- * @param {string} xml
- * @returns {boolean}
- */
+/** Tags fecham na ordem e todo `<` tem `>`: um `.csproj` truncado vira `unreadable`, não "sem drift". */
 export function isWellFormedXml(xml) {
   const stack = [];
   let i = 0;
@@ -121,7 +82,6 @@ export function isWellFormedXml(xml) {
   return stack.length === 0;
 }
 
-/** Todas as tags de um nome, com os atributos crus. */
 function* elements(xml, tagName) {
   const re = new RegExp(`<${tagName}\\b([^>]*?)(/?)>`, 'g');
   let m;
@@ -130,17 +90,13 @@ function* elements(xml, tagName) {
   }
 }
 
-/** Valor de um atributo dentro do texto cru de atributos de uma tag. */
 function attr(attrs, name) {
   const m = new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`, 'i').exec(attrs)
     || new RegExp(`\\b${name}\\s*=\\s*'([^']*)'`, 'i').exec(attrs);
   return m ? m[1].trim() : null;
 }
 
-/**
- * Elemento filho `<Version>x</Version>` de um `<PackageReference>` não
- * auto-fechado. Recebe o XML e o índice logo após a tag de abertura.
- */
+// Recebe o índice logo após a tag de abertura de um `<PackageReference>` não auto-fechado.
 function childVersion(xml, startIndex, tagName) {
   const close = xml.indexOf(`</${tagName}>`, startIndex);
   if (close === -1) return null;
@@ -149,18 +105,7 @@ function childVersion(xml, startIndex, tagName) {
   return m ? m[1].trim() : null;
 }
 
-/**
- * Classifica a string de versão declarada no projeto.
- *
- * - `fixed`      — `1.20.0` ou a forma de igualdade exata `[1.20.0]`
- * - `floating`   — contém `*`, ou é intervalo (`[1.0,)`, `[1.0,2.0)`, `(,2.0]`)
- * - `unresolved` — referência a propriedade MSBuild (`$(MafVersion)`): a
- *   varredura NÃO resolve propriedades, e chutar seria inventar o dado
- * - `absent`     — sem versão declarada e sem entrada de CPM
- *
- * @param {string|null} raw
- * @returns {{ kind: 'fixed'|'floating'|'unresolved'|'absent', value: string|null }}
- */
+/** `unresolved` é referência a propriedade MSBuild (`$(X)`): a varredura não resolve, e chutar inventaria o dado. */
 export function classifyVersion(raw) {
   if (raw === null || raw === undefined || String(raw).trim() === '') {
     return { kind: 'absent', value: null };
@@ -175,18 +120,7 @@ export function classifyVersion(raw) {
   return { kind: 'fixed', value };
 }
 
-/**
- * Coleta recursiva de arquivos que casam com um predicado, respeitando as
- * exclusões de `SCAN_IGNORED_DIRS`.
- *
- * Exportada porque `registry-audit.js` e `code-audit.js` precisam da MESMA
- * travessia com as MESMAS exclusões. Uma segunda cópia da lista de diretórios
- * ignorados é como um dos três volta a varrer `worktrees/` sozinho.
- *
- * @param {string} root
- * @param {(name: string, fullPath: string) => boolean} matches
- * @returns {string[]}
- */
+/** Exportada para que registry-audit e code-audit usem a mesma travessia com as mesmas exclusões. */
 export function collectProjectFiles(root, matches) {
   const out = [];
   if (!root || !existsSync(root)) return out;
@@ -194,7 +128,6 @@ export function collectProjectFiles(root, matches) {
   return out;
 }
 
-/** Coleta recursiva de arquivos que casam com um predicado, respeitando as exclusões. */
 function collectFiles(root, matches, out, depth = 0) {
   if (depth > 24) return;
   let entries;
@@ -208,8 +141,7 @@ function collectFiles(root, matches, out, depth = 0) {
     const full = join(root, name);
     let isDir = entry.isDirectory();
     if (entry.isSymbolicLink()) {
-      // Junction/symlink: pode apontar para fora da árvore (é assim que um
-      // worktree do Windows enxerga `.claude/`). Não descemos.
+      // Junction/symlink pode apontar para fora da árvore (assim um worktree do Windows enxerga `.claude/`).
       continue;
     }
     if (isDir) {
@@ -221,23 +153,8 @@ function collectFiles(root, matches, out, depth = 0) {
   }
 }
 
-/**
- * Varre `root` e devolve o que os projetos .NET declaram sobre pacotes.
- *
- * Sem limite de 10 arquivos (o de `scanStackDependencies`, que é do relatório
- * de arquitetura e tem outro consumidor): uma solução .NET real tem dezenas de
- * `.csproj`, e cortar em 10 é reportar sobre uma amostra chamando-a de todo.
- *
- * @param {string} root - raiz da varredura (o projeto)
- * @returns {null | {
- *   projectFiles: string[],
- *   cpmFiles: string[],
- *   unreadable: string[],
- *   packages: Array<{ name: string, file: string, ai: boolean,
- *                     version: string|null, versionKind: string,
- *                     declared: string|null, fromCpm: boolean }>
- * }} `null` = não pude perguntar (havia candidatos e nenhum era legível).
- */
+// Sem limite de arquivos: cortar uma solução real é reportar sobre uma amostra chamando-a de todo.
+// `null` = havia candidatos e nenhum era legível.
 export function scanAiPackageRefs(root) {
   if (!root || !existsSync(root)) return null;
   try {
@@ -280,7 +197,7 @@ export function scanAiPackageRefs(root) {
   }
 
   // Central Package Management primeiro: um PackageReference sem Version num
-  // projeto com CPM não é achado de versão ausente (UC-24 A1).
+  // projeto com CPM não é achado de versão ausente.
   const cpm = new Map();
   for (const file of cpmFiles) {
     const xml = readable.get(file);
@@ -319,28 +236,17 @@ export function scanAiPackageRefs(root) {
     }
   }
 
-  // Um Directory.Packages.props com PackageVersion de pacote de IA e nenhum
-  // .csproj que o referencie ainda declara a intenção — mas não é uso, e este
-  // módulo reporta declaração de uso. Fica de fora, de propósito.
+  // PackageVersion de IA sem .csproj que o referencie declara intenção, não uso: fica de fora.
 
   return { projectFiles, cpmFiles, unreadable, packages };
 }
 
-/**
- * Versão declarada de um pacote específico, ou `null` quando o projeto não a
- * declara de forma resolvível. Usado pelo gate do `removed-api` (só roda com
- * `Microsoft.Agents.AI` >= 1.0) e pelo relatório.
- *
- * @param {ReturnType<typeof scanAiPackageRefs>} scan
- * @param {string} name
- * @returns {{ name: string, version: string|null, versionKind: string, declared: string|null, file: string } | null}
- */
+/** `null` quando o projeto não declara o pacote de forma resolvível. */
 export function findPackage(scan, name) {
   if (!scan || !Array.isArray(scan.packages)) return null;
   return scan.packages.find((p) => p.name === name) ?? null;
 }
 
-/** Nomes de arquivo (sem diretório) dos projetos varridos — para mensagens. */
 export function projectFileNames(scan) {
   if (!scan) return [];
   return scan.projectFiles.map((f) => basename(f));

package/src/lib/ai/code-audit.js

@@ -1,26 +1,6 @@
-/**
- * code-audit.js — duas varreduras sobre os `.cs` do projeto.
- *
- *   (a) `removed-api`  — nomes renomeados ANTES do 1.0 GA do `Microsoft.Agents.AI`
- *   (b) `prompt-source` — `Instructions` recebendo literal de string no ponto de
- *                         construção do agente
- *
- * Nenhuma das duas é grep cego, e as duas são `warn`:
- *
- * - A #93 apurou, e o standard `ai-agents/agent-session.md` registra, que
- *   `AgentThread` → `AgentSession` e `GetNewThread()` → `CreateSessionAsync()`
- *   aconteceram no ciclo PRÉ-GA. Dentro do `Microsoft.Agents.AI` >= 1.0 os
- *   nomes antigos são nomes mortos — mas o MESMO identificador pertence a
- *   outros SDKs de agente na mesma solução, e é por isso que o achado é aviso
- *   e a mensagem manda CONFERIR a qual cliente a chamada pertence, em vez de
- *   afirmar defeito. Sem o pacote declarado em >= 1.0 a checagem nem roda.
- *
- * - O `prompt-source` é deliberadamente conservador: acusa só o literal no
- *   ponto de construção. Leitura de arquivo, banco, configuração ou constante
- *   nomeada não é acusada. Falso negativo é aceitável; falso positivo não —
- *   uma checagem que grita em código correto é desligada pelo usuário na
- *   primeira semana.
- */
+// As duas checagens são `warn`: o nome renomeado no ciclo pré-GA é o mesmo identificador de outros SDKs
+// de agente, então a mensagem manda conferir. `prompt-source` acusa só o literal no ponto de construção:
+// falso negativo é aceitável, falso positivo faz o usuário desligar a checagem.
 
 import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
@@ -40,22 +20,11 @@ function lineOf(text, index) {
   return line;
 }
 
-/** Todos os `.cs` do projeto, com as mesmas exclusões da varredura de `.csproj`. */
 export function collectCsharpFiles(root) {
   return collectProjectFiles(root, (name) => name.toLowerCase().endsWith('.cs'));
 }
 
-/**
- * Menor major que a versão declarada pode assumir, ou `null` quando a
- * declaração não permite decidir.
- *
- * `1.0.*` e `[1.0,)` têm limite inferior 1 — sobem, nunca descem. `$(Prop)` e
- * versão ausente NÃO permitem decidir, e decidir mesmo assim seria inventar o
- * dado que a checagem reporta.
- *
- * @param {{ declared: string|null, versionKind: string }|null} pkg
- * @returns {number|null}
- */
+/** `null` quando a declaração não permite decidir (`$(Prop)`, ausente): decidir inventaria o dado. */
 export function lowerBoundMajor(pkg) {
   if (!pkg) return null;
   if (pkg.versionKind === 'unresolved' || pkg.versionKind === 'absent') return null;
@@ -66,12 +35,7 @@ export function lowerBoundMajor(pkg) {
   return m ? Number(m[1]) : null;
 }
 
-/**
- * Por que o `removed-api` NÃO roda, quando não roda.
- *
- * @param {{ declared: string|null, versionKind: string }|null} mafPackage
- * @returns {string|null} razão do "não verificado", ou `null` quando pode rodar
- */
+/** A razão do "não verificado", ou `null` quando pode rodar. */
 export function renamedApiGate(mafPackage) {
   if (!mafPackage) {
     return 'o projeto não declara `Microsoft.Agents.AI` — os nomes antigos não pertencem a este código';
@@ -88,14 +52,7 @@ export function renamedApiGate(mafPackage) {
   return null;
 }
 
-/**
- * (a) Uso de API renomeada antes do 1.0 GA.
- *
- * @param {string} root
- * @param {{ mafPackage?: object|null }} [options]
- * @returns {null | Array<{ id: string, severity: 'warn', symbol: string, file: string, line: number, message: string }>}
- *   `null` = não pude perguntar (gate fechado ou raiz ilegível).
- */
+/** `null` = não pude perguntar (gate fechado ou raiz ilegível). */
 export function auditRenamedApi(root, { mafPackage = null } = {}) {
   if (renamedApiGate(mafPackage) !== null) return null;
 
@@ -131,22 +88,9 @@ export function auditRenamedApi(root, { mafPackage = null } = {}) {
   return findings;
 }
 
-/**
- * `Instructions` recebendo literal de string no ponto de construção.
- *
- * Casa `Instructions = "…"`, `Instructions = @"…"`, `Instructions = $"…"`,
- * `Instructions = """…"""` e o argumento nomeado `instructions: "…"`.
- * NÃO casa atribuição de variável, chamada, `await`, constante nomeada nem
- * literal dentro de comentário.
- */
+// NÃO casa atribuição de variável, chamada, `await`, constante nomeada nem literal dentro de comentário.
 const INSTRUCTIONS_LITERAL_RE = /(?<![\w."])(?:Instructions\s*=(?!=)|instructions\s*:)\s*(?:[$@]){0,2}"/g;
 
-/**
- * (b) Prompt sem fonte declarada.
- *
- * @param {string} root
- * @returns {null | Array<{ id: string, severity: 'warn', file: string, line: number, message: string }>}
- */
 export function auditPromptSource(root) {
   const files = collectCsharpFiles(root);
   if (files.length === 0) return null;

package/src/lib/ai/pin-drift.js

@@ -1,70 +1,27 @@
-/**
- * pin-drift.js — o pin de pacotes de IA (`framework/ai-pin.json`) contra o que
- * o `.csproj` do projeto declara.
- *
- * É a ÚNICA das cinco checagens do `doctor --ai` que produz `error`, e só na
- * faixa flutuante. O motivo é prejuízo medido, não estética: uma faixa `2.*`
- * sobe sozinha para uma versão com assinatura mudada e o `MissingMethodException`
- * chega DEPOIS de a chamada ao modelo ter sido paga. As outras quatro checagens
- * informam — uma checagem que grita em código correto é desligada pelo usuário
- * na primeira semana.
- *
- * O pin é lido por `readAiPin` (#92), nunca por um segundo leitor: duas cópias
- * do mesmo fato divergem, e é para isso que a Dependency Matrix existe.
- */
+// Única checagem que produz `error`, e só na faixa flutuante: `2.*` sobe sozinha para uma assinatura mudada
+// e o `MissingMethodException` chega depois de a chamada ao modelo ter sido paga.
 
 import { join } from 'node:path';
 import { readAiPin } from '../standards/verified-against.js';
 
-/**
- * Resolve o pin para um projeto, sem NUNCA lançar.
- *
- * Ordem: (1) `<target>/.morph/framework/ai-pin.json` — a régua com que aquele
- * projeto foi instalado; (2) o pin do pacote da CLI. Nenhum dos dois resolve →
- * `null`, que o relatório traduz em "não verificado". Falta de régua é ausência
- * de dado, nunca defeito do projeto: é literalmente o estado de todo projeto
- * cujo framework é anterior ao pin.
- *
- * @param {string} targetPath - raiz do projeto
- * @returns {{ pinnedAt: string, packages: Record<string, {version: string}> } | null}
- */
+// O pin instalado no projeto, senão o do pacote da CLI; nenhum resolve → `null` ("não verificado"):
+// falta de régua é ausência de dado, nunca defeito do projeto.
 export function resolveAiPin(targetPath) {
   const roots = [];
   if (targetPath) roots.push(join(targetPath, '.morph'));
-  roots.push(undefined); // root default de readAiPin = pacote da CLI
+  roots.push(undefined);
 
   for (const root of roots) {
     try {
       const pin = root === undefined ? readAiPin() : readAiPin(root);
       if (pin && pin.packages && Object.keys(pin.packages).length > 0) return pin;
-    } catch {
-      // Ausente ou inválido nesta raiz — tenta a próxima.
-    }
+    } catch {}
   }
   return null;
 }
 
-/**
- * Compara a varredura do projeto com o pin.
- *
- * Três classes de achado, e a diferença entre elas é de quem é o defeito:
- *
- * | classe | severidade | de quem é |
- * |---|---|---|
- * | pacote do pin declarado com faixa flutuante | `error` | do projeto |
- * | pacote do pin declarado com versão fixa ≠ pin | `warn` | do projeto |
- * | pacote de IA presente no projeto e ausente do pin | `warn` | **do pin** (lacuna) |
- *
- * A terceira classe é descrita como lacuna do PIN de propósito: medido,
- * `Microsoft.Agents.AI.OpenAI` aparece em três repositórios do acervo e não
- * está no pin. Acusar o projeto ali seria acusar o certo pelo errado.
- *
- * @param {object} params
- * @param {ReturnType<import('./ai-project-scan.js').scanAiPackageRefs>} params.scan
- * @param {ReturnType<typeof resolveAiPin>} params.pin
- * @returns {null | Array<{ id: string, severity: 'error'|'warn', package: string, message: string }>}
- *   `null` = não pude perguntar (sem varredura ou sem pin).
- */
+// Pacote de IA presente no projeto e ausente do pin é lacuna do PIN, não do projeto.
+// `null` = não pude perguntar (sem varredura ou sem pin).
 export function auditPinDrift({ scan, pin } = {}) {
   if (!scan || !pin || !pin.packages) return null;
 

package/src/lib/ai/registry-audit.js

@@ -1,22 +1,5 @@
-/**
- * registry-audit.js — o registry de modelos do projeto: tarifa por alias e
- * protocolo (`api`) por alias.
- *
- * As duas perguntas saem do standard `ai-agents/providers/model-registry.md`,
- * não da memória de quem implementa:
- *
- *   - **tarifa por alias** — um alias sem tarifa é um custo que ninguém
- *     consegue prever antes de a chamada ser paga. O caso medido no acervo é o
- *     GHLBrain, cujo mapa `Pricing.Models` é literalmente `{}`.
- *   - **`api` por alias** — o standard mede, sobre o pin, que
- *     `AgentApi.Responses = 0`, ou seja `default(AgentApi)` é Responses, e que
- *     `ModelRegistry.ReadApi` devolve `AgentApi.Responses` quando o campo está
- *     ausente. A ausência do campo, portanto, NÃO é defeito: é uma decisão
- *     tomada por omissão. O achado NOMEIA o default assumido e pede
- *     confirmação — nunca afirma defeito.
- *
- * Severidade: `warn` nas duas. Só `pin-drift` produz `error`.
- */
+// Ausência de `api` não é defeito: o default medido sobre o pin é Responses, então o achado nomeia o
+// default e pede confirmação. Severidade `warn`; só `pin-drift` produz `error`.
 
 import { readFileSync } from 'node:fs';
 import { existsSync } from 'node:fs';
@@ -24,22 +7,10 @@ import { isAbsolute, join, basename } from 'node:path';
 import { collectProjectFiles } from './ai-project-scan.js';
 import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
 
-/** Limite de tamanho para um JSON candidato (bytes de texto) — evita ler dumps. */
 const MAX_JSON_CHARS = 512 * 1024;
 
-/**
- * Lê um candidato a registry aceitando **JSONC**.
- *
- * Não é indulgência: é paridade com o leitor de produção. O exemplar canônico
- * `framework/templates/dotnet/ai-kit/src/Morph.AiKit/Providers/model-registry.v2.json`
- * — que diz na primeira linha "copie para `config/model-registry.json` no
- * projeto" — tem 20 linhas de `//`, e `ModelRegistry.FromJson` do kit declara
- * `CommentHandling = JsonCommentHandling.Skip` + `AllowTrailingCommas = true`.
- * Com `JSON.parse` cru, as duas checagens de registry saíam `skip` sobre a
- * ÚNICA forma que existem para auditar — e `skip` não muda o código de saída,
- * então o silêncio era total. A auditoria tem de enxergar a mesma forma que o
- * leitor de produção enxerga.
- */
+// JSONC por paridade com o leitor de produção (`ModelRegistry.FromJson` aceita comentário e vírgula
+// sobrando): com `JSON.parse` cru o exemplar canônico saía `skip`, e `skip` não muda o código de saída.
 function readJsonSafe(file) {
   try {
     const raw = readFileSync(file, 'utf8');
@@ -67,7 +38,7 @@ function asAliasSource(file, data) {
   return { file, aliases: data.aliases, defaultAlias: data.defaultAlias, data };
 }
 
-/** A forma medida no GHLBrain: a seção `Pricing` de um `appsettings*.json`. */
+/** A seção `Pricing` de um `appsettings*.json`. */
 function asPricingSource(file, data) {
   if (!isPlainObject(data)) return null;
   const pricing = data.Pricing ?? data.pricing;
@@ -77,19 +48,8 @@ function asPricingSource(file, data) {
   return { file, models };
 }
 
-/**
- * Localiza o registry de modelos do projeto.
- *
- * Ordem, primeira ocorrência ganha (spec §3.5):
- *   1. path declarado em `.morph/config/config.json → project.ai.modelRegistry`;
- *   2. um `*.json` cujo objeto raiz tenha `defaultAlias` **e** um mapa `aliases`;
- *   3. a seção `Pricing` de um `appsettings*.json`.
- *
- * @param {string} root - raiz do projeto
- * @param {object|null} config - conteúdo de `.morph/config/config.json`, se houver
- * @returns {null | { aliasSource: object|null, pricingSource: object|null }}
- *   `null` quando NENHUMA das três formas foi encontrada.
- */
+// Primeira forma ganha: o path de `project.ai.modelRegistry`, um `*.json` com `defaultAlias` e `aliases`,
+// ou a seção `Pricing` de um `appsettings*.json`. `null` sem nenhuma.
 export function locateAiRegistry(root, config = null) {
   let aliasSource = null;
   let pricingSource = null;
@@ -132,7 +92,6 @@ export function locateAiRegistry(root, config = null) {
   return { aliasSource, pricingSource };
 }
 
-/** Mapa de tarifas embutido no próprio registry de modelos, quando existir. */
 function extractPricingFromRegistry(file, data) {
   if (!isPlainObject(data)) return null;
   const pricing = data.pricing ?? data.Pricing;
@@ -153,40 +112,14 @@ function aliasHasWaiver(def) {
   return isPlainObject(def) && typeof def.pricingWaiver === 'string' && def.pricingWaiver.trim() !== '';
 }
 
-/**
- * O documento usa a forma **por alias** (`pricing` / `pricingWaiver` dentro de
- * cada alias) em vez da forma de mapa no topo?
- *
- * Basta UM alias declarar qualquer uma das duas: um documento meio-preenchido
- * ainda é um documento na forma v2, e os aliases que faltam é que são o achado.
- */
+// Basta um alias declarar `pricing` ou `pricingWaiver`: documento meio-preenchido ainda é forma por alias.
 export function usesPerAliasPricing(aliasSource) {
   if (!aliasSource) return false;
   return Object.values(aliasSource.aliases).some((d) => aliasHasPricing(d) || aliasHasWaiver(d));
 }
 
-/**
- * Todo alias do registry tem uma DECISÃO de tarifa?
- *
- * Duas formas, e a checagem cobra a que o documento usa:
- *
- * 1. **Por alias** (`model-registry.v2.json`, o exemplar que o framework manda
- *    copiar) — a REGRA DURA escrita no próprio exemplar e imposta por
- *    `ModelRegistry.ReadPricing`: *"todo alias declara `pricing` OU
- *    `pricingWaiver` — nunca os dois, nunca nenhum"*. Um `pricingWaiver` é uma
- *    tarifa **decidida**: a ausência está escrita, não esquecida, e acusá-la
- *    seria gritar em código correto.
- * 2. **Mapa no topo** (`pricing` na raiz, ou a seção `Pricing.Models` de um
- *    `appsettings*.json` — a forma medida no GHLBrain, cujo mapa é
- *    literalmente `{}`).
- *
- * Os achados de MAPA (`pricing-map-missing` / `pricing-map-empty`) só existem
- * na forma 2: num documento v2 não há mapa a faltar, e emitir o achado ali era
- * o primeiro dos seis falsos positivos sobre o exemplar canônico.
- *
- * @param {ReturnType<typeof locateAiRegistry>} registry
- * @returns {null | Array<{ id: string, severity: 'warn', alias?: string, message: string }>}
- */
+// Por alias, todo alias declara `pricing` OU `pricingWaiver`, nunca os dois, nunca nenhum (um waiver é
+// tarifa decidida). Os achados de mapa só existem na forma de mapa no topo.
 export function auditModelPricing(registry) {
   if (!registry) return null;
   const { aliasSource, pricingSource } = registry;
@@ -253,19 +186,7 @@ export function auditModelPricing(registry) {
   return findings;
 }
 
-/**
- * Todo alias declara `api`?
- *
- * O default do standard é **`responses`**: medido sobre o pin, `AgentApi.Responses = 0`
- * e `ModelRegistry.ReadApi` devolve Responses quando o campo está ausente. A mensagem
- * nomeia esse default e PEDE CONFIRMAÇÃO — a ausência do campo é uma decisão por
- * omissão, não um defeito. É a pergunta que o `ModelRegistry.cs` do ProspectPRO
- * documenta ter custado um bug.
- *
- * @param {ReturnType<typeof locateAiRegistry>} registry
- * @returns {null | Array<{ id: string, severity: 'warn', alias: string, message: string }>}
- *   `null` quando não há aliases para perguntar.
- */
+/** `null` quando não há aliases para perguntar. */
 export function auditApiPerAlias(registry) {
   if (!registry || !registry.aliasSource) return null;
   const findings = [];

package/src/lib/ci/ci-verify.js

@@ -47,13 +47,8 @@ function dispatchWorkflow(root, workflow, branch) {
   }
 }
 
-/**
- * When CI falls back to local, the last green feature stamp still proves the tree if nothing moved
- * since it by the gate's own staleness rule and nothing is uncommitted (treeMovedSince sees only
- * commits). A null sha or HEAD would read as "not moved", so both are required.
- *
- * @returns {object|null} the stamp to reuse, or null = run local
- */
+// The last green stamp still proves the tree if nothing moved since it and nothing is uncommitted
+// (treeMovedSince sees only commits). A null sha or HEAD would read as "not moved", so both are required.
 export function reusableLocalStamp(root, stamp) {
   if (stamp?.status !== 'pass' || !stamp.sha) return null;
   const head = getHeadSha(root);
@@ -63,18 +58,8 @@ export function reusableLocalStamp(root, stamp) {
   return treeMovedSince(root, stamp.sha, head) ? null : stamp;
 }
 
-/**
- * `verify {f} --ci`: the feature-scope proof, run by the project's CI over the pushed commit.
- * Every way CI cannot answer is `mode: 'local'` with the reason, and the caller runs the local
- * verify: no CI is never a pause. Only the uploaded `verify --json` becomes a result, so the
- * gate judges a CI run by the same stamp and the same rules as a local one.
- *
- * @returns {Promise<
- *   { mode: 'local', reason: string } |
- *   { mode: 'pending', reason: string, run: object|null } |
- *   { mode: 'ci', result: object, run: object, created: string|null }>}
- * @throws {CiUsageError} code CI would not see (uncommitted work)
- */
+// Every way CI cannot answer is `mode: 'local'` with the reason: no CI is never a pause. Only the
+// uploaded `verify --json` becomes a result, judged by the same stamp and rules as a local run.
 export async function runCiVerify(root, featureName, config, { log = () => {}, waitMs = CI_WAIT_MS, wait = waitForRun } = {}) {
   const avail = ciAvailability(root, featureName, config);
   if (!avail.ok) return { mode: 'local', reason: avail.reason };