@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/installers/effects.js

@@ -1,70 +1,12 @@
-/**
- * effects.js — o coletor de efeitos ÚNICO do caminho de instalação/atualização.
- *
- * A propriedade que faz o `--dry-run` ser honesto está numa frase:
- *
- *   > **o caminho real também emite.**
- *
- * Em modo normal cada verbo EXECUTA e registra; em `dryRun`, só registra. O
- * resumo impresso ao fim de uma execução real sai de `list()`, não de
- * contadores paralelos. A consequência é o ponto: um ponto de emissão
- * esquecido some das DUAS saídas ao mesmo tempo, e o resumo de uma execução
- * real fica visivelmente incompleto — o defeito aparece sem sequer usar o
- * `--dry-run`.
- *
- * **Não há segunda travessia.** Nenhum filtro, walker ou lista de payload é
- * reimplementado aqui. Os filtros que decidem o que instalar
- * (`shouldInstallSkill`, `agentEligible`, `shouldInstall`) já são puros e
- * continuam sendo os únicos. O anti-exemplar tem nome e mora neste
- * repositório: `checkAgentsDrift` funciona como preditor porque re-deriva o
- * conjunto elegível por conta própria e porque os dois lados chamam o mesmo
- * renderer puro. Estender essa forma para 9 payloads + hooks + merge de
- * settings + gitignore + índice do git é reimplementar o instalador inteiro e
- * depender de disciplina humana para mantê-los sincronizados.
- *
- * **Os verbos são SÍNCRONOS de propósito.** Metade dos instaladores que eles
- * atravessam (`installSkills`, `installAgents`, `installRulesForStack`) é
- * síncrona; um coletor assíncrono obrigaria a tornar `installRulesForStack`
- * async e a mudar a assinatura que `setup-infra`, `init` e os testes já usam.
- *
- * **O registro é a IDENTIDADE do efeito, nunca o conteúdo.** `writeFile` grava
- * `{ verb, target }`, não os bytes: `installClaudeHooks` carimba um
- * `generated_at` a cada execução, e comparar conteúdo faria o canário de
- * igualdade dry × real reprovar por causa do relógio.
- */
+// O caminho real também emite: o resumo de uma execução real sai de `list()`, então um ponto de
+// emissão esquecido some das duas saídas. Registra-se a identidade do efeito, nunca o conteúdo:
+// `installClaudeHooks` carimba `generated_at`, e comparar bytes reprovaria a igualdade dry × real.
 
 import fs from 'fs-extra';
 import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 
