@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/dashboard/scanner/skills-scanner.js

@@ -1,7 +1,7 @@
 import { readFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 
-/** One-line `key: value` frontmatter. CRLF-safe: a checkout with autocrlf is still read. */
+/** CRLF-safe: a checkout with autocrlf is still read. */
 export function parseFrontmatter(content) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (!match) return {};
@@ -21,19 +21,9 @@ export function parseFrontmatter(content) {
 const FENCE = /^(\s*)```/;
 const DISPATCH_HINT = /dispatch|despach|subagent_type|Template do prompt/i;
 const PERSONA_REF = /morph-(\{id\}|\{task\.agent\}|[a-z][a-z-]*[a-z])/g;
-/** Words after `morph-` that are skills or CLI verbs, never personas. */
-/** Claude Code's own sub-agents: dispatched by skills, but not personas of agents.json. */
 const BUILTIN_AGENT = /`(Explore|general-purpose|Plan)`/g;
 const NOT_PERSONA = /^(spec|proposal|brainstorming|stack-scan|uiux|plan|implement|apply|review|eval|hotfix|standards|media|task)$/;
 
-/**
- * The prompts a skill tells the orchestrator to send to a sub-agent: fenced
- * blocks that are either written as a dispatch (`dispatch Agent (…)`) or sit
- * right under a line about dispatching. Each carries the personas it names —
- * `generic` when the template is `morph-{id}` (any implementer).
- *
- * @returns {Array<{ index: number, personas: string[], generic: boolean, builtin: string[], context: string, text: string }>}
- */
 export function extractDispatchPrompts(content) {
   const lines = content.split(/\r?\n/);
   const out = [];
@@ -45,7 +35,7 @@ export function extractDispatchPrompts(content) {
     const body = lines.slice(i + 1, j);
     const text = body.map((l) => l.slice(Math.min(open[1].length, l.length - l.trimStart().length))).join('\n');
     // Only the sentence that introduces the block counts: a paragraph further up
-    // that mentions a dispatch (morph-apply's DAG example) is not this block's.
+    // that mentions a dispatch is not this block's.
     let k = i - 1;
     while (k >= 0 && lines[k].trim() === '') k--;
     const before = k >= 0 && i - k <= 2 ? lines[k] : '';

package/src/dashboard/scanner/standards-scanner.js

@@ -1,20 +1,17 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { personaStandardIds } from '../../utils/agents-installer.js';
+import { loadStandardsRegistry } from '../../lib/standards/registry.js';
 
 export function scanStandards(frameworkDir, agents) {
   const standardsJsonPath = join(frameworkDir, 'standards', 'STANDARDS.json');
   if (!existsSync(standardsJsonPath)) return { version: 'unknown', list: [] };
-  const sJson = JSON.parse(readFileSync(standardsJsonPath, 'utf8'));
+  const sJson = loadStandardsRegistry(standardsJsonPath);
   const refMap = {};
   for (const agent of agents) {
     for (const std of personaStandardIds(agent)) {
-      // agents.json stores standards as plain id STRINGS. Reading `std.id` off
-      // a string yields undefined, so every reference piled into refMap
-      // [undefined] and the lookup below missed all 60 — the Standards graph
-      // drew standards with no agent edge at all. The object form is the v4
-      // shape (`{ id, scope, priority }`); still accepted so a mixed or
-      // restored agents.json does not silently lose edges again.
+      // agents.json stores standards as id strings; the `{ id }` object form is
+      // still accepted so a mixed agents.json does not lose edges.
       const id = typeof std === 'string' ? std : std?.id;
       if (!id) continue;
       if (!refMap[id]) refMap[id] = [];

package/src/dashboard/vite-plugin-morph-data.js

@@ -21,14 +21,6 @@ function readBody(req) {
   });
 }
 
-/**
- * Two data paths:
- *   - `virtual:morph-data` — the framework's knowledge (agents, phases, skills,
- *     standards, rules, hooks, docs). Static for the life of the server.
- *   - `/api/morph/*` — the portfolio (`/projects`) and each project's features
- *     and activity (`/p/:id/…`), read on demand and pushed as `morph:changed`
- *     over the HMR socket when a project's `.morph/` changes.
- */
 export default function morphDataPlugin(frameworkDir, projectDir) {
   return {
     name: 'vite-plugin-morph-data',
@@ -43,11 +35,8 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
       const portfolio = createPortfolio({ launchDir: projectDir });
       const push = (data) => server.ws.send({ type: 'custom', event: 'morph:changed', data });
 
-      // Vite reloads the whole page for any changed .html it watches, even when
-      // handleHotUpdate returns [] (vite 6: no module matched + .html = full
-      // reload). A project's .morph/ carries .html design sources, and an agent
-      // writing one reloaded the dashboard under the person reading it. The
-      // dashboard's own code never lives under .morph/.
+      // Vite 6 full-reloads any changed .html it watches even when handleHotUpdate
+      // returns [], and a project's .morph/ carries .html design sources.
       const clientHot = server.environments?.client?.hot;
       if (clientHot?.send) {
         const send = clientHot.send.bind(clientHot);
@@ -64,10 +53,8 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
         if (fresh.length) server.watcher.add(fresh);
       }
 
-      // Read the projects in the background, one at a time, so neither the first
-      // page nor the portfolio waits for a large project. Reading one blocks the
-      // event loop for seconds, so each step waits WARM_GAP_MS first: the reads
-      // a push (or an add) just caused are served before the next block.
+      // One project at a time, WARM_GAP_MS apart: a read blocks the event loop for
+      // seconds, and the reads a push just caused are served first.
       let warming = false;
       function warmSoon() {
         if (warming) return;
@@ -88,7 +75,6 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.setHeader('Cache-Control', 'no-store');
         res.end(JSON.stringify(out));
-        // The portfolio's list changed: watch and read any project just added.
         if (req.method !== 'GET' && status === 200) { watchNew(); push({ scope: 'projects' }); warmSoon(); }
       });
 
@@ -98,7 +84,7 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
       rescan.unref?.();
 
       const timers = new Map();
-      const changed = new Map(); // `${project}:${scope}` -> path -> watcher event, in the debounce window
+      const changed = new Map();
       const onFsEvent = (event, path) => {
         const scope = classifyChange(path);
         if (!scope) return;

package/src/lib/ai/ai-checks.js

@@ -1,26 +1,5 @@
-/**
- * ai-checks.js — o coletor das cinco checagens de `morph-spec doctor --ai`.
- *
- * Contrato de uma checagem:
- *
- *     { id, name, status: 'ok'|'warn'|'error'|'skip', reason?, findings: [], unverified?: [] }
- *
- * Duas regras que este módulo existe para tornar mecânicas:
- *
- * 1. **`status: 'skip'` sai com `reason` obrigatória.** "Não verificado" sem
- *    motivo é ruído — quem lê não consegue decidir se falta insumo ou se falta
- *    checagem. Um `skip` sem razão é bug deste arquivo, e há canário.
- * 2. **`null` de uma função de checagem é DESCONHECIDO, nunca "não achei
- *    nada".** `[]` é "perguntei e não achei" e vira `ok`. É a doutrina de
- *    `pr-index.js`, já viva no `doctor`.
- *
- * E uma proibição: **nada alcançável daqui escreve.** Os candidatos óbvios ao
- * erro — `scripts/generate-ai-pin-props.js` e
- * `scripts/generate-standards-registry.js` — escrevem por padrão e NÃO entram
- * no grafo de imports deste módulo. É a lição do T10 da #90, onde a auditoria
- * ia ALOCAR um bloco de porta ao auditar, inventando o estado que reportava.
- * O canário assere a lista de chamadas feitas, não só o retorno.
- */
+// `skip` sai com `reason` obrigatória, e `null` de uma checagem é DESCONHECIDO, nunca "não achei".
+// Nada alcançável daqui escreve: os geradores de `scripts/` ficam fora do grafo de imports.
 
 import { scanAiPackageRefs } from './ai-project-scan.js';
 import { resolveAiPin, auditPinDrift } from './pin-drift.js';
@@ -30,7 +9,6 @@ import { auditRenamedApi, auditPromptSource, renamedApiGate } from './code-audit
 /** Os cinco ids, na ordem em que o relatório os imprime. */
 export const AI_CHECK_IDS = ['pin-drift', 'removed-api', 'pricing-missing', 'api-per-alias', 'prompt-source'];
 
-/** Nome legível de cada checagem. */
 export const AI_CHECK_NAMES = {
   'pin-drift': 'pin × projeto (versões de pacote de IA)',
   'removed-api': 'API renomeada antes do 1.0 GA',
@@ -42,7 +20,6 @@ export const AI_CHECK_NAMES = {
 /** O pacote cuja versão gateia a checagem de API renomeada. */
 export const MAF_PACKAGE = 'Microsoft.Agents.AI';
 
-/** As dependências reais. Substituíveis inteiras ou em parte, por canário. */
 export function defaultAiDeps() {
   return {
     scanAiPackageRefs,
@@ -75,19 +52,8 @@ function skipAll(reason) {
   return AI_CHECK_IDS.map((id) => skip(id, reason));
 }
 
-/**
- * Roda as cinco checagens sobre um projeto.
- *
- * As três condições de silêncio total acontecem ANTES de qualquer leitura do
- * pin — e é essa ordem, não o retorno, que o canário assere: sem `.csproj`
- * alcançável, `resolveAiPin` não é sequer chamada.
- *
- * @param {string} targetPath - raiz do projeto
- * @param {object} [options]
- * @param {object|null} [options.config] - `.morph/config/config.json` já lido
- * @param {object} [options.deps] - substituição parcial de `defaultAiDeps()`
- * @returns {Array<{id: string, name: string, status: string, reason?: string, findings: Array}>}
- */
+// As condições de silêncio total acontecem ANTES de ler o pin: sem `.csproj` alcançável,
+// `resolveAiPin` nem é chamada.
 export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
   const d = { ...defaultAiDeps(), ...deps };
 
@@ -114,8 +80,7 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
   const unverified = scan.unreadable.slice();
   const checks = [];
 
-  // ── pin-drift ────────────────────────────────────────────────────────────
-  // Condição 2: sem pin resolvível, a checagem que depende dele sai skip.
+  // Sem pin resolvível, a checagem que depende dele sai skip.
   const pin = d.resolveAiPin(targetPath);
   if (!pin) {
     checks.push(skip('pin-drift', 'nenhum `ai-pin.json` resolvível (nem em `.morph/framework/`, nem '
@@ -127,7 +92,6 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
       : resolved('pin-drift', findings, { unverified }));
   }
 
-  // ── removed-api ──────────────────────────────────────────────────────────
   const maf = scan.packages.find((p) => p.name === MAF_PACKAGE) ?? null;
   const gate = d.renamedApiGate(maf);
   if (gate !== null) {
@@ -139,7 +103,6 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
       : resolved('removed-api', findings));
   }
 
-  // ── pricing-missing e api-per-alias ──────────────────────────────────────
   const registry = d.locateAiRegistry(targetPath, config);
   const noRegistry = 'nenhum registry de modelos encontrado — nem `project.ai.modelRegistry` no '
     + 'config, nem um `.json` com `defaultAlias` + mapa de aliases, nem uma seção `Pricing` num '
@@ -155,7 +118,6 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
       : noRegistry)
     : resolved('api-per-alias', perAlias));
 
-  // ── prompt-source ────────────────────────────────────────────────────────
   const prompts = d.auditPromptSource(targetPath);
   checks.push(prompts === null
     ? skip('prompt-source', 'nenhum `.cs` alcançável a partir desta raiz')
@@ -164,19 +126,12 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
   return checks;
 }
 
-/**
- * Código de saída do `doctor --ai`: 1 quando há ao menos um `error`, 0 caso
- * contrário. `warn` e `skip` NUNCA mudam o código de saída — só `pin-drift`
- * produz `error`, e só na faixa flutuante, a única classe com prejuízo medido.
- *
- * @param {Array<{status: string}>} checks
- * @returns {0|1}
- */
+/** `warn` e `skip` nunca mudam o código de saída: só `pin-drift` produz `error`, na faixa flutuante. */
 export function aiExitCode(checks) {
   return checks.some((c) => c.status === 'error') ? 1 : 0;
 }
 
-/** true quando NENHUMA checagem teve insumo — o relatório sai em uma linha. */
+/** true quando nenhuma checagem teve insumo: o relatório sai em uma linha. */
 export function allSkipped(checks) {
   return checks.length > 0 && checks.every((c) => c.status === 'skip');
 }

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;