@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/project/doctor.js

@@ -25,27 +25,11 @@ import { samePathCase } from '../../lib/worktree/docker-audit.js';
 
 const isWindows = platform() === 'win32';
 
-/**
- * Resolved-path equality for a `cwd` string against the project root —
- * `"./src/web"`, `"src/web/"` and (on win32) `"src\\web"` must compare equal
- * to `"src/web"`. Case-insensitive on win32 only, through `samePathCase` of
- * `src/lib/worktree/docker-audit.js` — the one copy of that rule (#87 F5): NTFS
- * itself is case-insensitive, so two spellings that differ only in case are
- * the same directory there and nowhere else.
- *
- * @param {string} root - Project root the cwd is relative to
- * @param {string|null|undefined} cwd
- * @returns {string}
- */
+// NTFS is case-insensitive: case folding goes through `samePathCase`, the one copy of that rule.
 function normCwd(root, cwd) {
   return samePathCase(resolve(root, String(cwd ?? '.')).replace(/\\/g, '/'));
 }
 
-/**
- * Check which required Claude Code plugins are installed.
- * @param {Object} pluginsData - The `plugins` object from installed_plugins.json
- * @returns {{ context7: boolean }}
- */
 export function checkInstalledPlugins(pluginsData) {
   const REQUIRED = ['context7'];
   return Object.fromEntries(
@@ -54,9 +38,6 @@ export function checkInstalledPlugins(pluginsData) {
 }
 
 
-/**
- * Check if morph-spec command is in PATH
- */
 function isMorphSpecInPath() {
   try {
     const command = isWindows ? 'where morph-spec' : 'which morph-spec';
@@ -67,9 +48,6 @@ function isMorphSpecInPath() {
   }
 }
 
-/**
- * Detect if nvm-windows is installed
- */
 function isUsingNvmWindows() {
   if (!isWindows) return false;
 
@@ -81,9 +59,6 @@ function isUsingNvmWindows() {
   }
 }
 
-/**
- * Get npm global prefix
- */
 function getNpmGlobalPrefix() {
   try {
     const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
@@ -93,12 +68,10 @@ function getNpmGlobalPrefix() {
   }
 }
 
-// lib files (v5 — minimal surface)
 const REQUIRED_LIB_FILES = [
   'src/lib/stack-filter.js'
 ];
 
-// command files (v5 CLI surface — installer-only)
 const REQUIRED_COMMAND_FILES = [
   'src/commands/project/init.js',
   'src/commands/project/update.js',
@@ -112,20 +85,6 @@ const REQUIRED_COMMAND_FILES = [
   'src/commands/context/context-refresh.js',
 ];
 
-/**
- * Validate a parsed `agents.json` against the v5 contract.
- *
- * Exported, and pure, so the tests can exercise the REAL rules. They used to
- * re-implement this logic inline "because doctorCommand doesn't export
- * individual check functions" — and the two promptly disagreed: the tests
- * asserted a v4 document (version 4.x, `tier` and `active_phases` required)
- * while this code treats exactly those fields as deprecated. Both stayed green
- * because they never met. A canary that destroyed this whole check left the
- * suite at 18/18.
- *
- * @param {Object} agentsData - parsed agents.json
- * @returns {Array<{name: string, status: 'ok'|'warn'|'error', msg?: string}>}
- */
 export function validateAgentsJson(agentsData) {
   const checks = [];
   const agentEntries = Object.entries(agentsData.agents || {})
@@ -133,7 +92,6 @@ export function validateAgentsJson(agentsData) {
   const actualCount = agentEntries.length;
   const declaredCount = agentsData.total_agents;
 
-  // 1: total_agents matches actual count
   if (actualCount !== declaredCount) {
     checks.push({
       name: 'agents.json count',
@@ -144,7 +102,6 @@ export function validateAgentsJson(agentsData) {
     checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
   }
 
-  // 2: required v5 personas present
   const missingPersonas = REQUIRED_AGENTS.filter(id => !(agentsData.agents || {})[id]);
   if (missingPersonas.length > 0) {
     checks.push({
@@ -156,7 +113,6 @@ export function validateAgentsJson(agentsData) {
     checks.push({ name: 'agents.json required personas', status: 'ok' });
   }
 
-  // 3: v5 schema (flat personas, no tiers)
   const version = agentsData.version || 'unknown';
   const isV5 = version.startsWith('5.');
   const v4Fields = [];
@@ -191,8 +147,7 @@ export function validateAgentsJson(agentsData) {
     });
   }
 
-  // 4: maxTurns (ADR-004) — the installer's own rule, so this cannot pass a
-  // value the installer refuses. ERROR, not warn: that persona is not generated.
+  // The installer's own rule, so this cannot pass a value it refuses. ERROR: that persona is not generated.
   const maxTurnsErrors = agentEntries
     .map(([id, data]) => maxTurnsError(id, data?.maxTurns))
     .filter(Boolean);
@@ -200,7 +155,6 @@ export function validateAgentsJson(agentsData) {
     ? { name: 'agents.json maxTurns', status: 'error', msg: maxTurnsErrors.join(' | ') }
     : { name: 'agents.json maxTurns', status: 'ok' });
 
-  // 5: surfaces — same installer rule, same severity: the persona is not generated.
   const surfacesErrors = agentEntries
     .map(([id, data]) => surfacesError(id, data?.surfaces, data?.standards))
     .filter(Boolean);
@@ -208,7 +162,6 @@ export function validateAgentsJson(agentsData) {
     ? { name: 'agents.json surfaces', status: 'error', msg: surfacesErrors.join(' | ') }
     : { name: 'agents.json surfaces', status: 'ok' });
 
-  // 6: effort — same installer rule, same severity.
   const effortErrors = agentEntries
     .map(([id, data]) => effortError(id, data?.effort))
     .filter(Boolean);
@@ -228,12 +181,7 @@ export function validateAgentsJson(agentsData) {
   return checks;
 }
 
-// framework standards (stack-relevant only).
-// Keep every entry pointing at a file that exists: a check that can never pass
-// carries the same information as one that can never fail — none. This list
-// still named two standards from a `workflows/` directory that no longer
-// exists, which pinned `doctor --full` at a permanent 3/6 and made a real
-// regression indistinguishable from the usual red.
+// Every entry must point at an existing file: a check that can never pass reports nothing.
 const FRAMEWORK_STANDARDS = [
   'framework/standards/architecture/vertical-slice/vertical-slice.md',
   'framework/standards/data/nosql/cosmos-db.md',
@@ -242,8 +190,6 @@ const FRAMEWORK_STANDARDS = [
   'framework/standards/integration/mcp/mcp-tools.md'
 ];
 
-// required personas expected in agents.json — the universal, stack-agnostic
-// ones: the three review roles and scout (stage axis)
 const REQUIRED_AGENTS = [
   'verifier',
   'reviewer',
@@ -251,9 +197,6 @@ const REQUIRED_AGENTS = [
   'scout'
 ];
 
-/**
- * Run full health checks
- */
 async function doctorFullCommand(frameworkRoot) {
   console.log(chalk.bold('\n🔬 MORPH-SPEC Full Health Check\n'));
   console.log('─'.repeat(60));
@@ -272,15 +215,8 @@ async function doctorFullCommand(frameworkRoot) {
     }
   };
 
-  // Two layouts reach this command and they disagree on where everything is.
-  //
-  //   framework repo     src/, framework/, no .morph/ at all
-  //   installed project  .morph/framework/, and the CLI in node_modules
-  //
-  // Half the checks assumed one layout and half the other, so `--full` could
-  // not pass anywhere: red in the repo (no .morph/) and red in a project (no
-  // src/). A check that can never pass reports exactly as much as one that can
-  // never fail. Each check now runs only where it means something.
+  // Two layouts reach this command (framework repo: src/, no .morph/; installed project:
+  // .morph/framework/, CLI in node_modules). Each check runs only where it means something.
   const installedAgentsPath = join(frameworkRoot, '.morph/framework/agents.json');
   const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
   const inFrameworkRepo = !(await pathExists(installedAgentsPath))
@@ -289,9 +225,7 @@ async function doctorFullCommand(frameworkRoot) {
 
   console.log(chalk.gray(`\n  Contexto: ${inFrameworkRepo ? 'repo do framework' : 'projeto instalado'}`));
 
-  // ── 1-2. Source tree (framework repo only) ──────────────────────────────
-  // An installed project has no src/ — the CLI lives in node_modules, and its
-  // integrity is npm's job, not the doctor's.
+  // An installed project has no src/: the CLI's integrity in node_modules is npm's job.
   if (inFrameworkRepo) {
     console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
     const missingLibs = [];
@@ -312,9 +246,6 @@ async function doctorFullCommand(frameworkRoot) {
       missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
   }
 
-  // ── 3. Framework Standards ───────────────────────────────────────────────
-  // Same files, different root: the repo holds them at framework/standards/,
-  // an installed project at .morph/framework/standards/.
   const stdsRoot = inFrameworkRepo ? frameworkRoot : join(frameworkRoot, '.morph');
   console.log(chalk.cyan(`\n  ${inFrameworkRepo ? '' : '.morph/'}framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
   const missingStds = [];
@@ -325,7 +256,6 @@ async function doctorFullCommand(frameworkRoot) {
     missingStds.length === 0, false,
     missingStds.length > 0 ? `missing: ${missingStds.join(', ')}` : '');
 
-  // ── 5. Required Agents in agents.json ───────────────────────────────────
   console.log(chalk.cyan(`\n  ${inFrameworkRepo ? 'framework' : '.morph/framework'}/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
   if (await pathExists(agentsPath)) {
     try {
@@ -342,10 +272,7 @@ async function doctorFullCommand(frameworkRoot) {
     check('agents.json', false, false, 'file not found');
   }
 
-  // ── 6. agents.json version freshness ──────────────────────────────────
-  // Only meaningful for an installed project: it compares what was installed
-  // against the canonical source. In the framework repo the two are the same
-  // file, so the comparison is vacuous and is skipped.
+  // Installed project only: in the framework repo source and installed copy are the same file.
   if (!inFrameworkRepo && await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
     try {
       const installed = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
@@ -355,15 +282,10 @@ async function doctorFullCommand(frameworkRoot) {
       const isFresh = installedVer === canonicalVer;
       check(`agents.json version (${installedVer})`, isFresh, true,
         isFresh ? '' : `stale — canonical is v${canonicalVer}, run 'morph-spec update' to sync`);
-    } catch { /* ignore parse errors — already caught above */ }
+    } catch {}
   }
 
-  // ── 6b. Generated personas drift (.claude/agents ↔ agents.json) ─────────
-  // agents.json is the single source of truth; the .claude/agents/morph-*.md
-  // files are derived artifacts (ADR-001). Missing = broken dispatch (error);
-  // stale/hand-edited or orphan = drift (warning).
-  // Skipped in the framework repo: the generated `.claude/agents/morph-*.md`
-  // are an artifact of installing into a project, not of the source tree.
+  // Skipped in the framework repo: the generated `.claude/agents/morph-*.md` only exist in a project.
   if (!inFrameworkRepo && await pathExists(agentsPath)) {
     console.log(chalk.cyan('\n  .claude/agents/ — Generated personas (drift vs agents.json)'));
     try {
@@ -373,7 +295,7 @@ async function doctorFullCommand(frameworkRoot) {
         try {
           const rawCfg = (await fs.readFile(cfgPath, 'utf8')).replace(/^/, '');
           projectTags = getProjectTags(JSON.parse(rawCfg));
-        } catch { /* no tags */ }
+        } catch {}
       }
       // The MCP registry comes from the package, like the installer's: the
       // installed .morph/framework/ has no mcp/, and rendering without it
@@ -399,7 +321,6 @@ async function doctorFullCommand(frameworkRoot) {
     }
   }
 
-  // ── 6c. GitHub tooling — gh CLI (canonical; morph-spec does not use a GitHub MCP) ──
   console.log(chalk.cyan('\n  Tooling — GitHub via gh CLI'));
   try {
     execSync('gh --version', { stdio: 'pipe', timeout: 5000 });
@@ -409,7 +330,6 @@ async function doctorFullCommand(frameworkRoot) {
       "GitHub ops (issues/PRs/releases) usam o gh CLI — instale https://cli.github.com e rode 'gh auth login'");
   }
 
-  // ── 7. state.json schema version ────────────────────────────────────────
   console.log(chalk.cyan('\n  .morph/state.json — Schema Version'));
   const statePath = join(frameworkRoot, '.morph/state.json');
   if (await pathExists(statePath)) {
@@ -425,23 +345,8 @@ async function doctorFullCommand(frameworkRoot) {
     check('state.json', false, true, 'not found (run: morph-spec init)');
   }
 
-  // ── 8. project.tests[] — o contrato do config, camada 3 ─────────────────
-  //
-  // As outras duas camadas são o `config.schema.json` (declarativa) e
-  // `validateTestNodes()` chamada pelo `verify` (fail-closed, em uso). Esta
-  // aqui existe para o defeito chegar ANTES do gate: um `id` com typo em
-  // `tests[]` só se manifesta quando alguém roda `morph-spec verify` e lê um
-  // nó vermelho — o doctor o mostra na checagem de saúde, que é onde se olha
-  // primeiro. Reusa `validateTestNodes` (a MESMA autoridade que o verify
-  // consulta): uma segunda leitura do mesmo campo aqui seria uma segunda
-  // opinião sobre o que é um nó válido, e as duas divergiriam.
-  //
-  // PULA de verdade — sem check e sem cabeçalho — quando não há `config.json`
-  // ou quando `project.tests` não foi declarado. Um projeto sem declaração usa
-  // o fallback de quatro passos e não tem contrato a violar; este repositório
-  // é exatamente esse caso, e um check que não pode passar aqui é ruído, não
-  // achado (`test/commands/doctor.test.js`: `doctor --full` sem nenhum `✗`).
-  // WARN e nunca ERROR: a barreira fail-closed é o `verify`; o doctor informa.
+  // Mesma autoridade do `verify` (validateTestNodes). Pula sem `config.json` ou sem `project.tests`:
+  // não há contrato a violar, e `doctor --full` não pode ter ✗ aqui. WARN, nunca ERROR.
   const testsConfigPath = morphConfigPath(frameworkRoot);
   if (await pathExists(testsConfigPath)) {
     let testsConfig = null;
@@ -460,12 +365,8 @@ async function doctorFullCommand(frameworkRoot) {
           ? broken.map((n) => n.reason ?? `invalid-test-node: ${n.id}`).join('; ')
           : '');
 
-      // #87 PR B: a vitest/jest package.json declared tests[] never mentions is
-      // exactly the shape F30 exploited — a real suite sitting outside the gate.
-      // WARN-only, never ✗: the fail-closed barrier is `verify`, this just informs.
-      // Compared by RESOLVED path, not raw string: "./src/web", "src/web/" and
-      // (win32) "src\\web" all address the same node as "src/web" and must not
-      // produce a spurious warning just because the spelling differs.
+      // A vitest/jest package.json that no declared node covers is a suite outside the gate (WARN only).
+      // Compared by RESOLVED path so a different spelling of the same dir doesn't warn.
       const declaredCwds = new Set(declared.map((n) => normCwd(frameworkRoot, n.cwd)));
       const uncoveredPkgs = discoverFrontendPackages(frameworkRoot, testsConfig)
         .filter((pkg) => !declaredCwds.has(normCwd(frameworkRoot, pkg.cwd)));
@@ -476,10 +377,7 @@ async function doctorFullCommand(frameworkRoot) {
         );
       }
     } else if (typeof testsConfig?.project?.testCommand === 'string' && testsConfig.project.testCommand.trim()) {
-      // Mesma checagem, para o caso testCommand-only: o comando é OPACO (uma
-      // string de shell), então cobertura aqui é só "o comando MENCIONA o
-      // runner do package.json" — não confirmar isso seria ruído para quem já
-      // roda vitest por dentro do testCommand.
+      // testCommand é opaco: cobertura aqui é só "o comando MENCIONA o runner do package.json".
       const testCommand = testsConfig.project.testCommand;
       const uncoveredPkgs = discoverFrontendPackages(frameworkRoot, testsConfig)
         .filter((pkg) => !testCommand.includes(pkg.runner));
@@ -493,7 +391,6 @@ async function doctorFullCommand(frameworkRoot) {
     }
   }
 
-  // ── Display ──────────────────────────────────────────────────────────────
   console.log('\n' + '─'.repeat(60));
   console.log(chalk.bold('\nResults:\n'));
   for (const c of checks) {
@@ -520,19 +417,7 @@ async function doctorFullCommand(frameworkRoot) {
   }
 }
 
-/**
- * MCP health check: reads .mcp.json, settings.json, and settings.local.json
- * and validates each configured MCP server's command binary and env var requirements.
- *
- * Strategy:
- *  - "ok"   : command binary exists (or is a known runtime like npx/node) AND
- *             all env vars referenced in args/env are set in process.env
- *  - "warn" : binary found but env vars missing (MCP won't auth)
- *  - "missing": command binary not found in PATH
- *
- * NOTE: This does NOT test actual connectivity — that requires spawning the MCP.
- * It's a static configuration health check that catches 80% of "MCP not working" cases.
- */
+// Static config check only: connectivity would require spawning the MCP.
 async function doctorMcpCommand(targetPath) {
   logger.header('MCP Server Health Check');
   logger.blank();
@@ -540,7 +425,6 @@ async function doctorMcpCommand(targetPath) {
   const allMcpServers = {};
   const sourcesFound = [];
 
-  // Primary: .mcp.json (Claude Code reads MCPs from here)
   const mcpJsonPath = join(targetPath, '.mcp.json');
   if (await pathExists(mcpJsonPath)) {
     try {
@@ -551,10 +435,9 @@ async function doctorMcpCommand(targetPath) {
         Object.assign(allMcpServers, mcps);
         sourcesFound.push(`.mcp.json (${count})`);
       }
-    } catch { /* invalid JSON — ignore */ }
+    } catch {}
   }
 
-  // Legacy: settings files (for backward compat)
   const settingsPaths = [
     join(targetPath, '.claude', 'settings.json'),
     join(targetPath, '.claude', 'settings.local.json'),
@@ -575,7 +458,7 @@ async function doctorMcpCommand(targetPath) {
         if (addedCount > 0) {
           sourcesFound.push(`${relative(targetPath, sp)} (${addedCount})`);
         }
-      } catch { /* invalid JSON — ignore */ }
+      } catch {}
     }
   }
 
@@ -598,14 +481,11 @@ async function doctorMcpCommand(targetPath) {
     let status = 'ok';
     let isRemote = false;
 
-    // ── 0. Remote MCP detection ────────────────────────────────────────────
-    // Remote MCPs use HTTP transport (type: "http" or url property) — no binary to check
     if (config.type === 'http' || (config.url && !config.command)) {
       isRemote = true;
       // Remote MCPs are always "ok" from a config perspective — auth happens at runtime
     }
 
-    // ── 1. Binary check (stdio MCPs only) ──────────────────────────────────
     const cmd = config.command || '';
     if (!isRemote && cmd && !KNOWN_RUNTIMES.has(cmd)) {
       try {
@@ -616,7 +496,6 @@ async function doctorMcpCommand(targetPath) {
       }
     }
 
-    // ── 2. Env vars from config.env ────────────────────────────────────────
     for (const [key, val] of Object.entries(config.env || {})) {
       if (typeof val === 'string' && (val.startsWith('${') || (val.startsWith('$') && !val.includes(' ')))) {
         const varName = val.replace(/^\$\{?/, '').replace(/\}$/, '');
@@ -627,7 +506,6 @@ async function doctorMcpCommand(targetPath) {
       }
     }
 
-    // ── 3. Env refs in args array ──────────────────────────────────────────
     const argsStr = (config.args || []).join(' ');
     const envRefsInArgs = [...argsStr.matchAll(/\$\{?([A-Z_][A-Z0-9_]*)\}?/g)].map(m => m[1]);
     for (const varName of envRefsInArgs) {
@@ -640,7 +518,6 @@ async function doctorMcpCommand(targetPath) {
     checks.push({ name, status, issues, cmd, isRemote });
   }
 
-  // ── Display ────────────────────────────────────────────────────────────────
   for (const c of checks) {
     const typeLabel = c.isRemote
       ? chalk.gray(` [remote: ${allMcpServers[c.name]?.url || 'http'}]`)
@@ -679,23 +556,8 @@ async function doctorMcpCommand(targetPath) {
 }
 
 /**
- * `morph-spec doctor --worktrees [--prune]` — reconcile git's worktree registry
- * with the directories on disk and the features morph knows (C2).
- *
- * Orphan worktrees used to accumulate invisibly: `fleet` only reports worktrees
- * on a `morph/*` branch, so anything else never showed up anywhere.
- *
- * `--prune` runs the safe repairs: `git worktree prune` (admin records for
- * directories that are already gone) and the removal of EMPTY unregistered
- * residue directories, which by definition hold nothing that can be lost.
- * Deleting a directory that still HOLDS something is reported with the exact
- * command, never performed — same PROVE-or-DECLINE discipline as the finish
- * teardown.
- *
- * `--prune` also applies the retention of the finish backups — the same policy
- * every `finish` applies on its own, and the ONLY path that also applies it to
- * the backups written before the retention existed (no manifest), counting
- * them against the budget. Under `--json` its result rides in the JSON.
+ * `--prune` runs only safe repairs (`git worktree prune`, EMPTY unregistered dirs) and the
+ * finish-backup retention; a directory that still holds something is reported, never deleted.
  */
 export async function doctorWorktreesCommand(targetPath, options = {}) {
   const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
@@ -760,13 +622,8 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
   }
 
   const issues = auditWorktrees(targetPath);
-  // `severity: 'info'` entries (a worktree carrying unintegrated work) and
-  // `severity: 'warn'` entries (a worktree created outside morph's container,
-  // and the docker findings from `docker-audit.js`: an orphan stack, a port
-  // held by another compose project) are REPORTED but are not failures — a
-  // `doctor --worktrees || ...` in CI must not go red because somebody has an
-  // open PR, a hand-made tree, or a container still up. The human path below
-  // splits the same way; both surfaces must agree on what counts as broken.
+  // `info`/`warn` entries are REPORTED, not failures: CI must not go red for an open PR, a hand-made
+  // tree or a running container. The human path below splits the same way.
   const isProblem = (i) => !['info', 'warn'].includes(i.severity);
 
   if (options.json) {
@@ -780,10 +637,8 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     return true;
   }
 
-  // `unintegrated-work` is NOT an inconsistency — it is a worktree doing its
-  // job, reported so the reader knows why no cleanup is offered for it. Counting
-  // it as a problem is how a diagnostic starts nagging people into destroying
-  // things to make the warning go away.
+  // `unintegrated-work` is a worktree doing its job, not an inconsistency: counting it nags people
+  // into destroying work to silence the warning.
   const informational = issues.filter((i) => !isProblem(i));
   const problems = issues.filter(isProblem);
 
@@ -798,9 +653,7 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     console.log(`     ${i.detail}`);
     console.log(`     → ${i.fix}`);
   }
-  // An EMPTY unregistered directory is prunable too — it holds nothing that can
-  // be lost — so the hint must mention it, or the one issue `--prune` now fixes
-  // automatically would still read as a manual chore.
+  // An EMPTY unregistered dir is prunable too, so the hint must mention it.
   const prunable = (i) => i.type === 'registered-missing'
     || i.type === 'dangling-registration'
     || (i.type === 'unregistered-dir' && i.empty);
@@ -817,29 +670,9 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
   return false;
 }
 
-/** Dias a partir dos quais um PR aberto vira aviso. */
 const PR_STALE_DAYS = 7;
 
-/**
- * As inconsistências de PR desta árvore.
- *
- *   pr-awaiting-merge   — PR aberto há muito, sem cópia local: trabalho em
- *                         revisão que nenhuma superfície local reivindica.
- *   pr-merged-not-landed — o PR mergeou mas `archive/{f}` não está aqui. O
- *                         archive viaja no diff do PR, então ou falta um
- *                         `git pull`, ou ele não estava no diff. Branch
- *                         `morph/*` cujo diff nunca tocou
- *                         `.morph/{features,archive}/{f}/` não conta: o nome
- *                         não prova feature (ver pr-files.js).
- *
- * Offline-safe: índice `null` devolve `null`, NUNCA lista vazia — lista vazia
- * afirmaria "perguntei e não achei nada", que é diferente de "não pude
- * perguntar". Achado #3: um `[]` disfarçado de "sem problema" é o que fazia
- * `doctor` imprimir `✓ pull requests` mesmo sem conseguir consultar o `gh`.
- *
- * @returns {Array<{feature:string,type:string,detail:string}>|null}
- *   null = DESCONHECIDO (índice não pôde ser construído); nunca "sem PRs".
- */
+/** `null` = DESCONHECIDO (o índice não pôde ser construído), nunca "sem PRs". */
 function auditPullRequests(root) {
   const index = buildPrIndex(root);
   if (!index) return null;
@@ -874,26 +707,8 @@ function auditPullRequests(root) {
 }
 
 /**
- * `morph-spec doctor --ai` — as cinco checagens de projeto .NET com agentes.
- *
- * **Superfície própria, no molde do `--mcp`, e é decisão, não acidente.** O
- * `--ai` NÃO entra no `--full` nem no `doctor` default:
- *
- * - o renderer do `--full` é `ok → ✓`, `warn → ⚠`, **`else → ✗`** — não tem o
- *   ramo `skip → ○`. Uma checagem de IA lá seria VERMELHA neste repositório
- *   mesmo dizendo "não verificado", e `test/commands/doctor.test.js` exige
- *   `doesNotMatch(out, /✗/)` para `doctor --full` aqui, com a justificativa
- *   escrita no próprio teste: *"every check must be satisfiable here — a
- *   permanently red one teaches nothing"*;
- * - o `doctor` default é o comando mais rodado do dia, e cinco linhas `○`
- *   permanentes em todo projeto sem .NET é ruído com custo e sem informação.
- *
- * Exit code: 1 se houver ao menos um `error`; 0 caso contrário. `warn` e `skip`
- * nunca mudam o código de saída.
- *
- * @param {string} targetPath
- * @param {object} [options] - repassado a `collectAiChecks` (`config`, `deps`)
- * @returns {Promise<Array>} as checagens, para o canário assere-las sem parsear texto
+ * Superfície própria, fora do `--full` (cujo renderer mostra `skip` como ✗) e do default.
+ * Exit 1 só com algum `error`; `warn` e `skip` nunca mudam o código de saída.
  */
 export async function doctorAiCommand(targetPath, options = {}) {
   const { collectAiChecks, aiExitCode, allSkipped } = await import('../../lib/ai/ai-checks.js');
@@ -906,9 +721,7 @@ export async function doctorAiCommand(targetPath, options = {}) {
   const checks = collectAiChecks(targetPath, { config, deps: options.deps ?? {} });
 
   if (allSkipped(checks)) {
-    // Condição 4 do silêncio: nenhuma checagem teve insumo. Uma linha, não
-    // cinco `○` vazios — listar cinco vezes "não verificado" é o ruído que
-    // esta superfície existe para não produzir.
+    // Nenhuma checagem teve insumo: uma linha, não cinco `○` vazios.
     const reasons = [...new Set(checks.map((c) => c.reason))];
     for (const reason of reasons) {
       console.log(chalk.gray(`  ○ Nenhuma das ${checks.length} checagens teve insumo — ${reason}.`));
@@ -954,10 +767,8 @@ export async function doctorAiCommand(targetPath, options = {}) {
 }
 
 export async function doctorCommand(options = {}) {
-  // `--json` and `--prune` only mean something under `--worktrees` or `--procs`. Falling
-  // through to the human health check would hand a script a banner and a table
-  // where it asked for JSON — a caller has no way to notice a flag that was
-  // dropped in silence, so refuse instead of pretending.
+  // `--json`/`--prune` only mean something under `--worktrees` or `--procs`: refuse rather than
+  // drop the flag in silence and hand a script a banner where it asked for JSON.
   const scoped = ['json', 'prune'].filter((f) => options[f]);
   if (scoped.length && !options.worktrees && !options.procs) {
     const flags = scoped.map((f) => `--${f}`).join(' e ');
@@ -980,10 +791,7 @@ export async function doctorCommand(options = {}) {
     }
   }
 
-  // `--ai` é superfície própria (D1). Combiná-la com outra superfície pediria
-  // dois relatórios com dois códigos de saída no mesmo processo — o segundo
-  // apagaria o primeiro em silêncio. Mesmo molde da guarda acima: recusa em
-  // vez de fingir.
+  // `--ai` com outra superfície daria dois códigos de saída no mesmo processo: recusa.
   if (options.ai) {
     const conflicts = ['full', 'mcp', 'worktrees', 'procs'].filter((f) => options[f]);
     if (conflicts.length) {
@@ -996,7 +804,6 @@ export async function doctorCommand(options = {}) {
     return doctorAiCommand(process.cwd(), options);
   }
 
-  // Reset mode: remove morph-managed settings entries
   if (options.reset) {
     const targetPath = process.cwd();
     logger.header('MORPH-SPEC Settings Reset');
@@ -1021,27 +828,18 @@ export async function doctorCommand(options = {}) {
     return;
   }
 
-  // full health check mode
   if (options.full) {
     const frameworkRoot = process.cwd();
     return doctorFullCommand(frameworkRoot);
   }
 
-  // MCP health check mode
   if (options.mcp) {
     return doctorMcpCommand(process.cwd());
   }
 
-  // Worktree reconciliation mode (C2)
   if (options.worktrees) {
     const clean = await doctorWorktreesCommand(process.cwd(), options);
-    // The audit result has to reach the exit code, not just the terminal.
-    // Commander discards an action's return value, so this reported success to
-    // every script while printing "⚠ 5 inconsistência(s)" to the human — a
-    // `doctor --worktrees || echo falhou` in CI or a pre-commit hook saw a
-    // clean run with orphaned worktrees piling up. The flag-misuse branch
-    // above already treats the exit code as this command's signal channel;
-    // only the audit itself was left out of it.
+    // The audit result must reach the exit code: Commander discards an action's return value.
     if (!clean) process.exitCode = 1;
     return clean;
   }
@@ -1069,11 +867,9 @@ export async function doctorCommand(options = {}) {
     }
   };
 
-  // Check versions first
   const cliCheck = await checkCLIOutdated();
   const projectCheck = await checkProjectOutdated(targetPath);
 
-  // CLI Version
   if (cliCheck.latest) {
     if (cliCheck.isOutdated) {
       checks.push({
@@ -1096,7 +892,6 @@ export async function doctorCommand(options = {}) {
     });
   }
 
-  // Project MORPH version
   if (projectCheck.current) {
     if (projectCheck.isOutdated) {
       checks.push({
@@ -1120,7 +915,6 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
-  // Check if morph-spec is in PATH
   const inPath = isMorphSpecInPath();
   if (inPath) {
     checks.push({
@@ -1136,7 +930,6 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
-  // Check CLAUDE.md has morph-spec @import
   const claudeMd = join(targetPath, 'CLAUDE.md');
   const claudeMdStatus = await checkClaudeMdImport(claudeMd);
   if (claudeMdStatus === 'ok') {
@@ -1149,7 +942,6 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check .morph folder
   const morphPath = join(targetPath, '.morph');
   if (await pathExists(morphPath)) {
     checks.push({ name: '.morph/', status: 'ok' });
@@ -1158,7 +950,6 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check config.json
   const configPath = join(morphPath, 'config', 'config.json');
   if (await pathExists(configPath)) {
     try {
@@ -1177,7 +968,6 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check agents.json
   const agentsPath = join(morphPath, 'framework', 'agents.json');
   if (await pathExists(agentsPath)) {
     try {
@@ -1196,11 +986,9 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check standards (either in project .morph/framework/standards/ or in framework package)
   const standardsPath = join(morphPath, 'framework', 'standards');
   const frameworkStdsRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'standards');
   if (await pathExists(standardsPath)) {
-    // Check for VSA standard (core to the framework)
     const vsaStd = await pathExists(join(standardsPath, 'architecture', 'vertical-slice', 'vertical-slice.md')) ||
                    await pathExists(join(standardsPath, 'vertical-slice.md'));
     if (vsaStd) {
@@ -1210,7 +998,6 @@ export async function doctorCommand(options = {}) {
       hasWarnings = true;
     }
   } else if (await pathExists(frameworkStdsRoot)) {
-    // Framework package has standards (dev/global install mode)
     checks.push({ name: 'standards/', status: 'warn', msg: 'not installed in project (run morph-spec init)' });
     hasWarnings = true;
   } else {
@@ -1218,15 +1005,8 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check templates — as of the R3 perf plan (Task 2), setup-infra/update no
-  // longer pre-populate .morph/framework/templates/: template resolution is
-  // layered (template-registry.js / architecture-scanner.js resolveTemplatePath)
-  // and falls back to the npm package's own framework/templates/ when the
-  // project-local copy is absent, which is now the expected default rather
-  // than an error. The project-local copy remains a supported override — if
-  // present, report it as such. The "key templates" check further below
-  // verifies the package copy itself is intact, which is the check that
-  // actually matters now.
+  // A missing project-local templates copy is the default (resolution falls back to the package's
+  // framework/templates/); a local copy is a supported override.
   const templatesPath = join(morphPath, 'framework', 'templates');
   if (await pathExists(templatesPath)) {
     checks.push({ name: 'templates/', status: 'ok', msg: 'local override present' });
@@ -1234,7 +1014,6 @@ export async function doctorCommand(options = {}) {
     checks.push({ name: 'templates/', status: 'ok', msg: 'resolved from package (no local override)' });
   }
 
-  // Check .claude folder
   const claudePath = join(targetPath, '.claude');
   if (await pathExists(claudePath)) {
     const commandsPath = join(claudePath, 'commands');
@@ -1246,7 +1025,6 @@ export async function doctorCommand(options = {}) {
     if (hasCommands && hasSkills) {
       checks.push({ name: '.claude/', status: 'ok' });
 
-      // Check skills link status
       const skillEntries = await fs.readdir(skillsPath, { withFileTypes: true });
       const skillDirs = skillEntries.filter(e => e.isDirectory() || e.isSymbolicLink());
       let linkedCount = 0;
@@ -1255,7 +1033,7 @@ export async function doctorCommand(options = {}) {
         try {
           const stat = await fs.lstat(join(skillsPath, dir.name));
           if (stat.isSymbolicLink()) linkedCount++;
-        } catch { /* ignore */ }
+        } catch {}
       }
 
       if (skillDirs.length > 0) {
@@ -1270,7 +1048,6 @@ export async function doctorCommand(options = {}) {
         }
       }
 
-      // Check .claude/rules/
       const rulesPath = join(claudePath, 'rules');
       if (await pathExists(rulesPath)) {
         const ruleFiles = await fs.readdir(rulesPath);
@@ -1281,23 +1058,18 @@ export async function doctorCommand(options = {}) {
         hasWarnings = true;
       }
 
-      // Check .claude/agents/
       const agentsPathClaude = join(claudePath, 'agents');
       if (await pathExists(agentsPathClaude)) {
         const agentFiles = await fs.readdir(agentsPathClaude);
         const morphAgents = agentFiles.filter(f => f.startsWith('morph-') && f.endsWith('.md'));
         checks.push({ name: '.claude/agents/', status: 'ok', msg: `${morphAgents.length} agents` });
 
-        // Check for missing agents based on stack tags. Empty tags (no config
-        // yet) is NOT a skip: personas install-all by default, so with an
-        // unknown stack ALL personas are expected (agentEligible semantics) —
-        // the exact field failure where only morph-verifier landed and every
-        // domain dispatch fell back to general-purpose.
+        // Empty tags (no config yet) is NOT a skip: personas install-all by default, so ALL are expected.
         try {
           let projectTags = [];
           try {
             projectTags = getProjectTags(await readJson(configPath));
-          } catch { /* no config → expected = all personas */ }
+          } catch {}
           const tagsLabel = projectTags.length > 0 ? projectTags.join(', ') : 'all (stack unknown)';
           const frameworkDir = join(import.meta.dirname, '..', '..', '..', 'framework');
           const { missing } = checkMissingAgents(targetPath, frameworkDir, projectTags);
@@ -1312,12 +1084,11 @@ export async function doctorCommand(options = {}) {
           } else {
             checks.push({ name: 'agents completeness', status: 'ok', msg: `all agents for [${tagsLabel}]` });
           }
-        } catch { /* framework dir not resolvable — skip completeness check */ }
+        } catch {}
       } else {
         checks.push({ name: '.claude/agents/', status: 'warn', msg: 'missing — run morph-spec update' });
         hasWarnings = true;
       }
-      // ── Hook health: verify hook scripts exist ───────────────────────────────
       const settingsLocalPath = join(claudePath, 'settings.local.json');
       if (await pathExists(settingsLocalPath)) {
         try {
@@ -1353,7 +1124,6 @@ export async function doctorCommand(options = {}) {
         hasWarnings = true;
       }
 
-      // ── Skills cliVersion: warn if installed skills reference older CLI ──────
       try {
         const cliVersion = getInstalledCLIVersion();
         if (cliVersion) {
@@ -1375,24 +1145,19 @@ export async function doctorCommand(options = {}) {
             hasWarnings = true;
           }
         }
-      } catch { /* non-fatal */ }
+      } catch {}
 
-      // ── Claude Code Plugins ──────────────────────────────────────────────────
       console.log(chalk.cyan('\n  Claude Code Plugins (required by morph-spec init)'));
       const pluginsFile = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
       let pluginData = { plugins: {} };
       try {
         pluginData = JSON.parse(await fs.readFile(pluginsFile, 'utf8'));
-      } catch { /* file may not exist */ }
+      } catch {}
       const pluginStatus = checkInstalledPlugins(pluginData.plugins || {});
       check('context7 plugin', pluginStatus.context7, false,
         'Run: morph-spec install-plugin context7');
     } else {
-      // `.claude/` exists but lacks commands/ and/or skills/ — ranges from a
-      // partial install to the full-wipe incident this command exists to catch
-      // (folder survives, 0 items — doctor used to shrug this off as a vague
-      // warning with no fix). Count what IS still there: near-total loss is an
-      // ERROR with the actionable command, not a warning that reads as optional.
+      // `.claude/` without commands/ or skills/: count what is left; near-total loss is an ERROR with the fix.
       const pieces = ['agents', 'rules', 'skills', 'commands'];
       const present = [];
       for (const piece of pieces) {
@@ -1422,7 +1187,6 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check state.json
   const statePath = join(targetPath, '.morph', 'state.json');
   if (await pathExists(statePath)) {
     try {
@@ -1443,10 +1207,7 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
-  // Feature-lifecycle consistency — the consolidated inconsistency report:
-  // gate-order violations (N approved with N-1 pending), identity-less
-  // features (no description), orphan folders and stale index entries. Warn
-  // only (advisory); the per-feature detail is printed after the summary.
+  // Warn only (advisory); the per-feature detail is printed after the summary.
   const lifecycleIssues = auditFeatureLifecycle(targetPath);
   if (lifecycleIssues.length === 0) {
     checks.push({ name: 'feature lifecycle', status: 'ok' });
@@ -1459,13 +1220,8 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
-  // Pull requests — o pendurado (aberto há dias sem cópia local) e o mergeado
-  // que não pousou (archive não chegou nesta árvore). Offline-safe: sem `gh`,
-  // sem origin no GitHub, ou qualquer falha, `auditPullRequests` nunca lança
-  // (achado #7 — mesma guarda fail-open que `fleet-scanner.js` já usa para a
-  // síntese idêntica) e devolve `null` — achado #3: um índice desconhecido
-  // renderiza como "não verificado", nunca como `✓ ok`, porque `[]` e
-  // "não pude perguntar" não são a mesma coisa.
+  // Offline-safe: `auditPullRequests` never throws and returns `null` when it cannot ask, which
+  // renders as "não verificado", never `✓`.
   let prIssues;
   try {
     prIssues = auditPullRequests(targetPath);
@@ -1485,8 +1241,7 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
-  // Codebase graph — opcional (ADR-002). Nunca 'missing': um projeto que não
-  // usa o grafo tem de continuar com o doctor verde.
+  // Opcional: nunca 'missing', um projeto que não usa o grafo segue com o doctor verde.
   const graphAudit = auditGraph(targetPath);
   if (graphAudit.status === 'warn') {
     checks.push({ name: 'codebase graph', status: 'warn', msg: graphAudit.msg });
@@ -1506,9 +1261,8 @@ export async function doctorCommand(options = {}) {
       checks.push(storeCheck);
       if (storeCheck.status === 'warn') hasWarnings = true;
     }
-  } catch { /* fail-open */ }
+  } catch {}
 
-  // Check key templates exist (in framework package, not project copy)
   const frameworkTemplatesRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
   const keyTemplates = [
     { name: 'plan.md', path: join(frameworkTemplatesRoot, 'docs', 'plan.md') },
@@ -1531,7 +1285,6 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check Node.js version
   const nodeVersion = process.version;
   const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
   if (majorVersion >= 18) {
@@ -1541,7 +1294,6 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
-  // Display results
   for (const check of checks) {
     if (check.status === 'ok') {
       console.log(chalk.green(`  ✓ ${check.name}`));
@@ -1552,15 +1304,11 @@ export async function doctorCommand(options = {}) {
     } else if (check.status === 'error') {
       console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(` (${check.msg})`));
     } else if (check.status === 'skip') {
-      // "Não verificado" — nem ok nem falha. Nunca soma em hasWarnings/hasErrors:
-      // um `gh` indisponível não pode deixar o doctor mais barulhento nem mudar
-      // o exit code (achado #3).
+      // "Não verificado" nunca soma em hasWarnings/hasErrors: um `gh` indisponível não muda o exit code.
       console.log(chalk.gray(`  ○ ${check.name}`) + chalk.gray(check.msg ? ` (${check.msg})` : ''));
     }
   }
 
-  // Per-feature detail for the lifecycle inconsistencies (item: doctor lists
-  // what's already wrong in the repo, e.g. review approved with plan pending).
   if (lifecycleIssues.length) {
     logger.blank();
     console.log(chalk.yellow('  Feature lifecycle inconsistencies:'));
@@ -1570,8 +1318,6 @@ export async function doctorCommand(options = {}) {
     console.log(chalk.gray("    Fix: 'morph-spec approve' (order), '--description' on create, or 'morph-spec delete' for dead scaffolds."));
   }
 
-  // Per-feature detail for the PR inconsistencies (item: pendurado ou merge
-  // que não pousou).
   if (prIssues?.length) {
     logger.blank();
     console.log(chalk.yellow('  Pull requests pendentes:'));