@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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 {

package/src/commands/observability/cost.js

@@ -1,34 +1,5 @@
-/**
- * `morph-spec cost [feature] [--by task|phase] [--all-trees] [--metrics [--top n]] [--json]`
- *
- * A cost-facing view over the same harness event stream `telemetry` reads
- * (.morph/logs/events.jsonl): how much wall-clock time was spent inside
- * measured tasks (TaskStart→TaskEnd), how many context bytes were
- * re-ingested (grouped by kind: rubric/standard/skill/agents/plan-artifact/
- * code), and how many sub-agent dispatches happened (with total prompt
- * chars). When the stream has `SessionUsage` events (real, hook-observed
- * token counts), those are summed and shown too — see the sessionUsage
- * caveat below.
- *
- * IMPORTANT: bytes re-ingested is a DETERMINISTIC PROXY for cost, not a
- * token count. Hooks only see what tools read off disk — never the model's
- * actual token usage — so this measures re-ingestion pressure, not spend.
- * `sessionUsage` (when present) is the exception: real tokens, observed
- * directly, not a proxy — see aggregateCost's docstring for the contract.
- *
- * `--all-trees` widens the source from "just the current tree" to every git
- * worktree that has its own events.jsonl plus the logs `finish` saved before
- * removing a worktree, deduplicated by eventId.
- *
- * `--metrics` measures the loop instead: turns, tool calls by orchestrator and
- * sub-agent, time per command class, identical reruns and why, rereads, how
- * many feature-scope verifies each feature ran, git calls per task and whether
- * the reuse validator ran in root and worktree (see lib/telemetry/metrics.js).
- *
- * Read-only, always exits 0 on a normal (even empty) run — fail-open, an
- * empty stream is an answer, not an error. Only `--by` with an unknown value
- * is a usage error (exit 1).
- */
+// Bytes re-ingested is a deterministic proxy for cost, not a token count: hooks only see what
+// tools read off disk. `sessionUsage` is the exception, real hook-observed tokens.
 
 import chalk from 'chalk';
 import { loadTelemetry, loadTelemetryAllTrees, aggregateCost, dedupeEvents } from '../../lib/telemetry/telemetry-reader.js';
@@ -37,7 +8,7 @@ import { computeMetrics } from '../../lib/telemetry/metrics.js';
 const BYTES_CAVEAT =
   'Bytes re-ingeridos são um PROXY determinístico de custo (o que as ferramentas leram do disco) — NÃO são tokens reais. Hooks não enxergam o uso real de tokens do modelo.';
 
-const BY_MODES = ['task', 'phase'];
+const BY_MODES = ['phase'];
 
 function fmtBytes(n) {
   if (!n) return '0 B';
@@ -65,21 +36,6 @@ function printBytesByKind(bytesByKind) {
   }
 }
 
-function printTasks(tasks) {
-  if (!tasks.length) {
-    console.log(chalk.gray('\nNenhuma task com TaskStart/TaskEnd capturada.'));
-    return;
-  }
-  for (const t of tasks) {
-    const status = t.open ? chalk.yellow('[em aberto]') : (t.status || '-');
-    console.log('\n' + chalk.white.bold(`Task ${t.task}`) + chalk.gray(` · ${t.feature ?? '(sem feature)'}`) + ` · ${status}`);
-    console.log(`  duração: ${fmtDuration(t.durationSeconds)}`);
-    console.log(`  dispatches: ${t.dispatches.count} (${t.dispatches.promptChars} chars de prompt)`);
-    console.log('  bytes re-ingeridos por kind:');
-    printBytesByKind(t.bytesByKind);
-  }
-}
-
 function printPhases(phases) {
   if (!phases.length) {
     console.log(chalk.gray('\nNenhum byte de Read com phase capturado.'));
@@ -96,10 +52,6 @@ function tokenLine(u) {
     + `cacheRead=${u.cacheReadTokens}  cacheCreation=${u.cacheCreationTokens}`;
 }
 
-/**
- * Real (hook-observed) token counts — the non-proxy sibling of the bytes
- * above: the main sessions and, separately, the sub-agents.
- */
 function printSessionUsage(summary) {
   const { sessionUsage, agentUsage, sessionUsageLegacySamples } = summary;
   if (sessionUsage) {
@@ -118,8 +70,7 @@ function printSessionUsage(summary) {
 }
 
 function printSummary(summary) {
-  console.log(`\n  duração dentro de tasks medidas: ${fmtDuration(summary.taskDurationSeconds)}`);
-  console.log(`  dispatches: ${summary.dispatches.count} (${summary.dispatches.promptChars} chars de prompt)`);
+  console.log(`\n  dispatches: ${summary.dispatches.count} (${summary.dispatches.promptChars} chars de prompt)`);
 
   console.log('\n' + chalk.white.bold('Bytes re-ingeridos por kind') + ` (${fmtBytes(summary.bytesTotal)} total)`);
   printBytesByKind(summary.bytesByKind);
@@ -140,7 +91,7 @@ function split(counts) {
   return `${counts.total} (orq ${counts.orchestrator} · sub ${counts.subagent}${counts.unknown ? ` · sem agente ${counts.unknown}` : ''})`;
 }
 
-function printMetricsBody(m, { by }) {
+function printMetricsBody(m) {
   const legacyShare = m.window.events ? m.coverage.legacy / m.window.events : 0;
   console.log(chalk.gray(`janela: ${m.window.from ?? '-'} → ${m.window.to ?? '-'} · ${m.window.events} eventos`
     + ` · ${pct(1 - legacyShare)} no esquema v2`));
@@ -149,16 +100,8 @@ function printMetricsBody(m, { by }) {
   }
 
   console.log('\n' + chalk.white.bold('Turnos e chamadas'));
-  console.log(`  turnos: ${m.turns ? split(m.turns) : 'desconhecido (nenhum PostToolBatch na janela)'}`
-    + (m.turnsPerTaskMedian !== null ? chalk.gray(` · mediana por task ${m.turnsPerTaskMedian}`) : ''));
+  console.log(`  turnos: ${m.turns ? split(m.turns) : 'desconhecido (nenhum PostToolBatch na janela)'}`);
   console.log(`  chamadas de ferramenta: ${split(m.toolCalls)}`);
-  const perTask = m.perTaskByFeature;
-  if (perTask.toolCalls !== null) {
-    console.log(`  por task (total da feature ÷ tasks dela, mediana): ${perTask.toolCalls} chamadas`
-      + (perTask.turns !== null ? ` · ${perTask.turns} turnos` : '') + ` · ${perTask.git} git status+diff`
-      + chalk.gray(` · as janelas TaskStart→TaskEnd têm ${pct(m.taskWindowCoverage)} das chamadas`));
-  }
-
   console.log('\n' + chalk.white.bold('Tempo por classe de comando'));
   for (const [klass, t] of Object.entries(m.timeByClass).sort((a, b) => b[1].measuredMs - a[1].measuredMs)) {
     const unmeasured = t.unmeasured ? chalk.gray(` (${t.unmeasured} sem duração)`) : '';
@@ -183,9 +126,9 @@ function printMetricsBody(m, { by }) {
   }
 
   console.log('\n' + chalk.white.bold('verify, git e reuso'));
-  const perFeature = Object.entries(m.verify.byFeature).sort((a, b) => b[1].feature - a[1].feature);
-  console.log(`  verify de feature por feature: mediana ${m.verify.featureScopeMedian ?? '-'}`
-    + (perFeature.length ? chalk.gray(` (${perFeature.slice(0, 5).map(([f, v]) => `${f} ${v.feature}`).join(', ')})`) : ''));
+  const perFeature = Object.entries(m.verify.byFeature).sort((a, b) => b[1] - a[1]);
+  console.log(`  verify por feature: mediana ${m.verify.median ?? '-'}`
+    + (perFeature.length ? chalk.gray(` (${perFeature.slice(0, 5).map(([f, n]) => `${f} ${n}`).join(', ')})`) : ''));
   const repeats = Object.entries(m.verify.unchangedRepeats);
   if (repeats.length) {
     console.log(`  verify de feature sobre a mesma árvore do anterior: ${repeats.reduce((n, [, v]) => n + v, 0)}`
@@ -196,30 +139,14 @@ function printMetricsBody(m, { by }) {
     console.log(`  suíte .NET inteira que recompila (sem --no-build): ${m.dotnetFullSuite.withBuild}/${m.dotnetFullSuite.runs}`
       + chalk.gray(` (${phases})`));
   }
-  console.log(`  git status / diff por task: mediana ${m.gitPerTaskMedian.status ?? '-'} / ${m.gitPerTaskMedian.diff ?? '-'}`
-    + chalk.gray(` · total ${m.git.status} / ${m.git.diff}`));
+  console.log(`  git status / diff: ${m.git.status} / ${m.git.diff}`);
   const trees = Object.entries(m.reuse.byTree);
   console.log(`  reuse-validator: ${trees.length
     ? trees.map(([tree, s]) => `${tree} rodou ${s.ran}, pulou ${s.skipped}`).join(' · ')
     : 'nenhum evento Verify na janela'}`);
   for (const [reason, n] of Object.entries(m.reuse.skipReasons)) console.log(chalk.gray(`    pulou ${n}×: ${reason}`));
-
-  if (by === 'task') {
-    for (const t of m.tasks) {
-      const status = t.open ? chalk.yellow('[em aberto]') : (t.status || '-');
-      console.log('\n' + chalk.white.bold(`Task ${t.task}`) + chalk.gray(` · ${t.feature ?? '(sem feature)'}`) + ` · ${status}`);
-      console.log(`  turnos ${t.turns ? split(t.turns) : '-'} · chamadas ${split(t.toolCalls)}`);
-      const time = Object.entries(t.timeByClass).map(([k, v]) => `${k} ${fmtDuration(v.measuredMs / 1000)}`).join(' · ');
-      if (time) console.log(`  tempo: ${time}`);
-      console.log(`  rerun ${pct(t.reruns.rate)} (${t.reruns.reruns}/${t.reruns.runs}) · releitura ${pct(t.rereads.rate)} · git status/diff ${t.git.status}/${t.git.diff}`);
-    }
-  }
 }
 
-/**
- * `--metrics`: the loop measurements over the current tree (and, with
- * `--all-trees`, every tree plus the finish backups, deduplicated).
- */
 function printMetrics(feature, options, cwd) {
   const events = options.allTrees
     ? dedupeEvents(loadTelemetryAllTrees(cwd).flatMap((t) => t.events))
@@ -237,19 +164,9 @@ function printMetrics(feature, options, cwd) {
   }
   const scope = feature ? chalk.cyan(` · feature ${feature}`) : '';
   console.log(chalk.white.bold(`Medições do loop${options.allTrees ? ' — todas as árvores + finish-backup' : ''}`) + scope);
-  printMetricsBody(metrics, options);
+  printMetricsBody(metrics);
 }
 
-/**
- * `--all-trees` rendering: a short line per tree (so a fleet operator can
- * spot which tree is expensive) followed by the COMBINED aggregate — full
- * detail (task/phase breakdown honors `--by` here too, same as the
- * single-tree path; a typeable flag combination is never a silent no-op).
- *
- * @param {string} [feature]
- * @param {{ json?: boolean, by?: 'task'|'phase' }} options
- * @param {string} cwd
- */
 function printAllTrees(feature, options, cwd) {
   const treesData = loadTelemetryAllTrees(cwd);
   const perTree = treesData.map(({ tree, path, events }) => ({
@@ -277,7 +194,7 @@ function printAllTrees(feature, options, cwd) {
 
   for (const t of perTree) {
     console.log('\n' + chalk.cyan.bold(`── Árvore: ${t.tree}`) + chalk.gray(` — ${t.path}`));
-    console.log(`   ${t.total} eventos · duração em tasks: ${fmtDuration(t.taskDurationSeconds)} · `
+    console.log(`   ${t.total} eventos · `
       + `bytes: ${fmtBytes(t.bytesTotal)} · dispatches: ${t.dispatches.count}`);
   }
 
@@ -285,19 +202,13 @@ function printAllTrees(feature, options, cwd) {
   if (combined.features.length) {
     console.log(chalk.gray(`Features: ${combined.features.join(', ')}`));
   }
-  if (options.by === 'task') {
-    printTasks(combined.tasks);
-  } else if (options.by === 'phase') {
+  if (options.by === 'phase') {
     printPhases(combined.phases);
   } else {
     printSummary(combined);
   }
 }
 
-/**
- * @param {string} [feature] - narrow to a single feature
- * @param {{ json?: boolean, by?: 'task'|'phase', allTrees?: boolean, cwd?: string }} [options]
- */
 export function costCommand(feature, options = {}) {
   if (options.by && !BY_MODES.includes(options.by)) {
     console.error(chalk.red(`\n❌ Invalid --by: "${options.by}"`));
@@ -314,8 +225,7 @@ export function costCommand(feature, options = {}) {
   }
 
   if (options.allTrees) {
-    // Same fail-open + Windows-flush discipline as the single-tree path
-    // below — no forced process.exit(), --json included.
+    // No process.exit() here either, --json included.
     printAllTrees(feature, options, cwd);
     return;
   }
@@ -324,10 +234,8 @@ export function costCommand(feature, options = {}) {
   const summary = aggregateCost(events, { feature });
 
   if (options.json) {
-    // No forced process.exit() here: on Windows a piped stdout write is
-    // async, and exit()ing right after a large console.log can race the
-    // flush and truncate output. Letting the event loop drain naturally
-    // (nothing else keeps it alive in this command) exits 0 without risk.
+    // No process.exit(): on Windows a piped stdout write is async, and exiting right after a
+    // large console.log can truncate the output.
     console.log(JSON.stringify(summary));
     return;
   }
@@ -345,9 +253,7 @@ export function costCommand(feature, options = {}) {
     console.log(chalk.gray(`Features: ${summary.features.join(', ')}`));
   }
 
-  if (options.by === 'task') {
-    printTasks(summary.tasks);
-  } else if (options.by === 'phase') {
+  if (options.by === 'phase') {
     printPhases(summary.phases);
   } else {
     printSummary(summary);

package/src/commands/observability/telemetry.js

@@ -1,14 +1,3 @@
-/**
- * `morph-spec telemetry [--json] [--feature <name>] [--limit <n>]`
- *
- * The reader surface over the harness event stream (.morph/logs/events.jsonl,
- * written by the telemetry-log hook). Reconstructs the whole execution path of
- * an NLH session: top skills, personas dispatched, standards (knowledge base)
- * read, the tool mix, and the recent prompts (user + sub-agent).
- *
- * Read-only, always exits 0 (fail-open — an empty stream is an answer).
- */
-
 import chalk from 'chalk';
 import { loadTelemetry, aggregateTelemetry } from '../../lib/telemetry/telemetry-reader.js';
 
@@ -23,9 +12,7 @@ function section(title, rows, fmt) {
   for (const r of rows) console.log('  ' + fmt(r));
 }
 
-/**
- * @param {{ json?: boolean, feature?: string, limit?: number, cwd?: string }} [options]
- */
+// Read-only and always exits 0: an empty stream is an answer.
 export function telemetryCommand(options = {}) {
   const events = loadTelemetry(options.cwd || process.cwd());
   const summary = aggregateTelemetry(events, { feature: options.feature });

package/src/commands/project/branch.js

@@ -1,23 +1,3 @@
-/**
- * branch.js — `morph-spec branch prune`.
- *
- * The gap this closes: after a few features close by squash-merge, the local
- * repo accumulates branches git considers unmerged. `git branch --merged` lists
- * none of them, `git branch -d` refuses each one, and the only command left is
- * `git branch -D` — which is EXACTLY the command for throwing away real work.
- * Once a user has typed `-D` on five safe branches, the sixth (an actual
- * unintegrated feature) gets the same keystroke.
- *
- * So this command never asks the user to make that distinction: it makes it
- * itself, prints the evidence for each branch, and deletes only what it PROVED
- * is already integrated (see branch-classifier.js for the five classes and
- * their order). Everything else is listed with the reason it survives.
- *
- * The remote is a separate decision: `--remote` is required to touch
- * `origin/<branch>`, because a local branch is a local artifact while the remote
- * one may be what someone else, or an open review, is looking at.
- */
-
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
@@ -25,15 +5,8 @@ import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { buildPrIndex } from '../../lib/git/pr-index.js';
 import { classifyBranches } from '../../lib/git/branch-classifier.js';
 
-/**
- * Delete one local branch.
- *
- * `-D`, not `-d`, and that is the whole point of the classifier: `-d` refuses
- * every squash-merged branch, so a command that used it would be unable to do
- * its one job. The safety does not come from git's own check (which cannot see
- * a squash-merge) — it comes from only ever reaching this function with a
- * branch whose integration was positively proven.
- */
+// `-D`, not `-d`: `-d` refuses every squash-merged branch. Safety comes from only
+// reaching here with integration positively proven.
 function deleteLocal(name, cwd) {
   try {
     execFileSync('git', ['branch', '-D', name], { cwd, stdio: 'pipe' });
@@ -52,7 +25,6 @@ function deleteRemote(name, cwd) {
   }
 }
 
-/** Does `origin/<name>` exist locally as a remote-tracking ref? */
 function remoteRefExists(name, cwd) {
   try {
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/remotes/origin/${name}`], { cwd, stdio: 'pipe' });
@@ -62,15 +34,6 @@ function remoteRefExists(name, cwd) {
   }
 }
 
-/**
- * Command handler for `morph-spec branch prune [--remote] [--dry-run] [--json]`.
- *
- * Fail-open outside a git repo (exit 0, empty result) — the same discipline the
- * rest of the worktree suite follows: a housekeeping command must never be the
- * reason a script dies.
- *
- * @param {{ remote?: boolean, dryRun?: boolean, json?: boolean, cwd?: string }} [options]
- */
 export function branchPruneCommand(options = {}) {
   const cwd = options.cwd || process.cwd();
   const emit = (payload, code = 0) => {
@@ -85,9 +48,7 @@ export function branchPruneCommand(options = {}) {
   }
   const root = resolvePrimaryRoot(cwd);
   const defaultBranch = detectDefaultBranch(root);
-  // null = UNKNOWN, never "no PR" — the classifier treats a branch with no
-  // positive evidence as unmerged, so a missing `gh` costs conservatism, not
-  // safety. Reported so the user can tell "no PR" from "could not ask".
+  // null = UNKNOWN, never "no PR": a missing `gh` costs conservatism, not safety.
   const prIndex = buildPrIndex(root);
 
   const classified = classifyBranches({ cwd: root, defaultBranch, prIndex });
@@ -139,9 +100,7 @@ function printReport(payload, options) {
   const verb = payload.dryRun ? 'seriam apagadas' : 'apagadas';
   console.log(chalk.bold(`\nbranch prune — default: ${payload.defaultBranch || chalk.red('não resolvida')}`));
   if (!payload.prIndexAvailable) {
-    // Load-bearing caveat, not noise: without `gh` a squash-merge is only
-    // detectable by the tree comparison, so branches that WERE merged may
-    // legitimately show up as unmerged here.
+    // Without `gh`, squash-merged branches may legitimately show as unmerged.
     console.log(chalk.gray('  (sem `gh`/GitHub: squash-merge só é detectado por árvore idêntica)'));
   }