@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/e2e/e2e.js

@@ -1,22 +1,6 @@
-/**
- * `morph-spec e2e up|status|down` — lifecycle of the verification stack.
- *
- * The stack is deliberately NOT torn down between verifies: cold-starting a
- * .NET container per task is the difference between a loop people run and one
- * they disable. `up` brings it (or reuses it), `status` says whether what is
- * running still matches the working tree, and `down` releases it — which
- * `morph-spec finish` also does as part of teardown.
- *
- * Every subcommand acts in the TREE THAT OWNS THE FEATURE: run from the
- * primary root for a feature that lives in a worktree, the compose file, the
- * bind mount and the stamp are all the worktree's — the root's copy is a
- * different checkout of different code.
- *
- * All the real logic lives in framework/hooks/shared/e2e-check.js, shared with
- * the `verify` e2e node so the two can never drift.
- *
- * @module commands/e2e
- */
+// The stack is deliberately NOT torn down between verifies: a cold .NET start per task is the
+// difference between a loop people run and one they disable. Every subcommand acts in the tree
+// that owns the feature.
 
 import chalk from 'chalk';
 import { execFileSync } from 'child_process';
@@ -46,22 +30,10 @@ import { createHeavyGate, HeavyBusyError } from '../../lib/heavy/gate.js';
 import { afterHeavyRun } from '../../lib/heavy/cleanup.js';
 import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 
-/** Exit code for a usage error, matching `verify`'s convention. */
 const EXIT_USAGE = 2;
 const EXIT_BUSY = 3;
 
-// ============================================================================
-// Shared context
-// ============================================================================
-
-/**
- * Everything the three subcommands need, resolved once — against the tree
- * that owns the feature (its live worktree when it has one, the root
- * otherwise).
- *
- * Returns null (after printing) when that tree has no compose file — a usage
- * error here, unlike in the verify node where it is a graded skip.
- */
+// No compose file is a usage error here, unlike in the verify node where it is a graded skip.
 function resolveContext(featureName, { json = false } = {}) {
   const root = resolvePrimaryRoot(process.cwd());
   const found = findWorktreeForFeature(featureName, root);
@@ -95,49 +67,24 @@ function resolveContext(featureName, { json = false } = {}) {
   };
 }
 
-/**
- * Compose environment: the port block this feature owns, plus any credentials
- * from the gitignored auth env file.
- *
- * The port block comes from `buildComposeEnv` rather than being assembled here
- * so this command and the `e2e` node inside `verify` agree by construction —
- * isolation that exists only in the command nobody runs is no isolation at all.
- */
+// The port block comes from `buildComposeEnv`, so this command and the verify node agree by
+// construction.
 function buildEnv({ cwd, config, featureName, projectName, gitCommonDir }) {
-  // COMPOSE_PROJECT_NAME is part of the port layout now; the explicit key stays
-  // as the fail-open floor for a repo with no git common dir (no block → no
-  // layout), where the project name is still what isolates the containers.
+  // The explicit key is the floor for a repo with no git common dir (no port layout).
   return {
     COMPOSE_PROJECT_NAME: projectName,
     ...buildComposeEnv({ cwd, config, featureName, gitCommonDir }),
   };
 }
 