-/**
- * @typedef {Object} Effect
- * @property {string} verb   - ensureDir | remove | copyDir | copyFile | writeFile | writeJson | mergeJson | spawn | gitIndex
- * @property {string} target - o caminho (ou comando) sobre o qual o efeito age
- * @property {string} [from] - origem, para os verbos de cópia
- * @property {string} [detail] - qualificador estável (argumentos do spawn, operação do git)
- */
-
-/**
- * Cria um coletor de efeitos.
- *
- * @param {{ dryRun?: boolean }} [options]
- * @returns {{
- *   dryRun: boolean,
- *   ensureDir: (path: string) => void,
- *   remove: (path: string) => void,
- *   copyDir: (from: string, to: string) => void,
- *   copyFile: (from: string, to: string) => void,
- *   writeFile: (path: string, content: string) => void,
- *   writeJson: (path: string, data: object) => void,
- *   mergeJson: (path: string, patch: object) => void,
- *   spawn: (cmd: string, args: string[], options?: object) => object|null,
- *   gitIndex: (op: string, path: string, options?: object) => boolean,
- *   list: () => Effect[],
- * }}
- */
 export function createEffects({ dryRun = false } = {}) {
-  /** @type {Effect[]} */
   const effects = [];
 
   const record = (verb, target, extra = {}) => {
@@ -118,13 +60,7 @@ export function createEffects({ dryRun = false } = {}) {
       }
     },
 
-    /**
-     * Leitura + fusão rasa + escrita, como UM efeito.
-     *
-     * A leitura acontece nos dois modos (ler não muda nada); só a escrita é
-     * suprimida em dry. É assim que `~/.claude/settings.json` — um arquivo do
-     * usuário, FORA do projeto — é atualizado sem que o dry o toque.
-     */
+    // A leitura acontece nos dois modos; só a escrita é suprimida em dry.
     mergeJson(path, patch) {
       record('mergeJson', path);
       if (dryRun) return;
@@ -138,21 +74,9 @@ export function createEffects({ dryRun = false } = {}) {
       fs.writeJsonSync(path, { ...current, ...patch }, { spaces: 2 });
     },
 
-    /**
-     * @param {string} cmd
-     * @param {string[]} args
-     * @param {{ cwd?: string, dryRunArgs?: string[] }} [options]
-     *   `dryRunArgs` é a variante SÓ-LEITURA do mesmo comando (por exemplo
-     *   `--check`). Em dry ela é executada no lugar; sem ela, nada roda.
-     *   O REGISTRO é o mesmo nos dois modos: o efeito previsto é o comando
-     *   real, não a sua sonda.
-     */
+    // `dryRunArgs`: variante só-leitura do comando, executada no lugar em dry; o registro é o comando real.
     spawn(cmd, args = [], options = {}) {
-      // `args` viaja no registro ALÉM do `detail` legível. O `detail` é para
-      // humano; quebrá-lo por espaço para descobrir onde o spawn escreve é o
-      // bug que um caminho como `R:\Polymorphism Tech\...` produz em silêncio,
-      // e que o relatório mostrou pondo um efeito do PACOTE da CLI no grupo
-      // "no projeto".
+      // `args` viaja além do `detail`: quebrar o `detail` por espaço erra caminhos com espaço.
       record('spawn', cmd, { detail: args.join(' '), args: [...args] });
       const { cwd, dryRunArgs } = options;
       if (dryRun) {
@@ -162,11 +86,7 @@ export function createEffects({ dryRun = false } = {}) {
       return spawnSync(cmd, args, { cwd, encoding: 'utf8' });
     },
 
-    /**
-     * Mutação do índice do git (`git rm --cached`, etc.). A SONDA que decide
-     * se há o que fazer fica fora daqui de propósito: sondar é ler, e ler
-     * acontece nos dois modos.
-     */
+    // A sonda que decide se há o que fazer fica fora daqui: sondar é ler, e ler acontece nos dois modos.
     gitIndex(op, path, options = {}) {
       record('gitIndex', path, { detail: op });
       if (dryRun) return true;
@@ -182,12 +102,7 @@ export function createEffects({ dryRun = false } = {}) {
   };
 }
 
-/**
- * Coletor no-op-de-registro para chamadores que não passam um: executa
- * normalmente e registra numa lista descartada. Existe para que assinaturas
- * novas de `installSkills`/`installAgents`/`installRulesForStack` continuem
- * funcionando para `setup-infra` e `init` sem mudança de comportamento.
- */
+// Executa e registra numa lista descartada, para chamadores que não passam um coletor.
 export function realEffects() {
   return createEffects({ dryRun: false });
 }

package/src/lib/installers/mcp-installer.js

@@ -1,11 +1,3 @@
-/**
- * MCP Installer
- *
- * Core logic for installing and configuring MCP servers during morph-spec init
- * and via `morph-spec mcp setup`. Handles auto-installable (credential-free)
- * MCPs, prerequisite checking, credential collection, and setup guidance.
- */
-
 import { join } from 'path';
 import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
 import { execSync, spawn } from 'child_process';
@@ -13,10 +5,6 @@ import { homedir } from 'os';
 import { installMcpServers } from '../../utils/claude-settings-manager.js';
 import { mcpServerNames } from '../../utils/agents-installer.js';
 
-/**
- * Load the enhanced MCP registry (v3.0.0)
- * @returns {Object} Registry with install blocks
- */
 export function loadMcpRegistry() {
   const registryPath = join(
     import.meta.dirname, '..', '..', '..', 'framework', 'mcp', 'registry.json'
@@ -25,15 +13,7 @@ export function loadMcpRegistry() {
   return JSON.parse(raw);
 }
 
-/**
- * Filter MCPs by stack relevance
- * @param {Object} registry - Full MCP registry
- * @param {string} stack - Detected project stack (e.g., 'nextjs-neon', 'blazor')
- * @param {string[]} [integrations] - `project.integrations` (e.g., ['neon']). The
- *   detectors put a database or payment provider here, never in the stack string,
- *   so an MCP relevant to it (neon, asaas) is matched against this list too.
- * @returns {Object} Filtered map of mcpName → mcpEntry
- */
+// Detectors put a database or payment provider in `integrations`, never in the stack string.
 export function filterByStack(registry, stack, integrations = []) {
   const result = {};
   const normalizedStack = (stack || '').toLowerCase();
@@ -53,14 +33,7 @@ export function filterByStack(registry, stack, integrations = []) {
   return result;
 }
 
-/**
- * Match detected MCP servers against the registry
- * @param {Array} existingServers - From detectClaudeConfig().mcpServers
- * @param {Object} registry - MCP registry
- * @param {string[]} [enabledPlugins] - From detectClaudeConfig().enabledPlugins. A plugin
- *   that ships the server already runs it, and writing it to `.mcp.json` too starts it twice.
- * @returns {Object} Map of mcpName → { installed: true, source }
- */
+// A plugin that ships the server already runs it: writing it to `.mcp.json` too starts it twice.
 export function getInstalledMcps(existingServers, registry, enabledPlugins = []) {
   const installed = {};
   const registryNames = Object.keys(registry.mcps);
@@ -86,11 +59,6 @@ export function getInstalledMcps(existingServers, registry, enabledPlugins = [])
   return installed;
 }
 
-/**
- * Check if prerequisites are met for an MCP entry
- * @param {Object} mcpEntry - MCP entry from registry
- * @returns {Array} Array of { name, met, installUrl } for each prerequisite
- */
 export function checkPrerequisites(mcpEntry) {
   const prereqs = mcpEntry.install?.prerequisites || [];
   const results = [];
@@ -101,7 +69,6 @@ export function checkPrerequisites(mcpEntry) {
       execSync(prereq.checkCommand, { stdio: 'ignore', timeout: 5000 });
       met = true;
     } catch {
-      // Command failed or not found
     }
     results.push({
       name: prereq.name,
@@ -113,25 +80,13 @@ export function checkPrerequisites(mcpEntry) {
   return results;
 }
 
-/**
- * Check if an MCP config uses remote HTTP transport (no local process).
- * @param {Object} config - MCP server config
- * @returns {boolean}
- */
 export function isRemoteMcp(config) {
   return config.type === 'http' || config.url != null;
 }
 
-/**
- * Patch MCP config for the current platform.
- * On Windows, npx must be invoked via `cmd /c` to avoid ENOENT errors.
- * Registry already stores cmd/c format; this handles legacy configs that still use npx directly.
- * Remote HTTP MCPs are returned as-is (no local process to patch).
- * @param {Object} config - MCP server config { command, args, env? } or { type: "http", url }
- * @returns {Object} Patched config (new object, original unmodified)
- */
+// On Windows npx must run via `cmd /c` (ENOENT otherwise); the registry already stores that form,
+// this covers legacy configs.
 export function patchConfigForPlatform(config) {
-  // Remote MCPs need no platform patching
   if (isRemoteMcp(config)) return config;
   if (config.command !== 'npx') return config;
   return {
@@ -141,20 +96,12 @@ export function patchConfigForPlatform(config) {
   };
 }
 
-/**
- * Install auto-installable MCPs (no credentials, no prerequisites)
- * @param {string} targetPath - Project root directory
- * @param {Object} mcpsToInstall - Map of mcpName → mcpEntry
- * @returns {Promise<Object>} Result from installMcpServers
- */
 export async function installAutoMcps(targetPath, mcpsToInstall) {
   const servers = {};
 
   for (const [name, entry] of Object.entries(mcpsToInstall)) {
     let config = { ...entry.install.config };
-    // Remote MCPs don't have env to strip
     if (!isRemoteMcp(config)) {
-      // Only include env if it has actual values
       if (config.env && Object.values(config.env).every(v => !v)) {
         delete config.env;
       }
@@ -165,13 +112,6 @@ export async function installAutoMcps(targetPath, mcpsToInstall) {
   return installMcpServers(targetPath, servers);
 }
 
-/**
- * Install companion skills for MCPs that define them (e.g., Stitch agent skills).
- * Reads the `companionSkills` field from registry entries and runs the install command.
- * @param {Object} mcpsInstalled - Map of mcpName → mcpEntry that were just installed
- * @param {Function} exec - execSync function (for testing)
- * @returns {Array<{name: string, repo: string, success: boolean}>}
- */
 export function installCompanionSkills(mcpsInstalled, exec = execSync) {
   const results = [];
 
@@ -190,13 +130,6 @@ export function installCompanionSkills(mcpsInstalled, exec = execSync) {
   return results;
 }
 
-/**
- * Generate the Stitch OAuth proxy template script.
- * Cross-platform (Windows gcloud.cmd + Unix gcloud), fetch()-based,
- * with readline, session tracking, and graceful shutdown.
- * @param {string} gcpProject - GCP project ID for x-goog-user-project header
- * @returns {string} CJS proxy script content
- */
 export function getStitchProxyTemplate(gcpProject) {
   return `#!/usr/bin/env node
 /**
@@ -309,12 +242,6 @@ rl.on('close', () => { stdinClosed = true; maybeExit(); });
 `;
 }
 
-/**
- * Generate and write the Stitch OAuth proxy script to the target project.
- * @param {string} targetPath - Project root directory
- * @param {string} gcpProject - GCP project ID
- * @returns {{ proxyPath: string }} Path to the generated proxy script
- */
 export function generateStitchProxy(targetPath, gcpProject) {
   const claudeDir = join(targetPath, '.claude');
   if (!existsSync(claudeDir)) {
@@ -327,20 +254,12 @@ export function generateStitchProxy(targetPath, gcpProject) {
   return { proxyPath };
 }
 
-/**
- * Resolve the gcloud CLI binary path.
- * Checks: system PATH → bundled at ~/.stitch-mcp/ → null.
- * @param {Function} exec - execSync function (for testing)
- * @returns {{ gcloudPath: string|null, source: string }}
- */
 export function findGcloud(exec = execSync) {
-  // Try system PATH first
   try {
     exec('gcloud --version', { stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000 });
     return { gcloudPath: 'gcloud', source: 'system' };
-  } catch { /* not on PATH */ }
+  } catch {}
 
-  // Windows: try Cloud SDK default install location
   if (process.platform === 'win32') {
     const winPath = join(process.env.LOCALAPPDATA || '', 'Google', 'Cloud SDK', 'google-cloud-sdk', 'bin', 'gcloud.cmd');
     if (existsSync(winPath)) {
@@ -348,7 +267,6 @@ export function findGcloud(exec = execSync) {
     }
   }
 
-  // Try bundled at ~/.stitch-mcp/
   const bundledDir = join(homedir(), '.stitch-mcp');
   const bundledBin = process.platform === 'win32'
     ? join(bundledDir, 'google-cloud-sdk', 'bin', 'gcloud.cmd')
@@ -360,29 +278,10 @@ export function findGcloud(exec = execSync) {
   return { gcloudPath: null, source: 'not-found' };
 }
 
-/**
- * Fully automated Stitch MCP setup orchestrator.
- *
- * Steps:
- * 1. Find gcloud CLI
- * 2. Verify ADC credentials
- * 3. Detect GCP project
- * 4. Enable stitch.googleapis.com API
- * 5. Generate proxy script
- * 6. Install MCP config in .mcp.json
- * 7. Health-check the proxy
- *
- * @param {string} targetPath - Project root directory
- * @param {Object} options
- * @param {string} [options.gcpProject] - GCP project ID (auto-detected if omitted)
- * @param {Function} [options._exec] - execSync override for testing
- * @returns {Promise<Object>} Step-by-step results
- */
 export async function setupStitch(targetPath, options = {}) {
   const exec = options._exec || execSync;
   const steps = [];
 
-  // Step 1: Find gcloud
   const { gcloudPath, source: gcloudSource } = findGcloud(exec);
   if (!gcloudPath) {
     steps.push({ step: 'find-gcloud', success: false, error: 'gcloud CLI not found. Install from: https://cloud.google.com/sdk/docs/install' });
@@ -392,7 +291,6 @@ export async function setupStitch(targetPath, options = {}) {
 
   const gcloudCmd = gcloudPath.includes(' ') ? `"${gcloudPath}"` : gcloudPath;
 
-  // Step 2: Verify ADC credentials
   try {
     exec(`${gcloudCmd} auth application-default print-access-token`, {
       encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 15000
@@ -403,26 +301,23 @@ export async function setupStitch(targetPath, options = {}) {
     return { success: false, steps };
   }
 
-  // Step 3: Detect GCP project
   let gcpProject = options.gcpProject;
   if (!gcpProject) {
-    // Try config.json
     const configPath = join(targetPath, '.morph', 'config', 'config.json');
     if (existsSync(configPath)) {
       try {
         const config = JSON.parse(readFileSync(configPath, 'utf-8'));
         gcpProject = config.gcpProject || config.project?.gcpProject;
-      } catch { /* invalid config */ }
+      } catch {}
     }
   }
   if (!gcpProject) {
-    // Try gcloud config
     try {
       gcpProject = exec(`${gcloudCmd} config get-value project`, {
         encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000
       }).trim();
       if (!gcpProject || gcpProject === '(unset)') gcpProject = null;
-    } catch { /* gcloud config failed */ }
+    } catch {}
   }
   if (!gcpProject) {
     steps.push({ step: 'detect-project', success: false, error: 'Could not detect GCP project. Pass it explicitly or set via: gcloud config set project <id>' });
@@ -430,7 +325,6 @@ export async function setupStitch(targetPath, options = {}) {
   }
   steps.push({ step: 'detect-project', success: true, gcpProject });
 
-  // Step 4: Enable Stitch API
   try {
     exec(`${gcloudCmd} services enable stitch.googleapis.com --project=${gcpProject}`, {
       encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000
@@ -438,20 +332,17 @@ export async function setupStitch(targetPath, options = {}) {
     steps.push({ step: 'enable-api', success: true });
   } catch (err) {
     steps.push({ step: 'enable-api', success: false, error: `Failed to enable stitch API: ${err.message}` });
-    // Non-fatal — API might already be enabled and user may lack permissions to re-enable
+    // Non-fatal: the API may already be enabled and the user may lack permission to re-enable it.
   }
 
-  // Step 5: Generate proxy
   const { proxyPath } = generateStitchProxy(targetPath, gcpProject);
   steps.push({ step: 'generate-proxy', success: true, proxyPath });
 
-  // Step 6: Install MCP config in .mcp.json
   const mcpResult = await installMcpServers(targetPath, {
     stitch: { type: 'stdio', command: 'node', args: ['.claude/stitch-proxy.cjs'] }
   });
   steps.push({ step: 'install-mcp', success: true, added: mcpResult.added, skipped: mcpResult.skipped });
 
-  // Step 7: Health-check
   const healthResult = await healthCheckStitchProxy(proxyPath);
   steps.push({ step: 'health-check', ...healthResult });
 
@@ -462,11 +353,6 @@ export async function setupStitch(targetPath, options = {}) {
   return { success: allCriticalPassed, steps, gcpProject };
 }
 
-/**
- * Health-check the Stitch proxy by sending an MCP initialize handshake.
- * @param {string} proxyPath - Path to stitch-proxy.cjs
- * @returns {Promise<Object>} { success, protocolVersion?, error? }
- */
 export function healthCheckStitchProxy(proxyPath) {
   return new Promise((resolve) => {
     const initMsg = JSON.stringify({
@@ -492,7 +378,6 @@ export function healthCheckStitchProxy(proxyPath) {
 
     child.stdout.on('data', (data) => {
       output += data.toString();
-      // Check if we got a response
       const lines = output.split('\n').filter(l => l.trim());
       for (const line of lines) {
         try {
@@ -509,7 +394,7 @@ export function healthCheckStitchProxy(proxyPath) {
             resolve({ success: false, error: resp.error.message || 'MCP error' });
             return;
           }
-        } catch { /* not valid JSON yet */ }
+        } catch {}
       }
     });
 
@@ -530,38 +415,22 @@ export function healthCheckStitchProxy(proxyPath) {
       }
     });
 
-    // Send the initialize message
     child.stdin.write(initMsg + '\n');
     child.stdin.end();
   });
 }
 
-/**
- * Install a single MCP with provided credentials
- * @param {string} targetPath - Project root directory
- * @param {string} name - MCP name
- * @param {Object} mcpEntry - MCP entry from registry
- * @param {Object} credentialValues - Map of envVar → value
- * @returns {Promise<Object>} Result from installMcpServers
- */
 export async function installMcpWithCredentials(targetPath, name, mcpEntry, credentialValues) {
   const config = patchConfigForPlatform({ ...mcpEntry.install.config });
   config.env = { ...config.env, ...credentialValues };
   return installMcpServers(targetPath, { [name]: config });
 }
 
-/**
- * Generate setup instructions for a credential-requiring MCP
- * @param {string} name - MCP name
- * @param {Object} mcpEntry - MCP entry from registry
- * @returns {Object} { configSnippet, credentialUrls, cliCommand }
- */
 export function generateSetupInstructions(name, mcpEntry) {
   const config = mcpEntry.install.config;
   const credentials = mcpEntry.install.credentials || [];
   const setupGuide = mcpEntry.install.setupGuide;
 
-  // Remote HTTP MCPs — show claude mcp add command instead of config snippet
   if (isRemoteMcp(config)) {
     const configSnippet = JSON.stringify({ [name]: config }, null, 2);
     const credentialUrls = credentials.map(c => ({
@@ -577,7 +446,6 @@ export function generateSetupInstructions(name, mcpEntry) {
     };
   }
 
-  // Build the config snippet with placeholder values
   const snippetConfig = { ...config };
   if (credentials.length > 0) {
     snippetConfig.env = {};
@@ -601,17 +469,6 @@ export function generateSetupInstructions(name, mcpEntry) {
   };
 }
 
-/**
- * Full orchestrator for MCP setup during init or `mcp setup`
- * @param {string} targetPath - Project root directory
- * @param {string} stack - Detected project stack
- * @param {Array} existingMcps - From detectClaudeConfig().mcpServers
- * @param {Object} options
- * @param {boolean} options.autoOnly - Only handle auto-installable MCPs
- * @param {string[]} [options.integrations] - `project.integrations`, matched like the stack
- * @param {string[]} [options.enabledPlugins] - `detectClaudeConfig().enabledPlugins`
- * @returns {Object} { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing }
- */
 export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {}) {
   const registry = loadMcpRegistry();
   const relevant = filterByStack(registry, stack, options.integrations ?? []);
@@ -623,23 +480,19 @@ export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {
   const notRelevant = {};
   const prerequisitesMissing = {};
 
-  // Categorize all MCPs
   for (const [name, entry] of Object.entries(registry.mcps)) {
     if (!entry.install) continue;
 
-    // Check if already installed
     if (installed[name]) {
       alreadyInstalled[name] = { entry, source: installed[name].source };
       continue;
     }
 
-    // Check if relevant to stack
     if (!relevant[name]) {
       notRelevant[name] = entry;
       continue;
     }
 
-    // Check prerequisites
     const prereqResults = checkPrerequisites(entry);
     const unmetPrereqs = prereqResults.filter(p => !p.met);
     if (unmetPrereqs.length > 0) {
@@ -647,7 +500,6 @@ export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {
       continue;
     }
 
-    // Categorize by install type
     if (entry.install.autoInstall) {
       autoInstallable[name] = entry;
     } else if (!options.autoOnly) {
@@ -665,18 +517,11 @@ export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {
   };
 }
 
-/**
- * Format MCP status table for display
- * @param {Object} orchestration - Result from orchestrateMcpSetup
- * @param {Object} justInstalled - Map of names just installed during this run
- * @returns {Array<Object>} Array of { name, status, detail }
- */
 export function formatMcpStatusTable(orchestration, justInstalled = {}) {
   const rows = [];
 
   const { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing, registry } = orchestration;
 
-  // Installed during this run
   for (const [name, entry] of Object.entries(justInstalled)) {
     const mcpEntry = registry.mcps[name];
     rows.push({
@@ -686,7 +531,6 @@ export function formatMcpStatusTable(orchestration, justInstalled = {}) {
     });
   }
 
-  // Auto-installable but not yet installed (and not just-installed)
   for (const [name, entry] of Object.entries(autoInstallable)) {
     if (justInstalled[name]) continue;
     rows.push({
@@ -696,7 +540,6 @@ export function formatMcpStatusTable(orchestration, justInstalled = {}) {
     });
   }
 
-  // Already installed
   for (const [name, { source }] of Object.entries(alreadyInstalled)) {
     rows.push({
       name,
@@ -705,7 +548,6 @@ export function formatMcpStatusTable(orchestration, justInstalled = {}) {
     });
   }
 
-  // Needs manual setup
   for (const [name, entry] of Object.entries(needsManualSetup)) {
     rows.push({
       name,
@@ -714,7 +556,6 @@ export function formatMcpStatusTable(orchestration, justInstalled = {}) {
     });
   }
 
-  // Prerequisites missing
   for (const [name, { unmet }] of Object.entries(prerequisitesMissing)) {
     const missing = unmet.map(p => p.name).join(', ');
     rows.push({
@@ -724,7 +565,6 @@ export function formatMcpStatusTable(orchestration, justInstalled = {}) {
     });
   }
 
-  // Not relevant
   for (const [name] of Object.entries(notRelevant)) {
     rows.push({
       name,

package/src/lib/installers/memory-installer.js

@@ -1,15 +1,5 @@
-/**
- * Memory Installer — populates Claude Code persistent memory during `morph-spec init`.
- *
- * Writes two memory files (project + reference) plus an entry in MEMORY.md
- * so future Claude Code sessions enter pre-contextualized about the
- * morph-spec setup of this project.
- *
- * Memory location: ~/.claude/projects/<encoded-project-path>/memory/
- *
- * The path encoding mirrors Claude Code's own scheme: replace slashes and
- * colons with dashes. Tests can override via MORPH_MEMORY_ROOT env var.
- */
+// The path encoding mirrors Claude Code's scheme (slashes and colons become dashes);
+// MORPH_MEMORY_ROOT overrides the root in tests.
 
 import fs from 'fs-extra';
 import { join } from 'path';
@@ -49,7 +39,7 @@ metadata:
 
 | Command | Skill invoked |
 |---------|---------------|
-| \`/morph-proposal {feature}\` | \`Skill(morph-plan)\` — entrevista → plan.md → plan-check → gate do plano |
+| \`/morph-plan {feature}\` | \`Skill(morph-plan)\` — entrevista → plan.md → plan-check → gate do plano |
 | \`/morph-apply {feature}\` | \`Skill(morph-apply)\` — fatias do plano → verify → review → Gate 3 |
 | \`/morph-status [feature]\` | inspect state.json |
 | \`/morph-archive {feature}\` | move completed feature to .morph/archive/ |
@@ -64,7 +54,6 @@ metadata:
 
 **How to apply:**
 - When user mentions a feature, check \`.morph/features/\` first.
-- When user types \`/morph-proposal\`, invoke \`Skill(morph-plan)\` directly.
 - In \`trust: "auto"\`, gates auto-pass; only AskUserQuestion on risk signals.
 `;
 }
@@ -87,19 +76,7 @@ metadata:
 - \`.morph/framework/evals/review-checklist.md\` — what the Gate 3 verifier, reviewer and security check (verdict SHIP/FIX + evidence-typed blockers)
 `;
 
-/**
- * Populate Claude Code persistent memory for a morph-spec project.
- *
- * Idempotent: re-running overwrites the memory files with current info
- * but appends MEMORY.md index entries only if missing.
- *
- * @param {string} projectPath - Absolute path of the project root
- * @param {object} info - Project facts to embed in the memory
- * @param {string} info.projectName
- * @param {string} info.frameworkVersion
- * @param {string} [info.stack]
- * @returns {Promise<{ projectMemoryPath: string, referenceMemoryPath: string, indexPath: string }>}
- */
+// Idempotent: memory files are overwritten, MEMORY.md entries appended only if missing.
 export async function installProjectMemory(projectPath, info) {
   const memoryRoot = getMemoryRoot(projectPath);
   await fs.ensureDir(memoryRoot);