@polymorphism-tech/morph-spec 9.0.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,32 +1,5 @@
-/**
- * `morph-spec cost [feature] [--by phase] [--all-trees] [--metrics [--top n]] [--json]`
- *
- * A cost-facing view over the same harness event stream `telemetry` reads
- * (.morph/logs/events.jsonl): 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 verifies each feature ran, git calls 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';
@@ -79,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) {
@@ -178,10 +147,6 @@ function printMetricsBody(m) {
   for (const [reason, n] of Object.entries(m.reuse.skipReasons)) console.log(chalk.gray(`    pulou ${n}×: ${reason}`));
 }
 
-/**
- * `--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))
@@ -202,16 +167,6 @@ function printMetrics(feature, options, cwd) {
   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 (the 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?: 'phase' }} options
- * @param {string} cwd
- */
 function printAllTrees(feature, options, cwd) {
   const treesData = loadTelemetryAllTrees(cwd);
   const perTree = treesData.map(({ tree, path, events }) => ({
@@ -254,10 +209,6 @@ function printAllTrees(feature, options, cwd) {
   }
 }
 
-/**
- * @param {string} [feature] - narrow to a single feature
- * @param {{ json?: boolean, by?: '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}"`));
@@ -274,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;
   }
@@ -284,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;
   }

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)'));
   }
 

package/src/commands/project/claim.js

@@ -1,24 +1,3 @@
-/**
- * `morph-spec claim [feature] [--release] [--list]` — the manual half of
- * advisory feature ownership (B1).
- *
- * Claims are acquired and heartbeaten AUTOMATICALLY (SessionStart hook +
- * telemetry hook), so the operator never has to remember anything. This command
- * exists for the two cases automation cannot cover:
- *   - a session that died without releasing, leaving a claim that keeps
- *     warning everyone until its TTL expires (`--release`);
- *   - an operator switching this SAME session/tree to a different feature
- *     mid-task. `morph-spec claim <feature>` (no flags) ACQUIRES it, moving
- *     the tree's previous claim in the same step — a manual release-then-
- *     reclaim was observed to just not happen mid-task, and the silent no-op
- *     this used to be (any unclaimed feature name printed "nothing here" and
- *     changed nothing) was worse: it looked like a query, not a skipped write.
- *
- * `--list` forces the read-only view even when a feature is named. `--release`
- * is the only other mutation. Always exits 0 except on a genuine misuse — the
- * claim system is advisory and must never become a source of hard failures.
- */
-
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { resolve } from 'path';
@@ -31,7 +10,6 @@ import {
   claimAge,
 } from '../../../framework/hooks/shared/claim-registry.js';
 
-/** Resolve the repo's shared git common dir — where claims live. */
 function gitCommonDirOf(cwd) {
   const root = resolvePrimaryRoot(cwd);
   const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
@@ -41,15 +19,8 @@ function gitCommonDirOf(cwd) {
 const norm = (p) => String(p ?? '').replace(/\\/g, '/');
 
 /**
- * Acquire `feature`'s claim, moving it in the same step if this tree already
- * holds a live claim on a different feature.
- *
- * "This tree's own claim" is identified by PATH, not session id: the CLI has
- * no access to the Claude Code session id SessionStart stamps (that only
- * reaches hooks, via stdin JSON) — path is the one honest signal a manual
- * invocation shares with the automatic claim it may be replacing. Re-using
- * that claim's session id when re-acquiring keeps the move from reading as a
- * takeover of a stranger.
+ * Moves this tree's live claim, identified by PATH: the CLI never sees the session id
+ * SessionStart stamps. Reusing that claim's session id keeps the move from reading as a takeover.
  */
 function acquireOrMove(feature, { cwd, gitCommonDir, json }) {
   const here = norm(cwd);
@@ -84,10 +55,6 @@ function acquireOrMove(feature, { cwd, gitCommonDir, json }) {
   process.exit(0);
 }
 
-/**
- * @param {string|undefined} feature
- * @param {{ release?: boolean, list?: boolean, json?: boolean, cwd?: string }} [options]
- */
 export function claimCommand(feature, options = {}) {
   const cwd = options.cwd || process.cwd();
   if (!isGitRepo(cwd)) {
@@ -120,27 +87,16 @@ export function claimCommand(feature, options = {}) {
     process.exit(0);
   }
 
-  // `morph-spec claim <feature>` (no --release, no --list) is the manual
-  // acquire/move half of B1 — automation (SessionStart + heartbeat) covers the
-  // common case; this covers switching this session to a different feature
-  // mid-task without a release-then-reclaim dance. `--list` forces the
-  // read-only view below even when a feature is named.
   if (feature && !options.list) {
     acquireOrMove(feature, { cwd, gitCommonDir, json: options.json });
     return;
   }
 
-  // No feature (or explicit --list): the read-only board, whole or filtered.
   const all = listClaims(gitCommonDir);
   const scoped = feature ? all.filter((c) => c.feature === feature) : all;
 
-  // Um claim morto NÃO é limpo do registro — ele só para de avisar (o TTL de
-  // 30 min o mata, `live` é computado na leitura). O efeito colateral é que o
-  // board acumula: features encerradas há 20h e 73h apareciam no `--list` como
-  // se fossem informação. Um quadro de avisos onde quase nada é aviso ensina a
-  // não olhar o quadro. Por padrão mostramos só o que ainda avisa; `--all`
-  // devolve o registro inteiro, e o rodapé conta o que ficou de fora para a
-  // omissão nunca ser silenciosa.
+  // Claim morto segue no registro (`live` é computado na leitura): por padrão só o que ainda
+  // avisa; `--all` devolve tudo e o rodapé conta o que ficou de fora.
   const rows = options.all ? scoped : scoped.filter((c) => c.live);
   const hidden = scoped.length - rows.length;