-// ============================================================================
-// up
-// ============================================================================
-
-/**
- * `morph-spec e2e up <feature> [--fresh]`
- *
- * `--fresh` is destructive on purpose: it tears the previous stack down WITH
- * its named volumes and forces the auth seed to run again. A rebuild that
- * preserved the database would hand the next suite the previous run's rows,
- * and a storageState captured against that database would keep authenticating
- * a user that no longer exists.
- *
- * Exit codes: 0 = stack healthy · 1 = failed to come up (or auth broke, or the
- * compose cannot be isolated inside a worktree) · 2 = usage (no compose file /
- * no docker).
- */
+// `--fresh` drops the named volumes and reruns the auth seed: a preserved database would hand the
+// next suite stale rows and a storageState for a user that no longer exists.
 export async function e2eUpCommand(featureName, options = {}) {
   const ctx = resolveContext(featureName, options);
   if (!ctx) process.exit(EXIT_USAGE);
 
-  // Isolation BEFORE the docker check: `COMPOSE_PROJECT_NAME` isolates
-  // container names but not host ports, and a compose that hardcodes them (or
-  // names its containers) collides with the sibling worktree no matter what we
-  // inject. Same rule as the verify node — see decideIsolation().
+  // Isolation BEFORE the docker check: a compose that hardcodes host ports or container names
+  // collides with a sibling worktree whatever we inject.
   const lint = lintComposeIsolation(readComposeText(ctx.cwd, ctx.composeFile));
   const isolation = decideIsolation({ findings: lint.findings, insideWorktree: ctx.insideWorktree });
   if (isolation.status === 'fail') {
@@ -189,8 +136,7 @@ export async function e2eUpCommand(featureName, options = {}) {
       ? prepareAuth(ctx.cwd, { config: ctx.config, env: ctx.env, forceSeed: Boolean(options.fresh) })
       : { status: 'skip', reason: null };
 
-  // Same warnings[] contract as the verify e2e node: a seedCommand that never
-  // runs because `mode` switches it off is reported, never swallowed.
+  // A seedCommand that `mode` switches off is reported, never swallowed.
   const warnings = [];
   if (isolation.status === 'warn') warnings.push(isolation.reason);
   if (auth.warning) warnings.push(auth.warning);
@@ -225,32 +171,13 @@ export async function e2eUpCommand(featureName, options = {}) {
   process.exit(failed ? 1 : 0);
 }
 
-// ============================================================================
-// status
-// ============================================================================
-
-/**
- * Where the app actually landed.
- *
- * The orchestrator hands this to the verifier instead of letting it guess
- * `localhost:3000` — each feature owns a port block, so the default port is the
- * one address most likely to be wrong. Mirrors what `playwright.config.ts` is
- * asked to do, deliberately: one rule, two readers.
- *
- * @param {Record<string,string>} env
- * @returns {string}
- */
+// Handed to the verifier so it never guesses `localhost:3000`: each feature owns a port block.
+// Mirrors what `playwright.config.ts` does: one rule, two readers.
 export function resolveBaseUrl(env = {}) {
   return env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${env.PORT ?? 3000}`;
 }
 
-/**
- * `morph-spec e2e status <feature> [--json]`
- *
- * Answers the question that matters before trusting a green run: is what is
- * running still built from the code on disk? Exit 0 when up AND fresh, 1
- * otherwise — so it can gate a script.
- */
+// Exit 0 only when up AND built from the code on disk, so it can gate a script.
 export async function e2eStatusCommand(featureName, options = {}) {
   const ctx = resolveContext(featureName, options);
   if (!ctx) process.exit(EXIT_USAGE);
@@ -309,17 +236,8 @@ export async function e2eStatusCommand(featureName, options = {}) {
   process.exit(status.up && status.healthy && fresh ? 0 : 1);
 }
 
-// ============================================================================
-// down
-// ============================================================================
-
-/**
- * `morph-spec e2e down <feature> [--volumes]`
- *
- * Teardown is best-effort by design — a stack that will not come down must
- * never block `finish`. The freshness stamp goes regardless: a stamp that
- * outlives its containers would let the next `up` reuse a stack that is gone.
- */
+// Best-effort: a stack that will not come down must never block `finish`. The freshness stamp
+// goes regardless, or the next `up` would reuse a stack that is gone.
 export async function e2eDownCommand(featureName, options = {}) {
   const ctx = resolveContext(featureName, options);
   if (!ctx) process.exit(EXIT_USAGE);
@@ -348,10 +266,6 @@ export async function e2eDownCommand(featureName, options = {}) {
   process.exit(0);
 }
 
-// ============================================================================
-// Shared helpers
-// ============================================================================
-
 function readConfig(cwd) {
   try {
     const path = join(cwd, '.morph', 'config', 'config.json');
@@ -370,7 +284,6 @@ function readComposeText(cwd, composeFile) {
   }
 }
 
-/** Same resolution (and same fail-open) as verify-runner's. */
 function resolveGitCommonDir(cwd) {
   try {
     const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {

package/src/commands/graph/affected.js

@@ -1,23 +1,9 @@
-/**
- * `morph-spec graph affected <símbolo>` — blast radius saneado.
- *
- * O valor medido não é recall: contra o grep, o grafo achou ZERO arquivos a
- * mais. É precisão — 58% menos ruído em 12 símbolos do ProspectPRO (1.092
- * arquivos no grep, 266 usos reais) e a classificação da relação. `IHandler`
- * aparece em 193 arquivos no grep e tem 2 usos reais: é implementada por 98.
- *
- * @module graph-affected
- */
 import chalk from 'chalk';
 import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
 import { buildIndex, resolveLabel, affected } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob — o grafo é um subconjunto estrito do grep, então cair para grep não perde recall.';
 
-/**
- * @param {string} symbol
- * @param {{path?: string, json?: boolean, prod?: boolean, usesOnly?: boolean}} [options]
- */
 export async function graphAffectedCommand(symbol, options = {}) {
   const projectPath = options.path || process.cwd();
   const loaded = loadGraph(projectPath);

package/src/commands/graph/build.js

@@ -1,11 +1,3 @@
-/**
- * `morph-spec graph build` (extração completa) e `graph refresh` (incremental).
- *
- * Fail-open: sem graphify no PATH, explica o que fazer e sai 1 — sem stack
- * trace. Um projeto sem grafo continua funcionando por grep.
- *
- * @module graph-build
- */
 import chalk from 'chalk';
 import { readFileSync, existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -33,26 +25,9 @@ function readProjectTags(projectPath) {
   }
 }
 
-/**
- * O `.graphifyignore` com que o graphify vai rodar.
- *
- * Na raiz: escrito ou migrado (writeGraphifyignore). Numa worktree o arquivo é
- * do checkout e nunca é reescrito — seria uma mudança na branch da feature.
- * Ausente ali (a raiz ainda não o versionou), as regras — as da raiz
- * (`ignoreTextOf`), ou as geradas — entram só durante a rodada e saem depois
- * (`cleanup`): um `?? .graphifyignore` deixado na worktree faz o `finish` e
- * o `worktree remove --if-clean` recusarem com worktree-dirty (medido), e pôr
- * o arquivo no exclude do common dir esconderia também o da raiz. O arquivo leva
- * `TEMP_IGNORE_MARKER` na 1ª linha: se este processo morrer antes do
- * `cleanup`, a sobra é reconhecida pelo conteúdo — a próxima rodada a reusa e o
- * `finish` a apaga (`dropLeftoverIgnore`). O graphify não herda o da raiz: o
- * ignore dele para na raiz de VCS mais próxima, que numa worktree é ela mesma
- * (detect.py `_load_graphifyignore`).
- *
- * @param {string} projectPath
- * @param {string[]} tags
- * @returns {{written: boolean, migrated?: boolean, outdated?: object, temporary?: boolean, path: string, cleanup: () => void}}
- */
+// Numa worktree o arquivo do checkout nunca é reescrito; ausente, as regras entram só durante
+// a rodada (uma sobra suja a worktree e o `finish` recusa). `TEMP_IGNORE_MARKER` na 1ª linha
+// deixa a próxima rodada e o `finish` reconhecerem a sobra de um processo morto.
 function prepareIgnore(projectPath, tags) {
   const none = () => {};
   if (!isSecondaryWorktree(projectPath)) return { ...writeGraphifyignore(projectPath, tags), cleanup: none };
@@ -71,9 +46,6 @@ function prepareIgnore(projectPath, tags) {
   };
 }
 
-/**
- * @param {{path?: string, json?: boolean, refresh?: boolean}} [options]
- */
 export async function graphBuildCommand(options = {}) {
   const projectPath = options.path || process.cwd();
   const refresh = options.refresh === true;
@@ -93,19 +65,14 @@ export async function graphBuildCommand(options = {}) {
     process.exit(1);
   }
 
-  // O ignore precisa existir ANTES da extração, senão o grafo nasce com o
-  // ruído que a ADR-004 existe para tirar.
+  // O ignore precisa existir ANTES da extração, senão o grafo nasce com o ruído.
   const ignore = prepareIgnore(projectPath, readProjectTags(projectPath));
   if (ignore.outdated && !options.json) {
     console.error(chalk.yellow(`\n⚠ ${describeOutdatedIgnore(ignore.outdated)}`));
   }
 
-  // Na árvore principal o refresh em background (framework/hooks/shared/
-  // graph-refresh.js) escreve o mesmo graph.json: dois graphify ao mesmo tempo
-  // disputam o arquivo e todos os núcleos. Numa worktree ninguém mais escreve
-  // o graph.json dela — o background só toca a raiz —, e esperar o lock da
-  // raiz ali prometeria "o grafo chega ao HEAD" sobre um refresh que nunca a
-  // alcança. Sem git não há lock, e o comando segue sozinho.
+  // Na raiz o refresh em background escreve o mesmo graph.json: dois graphify disputam o arquivo
+  // e os núcleos. Numa worktree só este comando escreve o grafo dela, e sem git não há lock.
   const primary = isPrimaryTree(projectPath);
   const lock = primary ? acquireRefreshLock(projectPath) : null;
   const running = primary && !lock ? readRefreshLock(projectPath) : null;
@@ -127,24 +94,18 @@ export async function graphBuildCommand(options = {}) {
     ? ['update', projectPath]
     : ['extract', projectPath, '--code-only'];
 
-  // Capturamos o output em vez de herdar o terminal porque precisamos
-  // inspecioná-lo: o graphify sai 1 tanto quando quebra quanto quando não há
-  // código para indexar, e essas duas coisas não podem virar a mesma mensagem.
-  // HEAD e regras lidos ANTES: são o que o graphify leu.
+  // Output capturado: o graphify sai 1 tanto ao quebrar quanto sem código para indexar, e as duas
+  // coisas não podem virar a mesma mensagem. HEAD e regras lidos ANTES: são o que o graphify leu.
   const head = readHead(projectPath);
   const ignoreHash = ignoreRulesHash(projectPath);
   let run;
   let empty = false;
   try {
     run = runGraphify(projectPath, args, { timeout: null });
-    // Projeto sem código é o estado normal logo depois de um `init`, não uma
-    // falha: o graphify diz "found 0 code" / "graph is empty", sai 1 e não
-    // escreve graph.json. Tratar isso como erro faria todo init greenfield
-    // terminar em vermelho.
+    // Projeto sem código (logo depois de um `init`) não é falha: o graphify sai 1 sem graph.json.
     empty = run.status !== 0 && (/found 0 code/i.test(run.output) || /graph is empty/i.test(run.output));
-    // O registro é o que torna "untouched" em dia: sem ele, um refresh que não
-    // mudou a topologia deixa o carimbo no commit antigo e o grafo parece
-    // velho para sempre (framework/hooks/shared/graph-freshness.js).
+    // Sem o registro, um refresh que não mudou a topologia deixa o carimbo no commit antigo
+    // e o grafo parece velho para sempre.
     if (!empty) {
       recordRefreshRun(projectPath, {
         head, exit: run.status ?? null, ignoreHash, unavailable: Boolean(run.unavailable),

package/src/commands/graph/explain.js

@@ -1,25 +1,9 @@
-/**
- * `morph-spec graph explain <símbolo>` — vizinhança com citação arquivo:linha.
- *
- * É o comando preferido nas personas: no eval, `explain` foi consistentemente
- * mais preciso que `query`, que trunca por budget e traz ruído.
- *
- * Cada aresta carrega a procedência (`via`), então dá para ver o que o
- * saneamento recuperou — `coalesced` são exatamente as arestas que o graphify
- * cru perde.
- *
- * @module graph-explain
- */
 import chalk from 'chalk';
 import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
 import { buildIndex, resolveLabel, neighborhood, isTestPath } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob.';
 
-/**
- * @param {string} symbol
- * @param {{path?: string, json?: boolean}} [options]
- */
 export async function graphExplainCommand(symbol, options = {}) {
   const projectPath = options.path || process.cwd();
   const loaded = loadGraph(projectPath);

package/src/commands/graph/status.js

@@ -1,12 +1,3 @@
-/**
- * `morph-spec graph status` — existência, tamanho, frescor e saúde do
- * saneamento.
- *
- * Ausência de grafo NÃO é erro (ADR-002): exit 0 com `available: false`. Um
- * projeto sem grafo é um estado válido, e o framework segue por grep.
- *
- * @module graph-status
- */
 import chalk from 'chalk';
 import {
   loadGraph, getFreshness, describeStale, refreshState, staleCause,
@@ -24,9 +15,7 @@ function summarizeSanitize(index) {
   return counts;
 }
 
-/**
- * @param {{path?: string, json?: boolean}} [options]
- */
+// Ausência de grafo não é erro: exit 0 com `available: false`, e o framework segue por grep.
 export async function graphStatusCommand(options = {}) {
   const projectPath = options.path || process.cwd();
   const installed = detectGraphifyVersion();

package/src/commands/mcp/mcp-setup.js

@@ -1,15 +1,3 @@
-/**
- * MCP Setup Command
- *
- * Install and configure MCP servers for morph-spec projects.
- *
- * Usage:
- *   morph-spec mcp setup              — Interactive wizard showing all MCPs
- *   morph-spec mcp setup <name>       — Setup a specific MCP
- *   morph-spec mcp setup --list       — Show MCP install status
- *   morph-spec mcp setup --auto       — Non-interactive auto-install credential-free MCPs
- */
-
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import ora from 'ora';
@@ -31,17 +19,9 @@ import {
 import { detectClaudeConfig } from '../../lib/detectors/claude-config-detector.js';
 import { detectProject } from '../../lib/detectors/index.js';
 
-/**
- * Detect the current project's stack.
- * Prefers .morph/config/config.json (set during morph-spec init) over filesystem re-detection.
- *
- * Exported for testing: the stack decides which MCPs are relevant, and it is
- * the one branch here worth pinning — `.morph/config/config.json` is the only
- * place a compound stack (`dotnet-nextjs`) survives, since filesystem
- * re-detection collapses it to whichever half it notices first.
- */
+// config.json is the only place a compound stack (`dotnet-nextjs`) survives: filesystem
+// re-detection collapses it to whichever half it notices first.
 export async function detectStack(targetPath) {
-  // 1. Prefer the authoritative config (handles compound stacks like nextjs+dotnet)
   try {
     const configPath = join(targetPath, '.morph', 'config', 'config.json');
     if (existsSync(configPath)) {
@@ -55,7 +35,6 @@ export async function detectStack(targetPath) {
     // Fall through to filesystem detection
   }
 
-  // 2. Fallback: detect from filesystem
   try {
     const results = await detectProject(targetPath, { conversation: false, generateStandards: false });
     return results.structure?.stack || 'unknown';
@@ -64,14 +43,8 @@ export async function detectStack(targetPath) {
   }
 }
 
-/**
- * Detect the project's integrations (`neon`, `stripe`...), same sources and
- * order as detectStack. The detectors never fold them into the stack string, so
- * without this an MCP scoped to an integration (neon, asaas) is never offered.
- *
- * @param {string} targetPath
- * @returns {Promise<string[]>}
- */
+// The detectors never fold integrations into the stack string: without this, an MCP scoped
+// to an integration (neon, asaas) is never offered.
 export async function detectIntegrations(targetPath) {
   try {
     const configPath = join(targetPath, '.morph', 'config', 'config.json');
@@ -95,7 +68,6 @@ export async function mcpSetupCommand(name, options) {
   const targetPath = process.cwd();
 
   try {
-    // Detect current environment
     const stack = await detectStack(targetPath);
     const integrations = await detectIntegrations(targetPath);
     const claudeConfig = await detectClaudeConfig(targetPath);
@@ -114,7 +86,6 @@ export async function mcpSetupCommand(name, options) {
       return setupSpecificMcp(targetPath, name, stack, existingMcps);
     }
 
-    // Interactive wizard
     return interactiveWizard(targetPath, stack, existingMcps, integrations, enabledPlugins);
   } catch (err) {
     console.error(chalk.red(`Error: ${err.message}`));
@@ -122,9 +93,6 @@ export async function mcpSetupCommand(name, options) {
   }
 }
 
-/**
- * Show MCP status list (--list)
- */
 async function showStatusList(targetPath, stack, existingMcps, integrations, enabledPlugins) {
   const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations, enabledPlugins });
   const statusRows = formatMcpStatusTable(orchestration, {});
@@ -156,9 +124,6 @@ async function showStatusList(targetPath, stack, existingMcps, integrations, ena
   console.log('');
 }
 
-/**
- * Auto-install credential-free MCPs (--auto)
- */
 async function autoInstall(targetPath, stack, existingMcps, integrations, enabledPlugins) {
   const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { autoOnly: true, integrations, enabledPlugins });
   const autoNames = Object.keys(orchestration.autoInstallable);
@@ -176,7 +141,6 @@ async function autoInstall(targetPath, stack, existingMcps, integrations, enable
     console.log(chalk.gray(`  Skipped (already configured): ${result.skipped.join(', ')}`));
   }
 
-  // Install companion skills for MCPs that define them
   const skillResults = installCompanionSkills(orchestration.autoInstallable);
   for (const r of skillResults) {
     if (r.success) {
@@ -189,9 +153,6 @@ async function autoInstall(targetPath, stack, existingMcps, integrations, enable
   console.log('');
 }
 
-/**
- * Setup a specific MCP by name
- */
 async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
   const registry = loadMcpRegistry();
   const mcpEntry = registry.mcps[name];
@@ -208,7 +169,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     return;
   }
 
-  // Check if already installed
   const isInstalled = existingMcps.some(s => s.name.toLowerCase().includes(name));
   if (isInstalled) {
     const { reconfigure } = await inquirer.prompt([{
@@ -220,7 +180,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     if (!reconfigure) return;
   }
 
-  // Check prerequisites
   const prereqs = mcpEntry.install.prerequisites || [];
   for (const prereq of prereqs) {
     try {
@@ -234,20 +193,17 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     }
   }
 
-  // Show warnings
   for (const warning of mcpEntry.install.warnings || []) {
     console.log(chalk.yellow(`\n  ⚠ ${warning}`));
   }
 
   const credentials = mcpEntry.install.credentials || [];
 
-  // Stitch MCP — automated setup via setupStitch()
   if (name === 'stitch' && !mcpEntry.install.autoInstall) {
     console.log(chalk.cyan(`\n  Setting up Stitch MCP (automated)\n`));
     console.log(chalk.gray(`  Usage: ${mcpEntry.usage}`));
     console.log('');
 
-    // Allow user to provide GCP project if auto-detection might fail
     let gcpProject;
     const gcpCred = credentials.find(c => c.envVar === 'STITCH_GCP_PROJECT');
     const { gcpProjectInput } = await inquirer.prompt([{
@@ -260,7 +216,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     const spinner = ora('Setting up Stitch MCP...').start();
     const result = await setupStitch(targetPath, { gcpProject });
 
-    // Report step-by-step results
     for (const step of result.steps) {
       if (step.success) {
         switch (step.step) {
@@ -288,7 +243,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
       if (failedStep?.error) {
         console.log(chalk.red(`  ${failedStep.error}`));
       }
-      // Show health-check warning if it failed but setup otherwise succeeded
       const healthStep = result.steps.find(s => s.step === 'health-check');
       if (healthStep && !healthStep.success) {
         console.log(chalk.yellow(`  ⚠ Health-check: ${healthStep.error}`));
@@ -318,7 +272,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     return;
   }
 
-  // Auto-installable — just install
   if (mcpEntry.install.autoInstall) {
     const spinner = ora(`Installing ${name}...`).start();
     const result = await installAutoMcps(targetPath, { [name]: mcpEntry });
@@ -331,7 +284,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     return;
   }
 
-  // Remote HTTP MCP — show setup command and optionally auto-configure
   if (isRemoteMcp(mcpEntry.install.config)) {
     console.log(chalk.cyan(`\n  Setting up ${name} MCP (remote)\n`));
     console.log(chalk.gray(`  Usage: ${mcpEntry.usage}`));
@@ -372,7 +324,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     return;
   }
 
-  // Needs credentials (stdio MCPs)
   console.log(chalk.cyan(`\n  Setting up ${name} MCP\n`));
   console.log(chalk.gray(`  Usage: ${mcpEntry.usage}`));
   console.log('');
@@ -400,7 +351,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     await installMcpWithCredentials(targetPath, name, mcpEntry, credentialValues);
     spinner.succeed(`${name} MCP configured`);
   } else {
-    // Show config snippet
     const instructions = generateSetupInstructions(name, mcpEntry);
     console.log(chalk.gray('\n  Add to .mcp.json → mcpServers:'));
     console.log(chalk.gray('  ' + '─'.repeat(55)));
@@ -417,9 +367,6 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
   console.log('');
 }
 
-/**
- * Interactive wizard showing all MCPs
- */
 async function interactiveWizard(targetPath, stack, existingMcps, integrations, enabledPlugins) {
   const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations, enabledPlugins });
 
@@ -435,7 +382,6 @@ async function interactiveWizard(targetPath, stack, existingMcps, integrations,
     console.log(chalk.green(`  Already configured: ${alreadyNames.join(', ')}`));
   }
 
-  // Auto-install
   if (autoNames.length > 0) {
     const { installAuto } = await inquirer.prompt([{
       type: 'confirm',
@@ -449,7 +395,6 @@ async function interactiveWizard(targetPath, stack, existingMcps, integrations,
       const result = await installAutoMcps(targetPath, orchestration.autoInstallable);
       spinner.succeed(`Installed: ${result.added.join(', ')}`);
 
-      // Install companion skills for MCPs that define them
       const skillResults = installCompanionSkills(orchestration.autoInstallable);
       for (const r of skillResults) {
         if (r.success) {
@@ -461,7 +406,6 @@ async function interactiveWizard(targetPath, stack, existingMcps, integrations,
     }
   }
 
-  // Credential MCPs
   if (manualNames.length > 0) {
     console.log(chalk.cyan('\n  Credential-requiring MCPs:'));
 
@@ -481,7 +425,6 @@ async function interactiveWizard(targetPath, stack, existingMcps, integrations,
       }]);
 
       if (setupNow) {
-        // Stitch — automated setup via setupStitch()
         if (name === 'stitch' && !entry.install.autoInstall) {
           const gcpCred = entry.install.credentials?.find(c => c.envVar === 'STITCH_GCP_PROJECT');
           const { gcpProject } = await inquirer.prompt([{
@@ -507,7 +450,6 @@ async function interactiveWizard(targetPath, stack, existingMcps, integrations,
           continue;
         }
 
-        // Remote MCPs — launch OAuth via claude mcp add
         if (isRemoteMcp(entry.install.config)) {
           console.log(chalk.cyan(`  Launching ${capitalizedName} OAuth...`));
           try {