@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -18,7 +18,7 @@ export class CiUsageError extends Error {}
 const NODE_KEYS = ['build', 'tests', 'validators', 'e2e'];
 
 function isVerifyResult(result) {
-  return Boolean(result) && ['pass', 'fail'].includes(result.status) && result.scope === 'feature'
+  return Boolean(result) && ['pass', 'fail'].includes(result.status)
     && NODE_KEYS.every((k) => typeof result.nodes?.[k]?.status === 'string');
 }
 
@@ -47,18 +47,19 @@ function dispatchWorkflow(root, workflow, branch) {
   }
 }
 
-/**
- * `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)
- */
+// 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);
+  if (!head) return null;
+  const dirty = uncommittedCode(root);
+  if (dirty === null || dirty.length > 0) return null;
+  return treeMovedSince(root, stamp.sha, head) ? null : stamp;
+}
+
+// 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 };

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

@@ -21,14 +21,8 @@ function gh(cwd, args, timeout = 15000) {
   return execFileSync(bin, [...prefix, ...args], { cwd, stdio: 'pipe', timeout }).toString();
 }
 
-/**
- * The workflow that can stand in for `verify {feature}`: it must call `morph-spec verify` AND
- * publish its JSON, because only that artifact becomes a stamp. A green run of any other
- * workflow (lint, deploy) proves nothing about the suite.
- *
- * @param {string} root
- * @returns {string|null} workflow file name, as `gh run list --workflow` takes it
- */
+// Must call `morph-spec verify` AND publish its JSON: only that artifact becomes a stamp, and a green
+// lint or deploy run proves nothing about the suite.
 export function findCiWorkflow(root) {
   const dir = join(root, CI_WORKFLOW_DIR);
   if (!existsSync(dir)) return null;
@@ -69,15 +63,7 @@ function ghAuthText(root) {
   return `${res.stdout ?? ''}${res.stderr ?? ''}`;
 }
 
-/**
- * Whether CI can answer for this feature, and why not. Never throws: every "no" is a reason the
- * caller prints before falling back to the local verify.
- *
- * @param {string} root - the feature's tree
- * @param {string} featureName
- * @param {object|null} config - `.morph/config/config.json`
- * @returns {{ ok: true, branch: string, https: boolean, scopes: string|null } | { ok: false, reason: string }}
- */
+/** Never throws: every "no" is a reason the caller prints before falling back to the local verify. */
 export function ciAvailability(root, featureName, config) {
   if (config?.project?.ci === false) return { ok: false, reason: 'project.ci = false no config.json' };
   const url = originUrl(root);
@@ -93,21 +79,14 @@ export function ciAvailability(root, featureName, config) {
   return { ok: true, branch, https: /^https?:/i.test(url), scopes };
 }
 
-/**
- * Creating a workflow file over HTTPS needs the token's `workflow` scope; without it GitHub
- * rejects the whole push. Unknown scopes (fine-grained token, SSH remote) are not a refusal.
- */
+// Creating a workflow file over HTTPS needs the token's `workflow` scope, or GitHub rejects the whole push.
+// Unknown scopes (fine-grained token, SSH remote) are not a refusal.
 export function workflowPushProblem({ https, scopes }) {
   if (!https || scopes === null) return null;
   return /\bworkflow\b/.test(scopes) ? null : 'o token do gh não tem o escopo "workflow" (gh auth refresh -s workflow)';
 }
 
-/**
- * Paths CI would not see: uncommitted or untracked files outside `.morph/`, plus the config,
- * which names the test commands.
- *
- * @returns {string[]|null} null when git did not answer
- */
+/** Uncommitted or untracked files outside `.morph/`, plus the config; null when git did not answer. */
 export function uncommittedCode(root) {
   let out;
   try {
@@ -138,10 +117,8 @@ export function listRuns(root, branch, workflow) {
   }
 }
 
-/**
- * The newest run over the same code as HEAD. `isCurrent` is a tree comparison, not SHA equality:
- * the evaluator and the archive commit only `.morph/`, and the workflow does not re-run for them.
- */
+// `isCurrent` compares trees, not SHAs: the review agents and the archive commit only `.morph/`,
+// and the workflow does not re-run for them.
 export function pickRun(runs, isCurrent) {
   return (runs || []).find((run) => !(run.status === 'completed' && NO_VERDICT.has(run.conclusion))
     && run.headSha && isCurrent(run.headSha)) ?? null;
@@ -160,12 +137,7 @@ export function downloadResult(root, runId) {
   }
 }
 
-/**
- * Polls until the run over the current tree completes. Never decides: the caller turns
- * `timeout`/`no-run`/`unknown` into "no CI proof", never into red.
- *
- * @returns {Promise<{ state: 'completed'|'timeout'|'no-run'|'unknown', run?: object }>}
- */
+/** Never decides: the caller turns `timeout`/`no-run`/`unknown` into "no CI proof", never into red. */
 export async function waitForRun(root, { branch, workflow, isCurrent, timeoutMs, appearMs, pollMs = 15000,
   sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, onPending = () => {}, list = listRuns }) {
   const start = now();

package/src/lib/ci/workflow-scaffold.js

@@ -56,16 +56,8 @@ const step = (name, dir, run) => [
   `        run: ${run}`,
 ];
 
-/**
- * The workflow `verify {f} --ci` relies on. Same judge as the local run: it calls the project's
- * pinned morph-spec, so the suite is whatever `project.tests` says, not a second definition here.
- * `.morph/` is out of the trigger (bookkeeping commits would cancel the run over the code) except
- * the config, which names the commands.
- *
- * @param {string} root
- * @param {object|null} config
- * @returns {string}
- */
+// Calls the project's pinned morph-spec, so the suite is whatever `project.tests` says. `.morph/` is out of
+// the trigger (bookkeeping commits would cancel the run over the code) except the config.
 export function renderCiWorkflow(root, config) {
   const packages = packageDirs(root, config);
   const lines = [

package/src/lib/detectors/claude-config-detector.js

@@ -1,24 +1,8 @@
-/**
- * @fileoverview Claude Config Detector
- *
- * Scans .claude/ settings and plugins for MCP servers, hooks, skills, and commands.
- * Used by mcp-setup and session-start hooks.
- *
- * @module detectors/claude-config-detector
- */
-
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
-/**
- * Plugin ids (`name@marketplace`) that are switched ON. User settings first, then
- * the project's; a later file overrides an earlier one, and `false` turns one off.
- *
- * @param {string} targetPath - Root path of the project
- * @param {string} [home] - Home directory holding `.claude/settings.json`
- * @returns {string[]}
- */
+// User settings first, then the project's: a later file overrides, and `false` turns a plugin off.
 export function readEnabledPlugins(targetPath, home = homedir()) {
   const merged = new Map();
   const files = [
@@ -32,17 +16,11 @@ export function readEnabledPlugins(targetPath, home = homedir()) {
       const map = JSON.parse(readFileSync(file, 'utf8').replace(/^/, '')).enabledPlugins;
       if (!map || typeof map !== 'object') continue;
       for (const [id, on] of Object.entries(map)) merged.set(id, on === true);
-    } catch { /* invalid JSON */ }
+    } catch {}
   }
   return [...merged].filter(([, on]) => on).map(([id]) => id);
 }
 
-/**
- * Detect Claude Code configuration for a project.
- *
- * @param {string} targetPath - Root path of the project
- * @returns {{ plugins: string[], enabledPlugins: string[], mcpServers: Array<{name: string, config: Object}>, customSkills: string[], customCommands: string[], hooks: string[] }}
- */
 export function detectClaudeConfig(targetPath) {
   const result = {
     plugins: [],
@@ -58,7 +36,6 @@ export function detectClaudeConfig(targetPath) {
   const mcpJsonNames = new Set();
 
   try {
-    // ── MCP Servers from .mcp.json (primary — Claude Code reads this) ───────
     const mcpJsonPath = join(targetPath, '.mcp.json');
     if (existsSync(mcpJsonPath)) {
       try {
@@ -68,10 +45,9 @@ export function detectClaudeConfig(targetPath) {
           result.mcpServers.push({ name, config });
           mcpJsonNames.add(name);
         }
-      } catch { /* invalid JSON */ }
+      } catch {}
     }
 
-    // ── MCP Servers + hooks from settings (legacy + hooks/permissions) ───────
     const settingsPaths = [
       join(targetPath, '.claude', 'settings.json'),
       join(targetPath, '.claude', 'settings.local.json'),
@@ -81,19 +57,18 @@ export function detectClaudeConfig(targetPath) {
       if (existsSync(sp)) {
         try {
           const settings = JSON.parse(readFileSync(sp, 'utf8'));
-          // Legacy MCP entries — skip if already in .mcp.json, but allow later settings files to override earlier ones
+          // Legacy entries: .mcp.json wins; among settings files, the later one wins.
           const mcps = settings.mcpServers || {};
           for (const [name, config] of Object.entries(mcps)) {
-            if (mcpJsonNames.has(name)) continue; // .mcp.json takes priority
+            if (mcpJsonNames.has(name)) continue;
             const idx = result.mcpServers.findIndex(m => m.name === name);
             if (idx >= 0) {
-              result.mcpServers[idx] = { name, config }; // later file wins
+              result.mcpServers[idx] = { name, config };
             } else {
               result.mcpServers.push({ name, config });
             }
           }
 
-          // Collect hooks
           if (settings.hooks) {
             for (const [event, eventHooks] of Object.entries(settings.hooks)) {
               for (const group of (Array.isArray(eventHooks) ? eventHooks : [])) {
@@ -103,60 +78,43 @@ export function detectClaudeConfig(targetPath) {
               }
             }
           }
-        } catch { /* invalid JSON */ }
+        } catch {}
       }
     }
 
-    // ── Plugins from global config ──────────────────────────────────────────
     const pluginsPath = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
     if (existsSync(pluginsPath)) {
       try {
         const pluginsData = JSON.parse(readFileSync(pluginsPath, 'utf8'));
         const plugins = pluginsData.plugins || {};
         result.plugins = Object.keys(plugins);
-      } catch { /* invalid JSON */ }
+      } catch {}
     }
 
-    // ── Custom skills ───────────────────────────────────────────────────────
     const skillsPath = join(targetPath, '.claude', 'skills');
     if (existsSync(skillsPath)) {
       try {
         result.customSkills = readdirSync(skillsPath).filter(f => !f.startsWith('.'));
-      } catch { /* ignore */ }
+      } catch {}
     }
 
-    // ── Custom commands ─────────────────────────────────────────────────────
     const commandsPath = join(targetPath, '.claude', 'commands');
     if (existsSync(commandsPath)) {
       try {
         result.customCommands = readdirSync(commandsPath).filter(f => f.endsWith('.md'));
-      } catch { /* ignore */ }
+      } catch {}
     }
   } catch {
-    // Fail-safe
   }
 
   return result;
 }
 
-/**
- * Cross-reference configured MCPs with the MCP registry's phase matrix.
- *
- * `phaseMatrix` and `currentPhase` default rather than being required: the
- * `init` caller passed only `mcpServers`, so `phaseMatrix[currentPhase]` threw
- * a TypeError that `init`'s outer catch swallowed as
- * "Claude config detection skipped" — taking `saveIntegrations` and
- * `generateSettings` down with it, since both run after this line.
- *
- * @param {Array<{name: string}>} mcpServers - Detected MCP server list
- * @param {Object} [phaseMatrix] - From framework/mcp/registry.json → phaseMatrix
- * @param {string} [currentPhase] - Phase to look up; omit for every phase
- * @returns {{ available: string[], recommended: string[], missing: string[] }}
- */
+// `phaseMatrix`/`currentPhase` default: `init` passes only `mcpServers`, and a throw here was
+// swallowed by its outer catch, skipping the steps after it.
 export function mapMcpsToPhases(mcpServers, phaseMatrix = {}, currentPhase = null) {
   const configuredNames = new Set((mcpServers || []).map(m => m.name.toLowerCase()));
-  // No phase asked for → the union across every phase, deduped. That is what a
-  // caller showing "which of my MCPs this framework uses" wants.
+  // No phase asked for → the union across every phase, deduped.
   const recommended = currentPhase
     ? (phaseMatrix[currentPhase] || [])
     : [...new Set(Object.values(phaseMatrix).flat())];
@@ -168,19 +126,6 @@ export function mapMcpsToPhases(mcpServers, phaseMatrix = {}, currentPhase = nul
   };
 }
 
-/**
- * The MCP-by-phase table `init` prints: every phase that recommends at least
- * one of the MCPs this machine actually has configured.
- *
- * Separate from `mapMcpsToPhases` because the caller wants a per-phase
- * breakdown, not one phase's slice — reaching for the wrong one is what
- * produced `Object.entries()` over `{available, recommended, missing}` and a
- * `.map(m => m.name)` over plain strings.
- *
- * @param {Array<{name: string}>} mcpServers
- * @param {Object} phaseMatrix
- * @returns {Array<{phase: string, available: string[]}>} phases with ≥1 match
- */
 export function mcpAvailabilityByPhase(mcpServers, phaseMatrix = {}) {
   return Object.keys(phaseMatrix)
     .map(phase => ({
@@ -190,12 +135,6 @@ export function mcpAvailabilityByPhase(mcpServers, phaseMatrix = {}) {
     .filter(({ available }) => available.length > 0);
 }
 
-/**
- * Format a human-readable one-liner summary of detected config.
- *
- * @param {{ plugins: string[], mcpServers: Array<{name: string}> }} config
- * @returns {string}
- */
 export function formatConfigSummary(config) {
   const parts = [];
   if (config.mcpServers.length > 0) {