@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/commands/project/update.js

@@ -39,11 +39,6 @@ import {
   writeGraphifyignore, describeOutdatedIgnore, graphifyignoreTracked,
 } from '../../lib/graph/graphifyignore.js';
 
-/**
- * Backup user's config.json before cleaning
- * @param {string} morphPath - Path to .morph directory
- * @returns {Promise<object|null>} Backup of config.json or null
- */
 async function backupUserConfig(morphPath) {
   try {
     const configPath = join(morphPath, 'config', 'config.json');
@@ -52,40 +47,18 @@ async function backupUserConfig(morphPath) {
       return config;
     }
   } catch (error) {
-    // If backup fails, return null and continue
   }
   return null;
 }
 
-/**
- * Os DEZ diretórios que `cleanFrameworkDirs` apaga por inteiro, sem condição.
- *
- * O número está pinado à mão em `test/commands/update-dry-run.test.js`
- * (`DIRETORIOS_APAGADOS_POR_INTEIRO`), com os dez caminhos escritos: derivar a
- * expectativa desta função deixaria a suíte cega a uma entrada removida.
- *
- * Exportado porque o relatório do `--dry-run` é obrigado a nomeá-los: "update"
- * não sugere a ninguém que `.claude/skills/` e `.claude/agents/` são apagados
- * inteiros antes da reinstalação.
- *
- * @param {string} morphPath
- * @param {string} targetPath
- * @returns {string[]}
- */
 export function frameworkDirsToClean(morphPath, targetPath) {
   const claudeDir = join(targetPath, '.claude');
   return [
-    // NOTE: framework/templates is intentionally NOT in this list (R3 perf
-    // plan, Task 2). It's no longer copied/refreshed here — see
-    // reconcileLegacyTemplatesCopy() below, which decides per-run whether a
-    // pre-existing local copy is safe to remove or must be preserved as a
-    // user override. Blindly deleting it here (the old behavior) destroyed
-    // any customization on every single `update` run, override or not.
+    // framework/templates is left out on purpose: reconcileLegacyTemplatesCopy() decides whether
+    // a local copy is a user override to preserve.
     join(morphPath, 'framework', 'standards'),
     join(morphPath, 'framework', 'hooks'),
     join(morphPath, 'framework', 'schemas'),
-    // Não é mais instalado: fica na lista para apagar o de instalações antigas.
-    join(morphPath, 'framework', 'rubrics'),
     join(morphPath, 'framework', 'evals'),
     join(morphPath, 'config'),
     join(claudeDir, 'commands'),
@@ -95,14 +68,6 @@ export function frameworkDirsToClean(morphPath, targetPath) {
   ];
 }
 
-/**
- * Emite (e, fora do dry, executa) a remoção recursiva de um diretório.
- *
- * Um efeito por arquivo, mais um pelo diretório. É a varredura que a §5.2 do
- * spec exige, e é dela que sai a contagem "N arquivos" do relatório.
- *
- * @returns {number} arquivos varridos
- */
 function sweepRemove(dir, fx) {
   let entries;
   try {
@@ -125,23 +90,8 @@ function sweepRemove(dir, fx) {
 }
 
 /**
- * Clean framework directories but preserve .morph/project/.
- *
- * **A armadilha que esta função resolve (decisions.md D6).** Ela apaga
- * exatamente os destinos que os laços de limpeza de órfão DEPOIS varrem
- * (`skills-installer.js`, `agents-installer.js`, `installRulesForStack`).
- * Numa execução real esses laços sempre encontram diretório vazio e não
- * apagam nada. Num `--dry-run` ingênuo nada foi apagado, eles encontrariam o
- * diretório POPULADO e o relatório preveria remoções que a execução real
- * nunca faz — errado na direção que assusta o usuário. Como o clean é
- * incondicional e total, a previsão correta é "tudo que hoje está sob estes
- * dez é apagado", e os laços de órfão ficam calados em dry: são provadamente
- * subsumidos.
- *
- * @param {string} morphPath - Path to .morph directory
- * @param {string} targetPath - Project root path
- * @param {ReturnType<import('../../lib/installers/effects.js').createEffects>} fx
- * @returns {Array<{ dir: string, files: number }>} o que foi (ou seria) apagado
+ * Os laços de órfão depois varrem estes mesmos destinos já vazios: em dry eles ficam calados,
+ * senão o relatório preveria remoções que a execução real nunca faz.
  */
 function cleanFrameworkDirs(morphPath, targetPath, fx) {
   const cleaned = [];
@@ -151,31 +101,20 @@ function cleanFrameworkDirs(morphPath, targetPath, fx) {
         cleaned.push({ dir, files: sweepRemove(dir, fx) });
       }
     } catch (error) {
-      // Continue even if cleanup fails for one directory
     }
   }
   return cleaned;
 }
 
-/**
- * Restore user's config.json after reinstallation
- * @param {string} morphPath - Path to .morph directory
- * @param {string} targetPath - Project root path
- * @param {object|null} configBackup - Backup of config.json
- * @param {string} currentVersion - Current CLI version
- * @param {ReturnType<import('../../lib/installers/effects.js').createEffects>} fx
- */
 function restoreUserConfig(morphPath, targetPath, configBackup, currentVersion, fx) {
   const configDir = join(morphPath, 'config');
   fx.ensureDir(configDir);
   const configPath = join(configDir, 'config.json');
 
   if (configBackup) {
-    // Preserve user data but update framework version
     configBackup.frameworkVersion = currentVersion;
     fx.writeJson(configPath, configBackup);
   } else {
-    // Create basic config if none existed
     const dirName = targetPath.split(/[\\/]/).pop();
     const defaultConfig = {
       framework: 'global',
@@ -189,15 +128,7 @@ function restoreUserConfig(morphPath, targetPath, configBackup, currentVersion,
   }
 }
 
-/**
- * `.morph/state.json` já está no índice do git?
- *
- * SONDA, separada da mutação de propósito: sondar é ler, e ler acontece nos
- * dois modos. É o que faz previsão e execução concordarem sobre este efeito.
- *
- * @param {string} targetPath
- * @returns {boolean}
- */
+/** Sonda separada da mutação: ler acontece nos dois modos, e é o que faz previsão e execução concordarem. */
 export function stateJsonIsTracked(targetPath) {
   try {
     const isRepo = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
@@ -214,38 +145,14 @@ export function stateJsonIsTracked(targetPath) {
   }
 }
 
-/**
- * Untrack an already-committed `.morph/state.json` from git.
- *
- * Before v5's per-feature model, `.morph/state.json` was committed. Adding it to
- * `.gitignore` does NOT stop git from tracking a file already in the index — so on
- * exactly the repos that had the P1 sweep problem, `git commit -a` would keep
- * staging state.json. This runs `git rm --cached` once so the next commit drops it.
- * The working-tree file is left in place (it's rebuilt from feature.json on load).
- *
- * Mildly destructive (mutates the git index), but no data is lost: state.json is a
- * derivable index. Fail-open — a non-git project or any git error is a silent no-op.
- *
- * @param {string} targetPath - Project root
- * @param {ReturnType<import('../../lib/installers/effects.js').createEffects>} fx
- * @returns {boolean} true if state.json was untracked, false otherwise
- */
 export function untrackCommittedStateJson(targetPath, fx = createEffects({ dryRun: false })) {
-  if (!stateJsonIsTracked(targetPath)) return false; // not tracked — nothing to migrate
+  if (!stateJsonIsTracked(targetPath)) return false;
   return fx.gitIndex('rm --cached --quiet', '.morph/state.json', { cwd: targetPath });
 }
 
 /**
- * Os dois registros de versão que um projeto morph-spec carrega.
- *
- * `.morph/.morphversion → morphVersion` é o que o `update` LÊ para decidir.
- * `config.json → frameworkVersion` é o que o `update` ESCREVE e nunca lê para
- * decidir coisa alguma — e no MORPH_OS os dois divergem por um major inteiro
- * (7.5.0 contra 6.0.0). Um freio calibrado no campo errado recusaria (ou
- * liberaria) com base num número que ninguém mantém.
- *
- * @param {string} targetPath
- * @returns {Promise<{ morphVersion: string|null, frameworkVersion: string|null, diverged: boolean }>}
+ * `.morphversion` é o que o `update` LÊ para decidir; `config.json → frameworkVersion` só é
+ * escrito e pode divergir por um major inteiro.
  */
 export async function readVersionRegisters(targetPath) {
   let morphVersion = null;
@@ -253,30 +160,17 @@ export async function readVersionRegisters(targetPath) {
   try {
     const v = await readJson(join(targetPath, '.morph', '.morphversion'));
     morphVersion = typeof v?.morphVersion === 'string' ? v.morphVersion : null;
-  } catch { /* ausente ou ilegível — indeterminável, e isso é um dado */ }
+  } catch {}
   try {
     const c = await readJson(join(targetPath, '.morph', 'config', 'config.json'));
     frameworkVersion = typeof c?.frameworkVersion === 'string' ? c.frameworkVersion : null;
-  } catch { /* idem */ }
+  } catch {}
 
   const diverged = Boolean(morphVersion && frameworkVersion && morphVersion !== frameworkVersion);
   return { morphVersion, frameworkVersion, diverged };
 }
 
-/**
- * As linhas da recusa do freio de major.
- *
- * Separada do comando para ser testável sem rodar o `update`, e porque a
- * mensagem carrega três obrigações: a versão instalada, a versão de destino e
- * **o registro de onde a versão instalada foi lida**. Quando os dois registros
- * discordam, imprime OS DOIS e diz qual decidiu — escolher em silêncio é
- * acertar metade das vezes e nunca saber qual metade.
- *
- * @param {{ refuse: boolean, reason: string|null, jump: number|null }} verdict
- * @param {{ morphVersion: string|null, frameworkVersion: string|null, diverged: boolean }} registers
- * @param {string} targetVersion
- * @returns {string[]}
- */
+/** Quando os dois registros discordam, imprime OS DOIS e diz qual decidiu. */
 export function majorGuardLines(verdict, registers, targetVersion) {
   const lines = [];
   if (verdict.reason === 'unknown-installed') {
@@ -298,7 +192,6 @@ export function majorGuardLines(verdict, registers, targetVersion) {
   return lines;
 }
 
-/** Rótulo humano de cada verbo, para agrupar o relatório por natureza do efeito. */
 const VERB_GROUPS = {
   remove: 'Apagar',
   ensureDir: 'Criar diretório',
@@ -317,20 +210,8 @@ function isUnder(path, root) {
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
 }
 
-/**
- * ONDE um efeito age.
- *
- * Para quase todo verbo é o próprio `target`. Para `spawn` NÃO é: o `target`
- * de um spawn é o binário (`node`), e classificar por ele esconderia
- * exatamente o efeito que a §5.3 obriga a nomear — `generate-refs.js`
- * escrevendo `framework/hooks/shared/phase-utils.js` DENTRO do pacote da CLI.
- *
- * O script sai de `effect.args`, o **array**, nunca de um split do `detail`
- * por espaço: o caminho real deste pacote é
- * `R:\Polymorphism Tech\repos\...` — um espaço no meio, e o split devolvia
- * `Tech\repos\...\generate-refs.js`, que não é subcaminho de nada. O efeito ia
- * calado para o grupo errado. Medido rodando o comando de verdade.
- */
+// O `target` de um spawn é o binário (`node`): classifica pelo script em `effect.args`, o array —
+// um split do `detail` por espaço quebra em caminho com espaço.
 function effectLocation(effect) {
   if (effect.verb !== 'spawn') return effect.target;
   const args = Array.isArray(effect.args) ? effect.args : [];
@@ -338,26 +219,12 @@ function effectLocation(effect) {
   return script || effect.target;
 }
 
-/**
- * Imprime o relatório de efeitos.
- *
- * Três grupos ganham nome próprio, porque o usuário não os adivinharia da
- * palavra "update": o que é apagado por INTEIRO antes da reinstalação, o que
- * acontece FORA do projeto, e o que é escrito DENTRO do pacote da CLI (que num
- * `npm link` de desenvolvimento é o próprio repositório do framework).
- *
- * @param {Array} effects - saída de `fx.list()`
- * @param {object} context
- */
 export function renderEffectsReport(effects, context) {
   const { targetPath, packageRoot, dryRun, cleaned = [], notices = [] } = context;
   const globalClaudeDir = join(homedir(), '.claude');
 
   logger.blank();
-  // O cabeçalho não pode dizer "nem executado": em dry o `spawn` do
-  // `generate-refs.js` RODA, na variante `--check`, que verifica e não escreve.
-  // Prometer silêncio total e rodar um processo é mentir num detalhe pequeno —
-  // e é o tipo de detalhe pequeno que faz o usuário parar de acreditar no resto.
+  // Não diz "nem executado": em dry o spawn de `generate-refs.js --check` roda.
   logger.info(dryRun
     ? 'Relatório do --dry-run — nada foi escrito, apagado nem removido '
       + '(o único processo executado é a variante `--check` do gerador, que só verifica):'
@@ -419,7 +286,7 @@ export function renderEffectsReport(effects, context) {
     + `${outside.length} fora do projeto, ${inPackage.length} dentro do pacote da CLI.`);
   logger.blank();
 
-  // Risco conhecido, reportado em vez de escondido (decisions.md D9): o backup
+  // Risco conhecido, reportado em vez de escondido: o backup
   // de `config.json` só existe em memória durante a execução.
   logger.dim('Nota: durante uma execução real o backup de `.morph/config/config.json` existe apenas '
     + 'em memória — uma falha no meio do caminho deixa o arquivo apagado. Follow-up nomeado.');
@@ -437,11 +304,7 @@ export async function updateCommand(options = {}) {
 
   logger.header(dryRun ? 'MORPH-SPEC Update (--dry-run)' : 'MORPH-SPEC Update');
 
-  // ── Versões primeiro, e NADA de mutação antes do freio ───────────────────
-  // O passo de criação de diretórios ficava aqui em cima e criava `.morph/`
-  // ANTES de qualquer guarda. Recusar depois de mutar é meio-estado — o mesmo
-  // defeito que o `finish --merge` pagou uma vez na v8.24.3 ("valida a raiz
-  // ANTES de arquivar").
+  // Nenhuma mutação antes do freio: recusar depois de mutar deixa meio-estado.
   const spinner = ora('Checking versions...').start();
   // `cliCheck` é injetável para que o canário de igualdade dry × real não
   // dependa do registro npm; a CLI nunca o passa.
@@ -450,7 +313,6 @@ export async function updateCommand(options = {}) {
   const registers = await readVersionRegisters(targetPath);
   spinner.stop();
 
-  // Display version info
   logger.blank();
   logger.info('Version Status:');
   logger.dim(`  CLI version: ${cliCheck.current}`);
@@ -467,10 +329,7 @@ export async function updateCommand(options = {}) {
   }
   logger.blank();
 
-  // If CLI is outdated, stop and instruct user.
-  // O `--dry-run` PASSA POR CIMA desta saída antecipada: bloquear o relatório
-  // justamente quando o usuário está decidindo se atualiza seria inútil. O
-  // aviso vira a primeira linha do relatório.
+  // O `--dry-run` passa por cima desta saída antecipada: o aviso vira a 1ª linha do relatório.
   if (cliCheck.isOutdated && cliCheck.latest) {
     if (dryRun) {
       notices.push(`A CLI local está desatualizada (${cliCheck.current} → ${cliCheck.latest}). `
@@ -500,7 +359,6 @@ export async function updateCommand(options = {}) {
     }
   }
 
-  // ── Freio de major, ANTES de qualquer mutação ────────────────────────────
   const needsInitialization = !(await pathExists(morphPath));
   const targetVersion = cliCheck.current ?? getInstalledCLIVersion();
   const verdict = needsInitialization
@@ -514,8 +372,7 @@ export async function updateCommand(options = {}) {
     if (force) {
       notices.push(`Freio de major DISPENSADO por \`--force\`: ${lines[0]}`);
     } else if (dryRun) {
-      // UC-27 A1: em dry ninguém precisa ser protegido de nada, e esconder o
-      // relatório seria esconder justamente a informação que motivou o comando.
+      // Em dry não há recusa: esconder o relatório esconderia a informação que motivou o comando.
       notices.push(...lines);
     } else {
       logger.error(lines[0]);
@@ -531,7 +388,6 @@ export async function updateCommand(options = {}) {
       + `Quem decide é o primeiro.`);
   }
 
-  // ── A partir daqui, tudo passa pelo coletor ──────────────────────────────
   if (needsInitialization) {
     logger.warn('MORPH not fully initialized. Creating basic structure...');
     fx.ensureDir(join(morphPath, 'context'));
@@ -541,19 +397,16 @@ export async function updateCommand(options = {}) {
     logger.dim('  ✓ Created .morph directory structure');
   }
 
-  // Proceed with update
   const updateSpinner = ora(dryRun ? 'Prevendo efeitos...' : 'Updating MORPH-SPEC...').start();
   let cleaned = [];
 
   try {
-    // Backup user config before cleaning
     updateSpinner.text = 'Backing up user configuration...';
     const configBackup = await backupUserConfig(morphPath);
     if (configBackup) {
       logger.dim('  ✓ User config backed up');
     }
 
-    // Clean framework directories (preserve .morph/project/)
     updateSpinner.text = 'Cleaning old framework files...';
     cleaned = cleanFrameworkDirs(morphPath, targetPath, fx);
     logger.dim('  ✓ Old framework files removed');
@@ -561,9 +414,6 @@ export async function updateCommand(options = {}) {
     const updateTemplates = !options.standards || options.templates;
     const updateStandards = !options.templates || options.standards;
 
-    // Templates are no longer copied to .morph/framework/templates/ (Task 2,
-    // R3 perf plan) — see reconcileLegacyTemplatesCopy()'s doc comment for
-    // why. Only reconcile a leftover copy from a pre-R3 install.
     let templatesReconcile = 'absent';
     if (updateTemplates) {
       updateSpinner.text = 'Checking for a legacy templates copy...';
@@ -571,7 +421,6 @@ export async function updateCommand(options = {}) {
       templatesReconcile = reconcileLegacyTemplatesCopy(templatesDest, projectCheck.current, fx);
     }
 
-    // Update standards
     if (updateStandards) {
       updateSpinner.text = 'Updating standards...';
       const standardsSrc = join(contentDir, 'framework', 'standards');
@@ -579,7 +428,6 @@ export async function updateCommand(options = {}) {
       fx.copyDir(standardsSrc, standardsDest);
     }
 
-    // Update hooks (runtime hook scripts under .morph/framework/hooks/)
     updateSpinner.text = 'Updating hooks...';
     const hooksSrc = join(__dirname, '..', '..', '..', 'framework', 'hooks');
     const hooksDest = join(morphPath, 'framework', 'hooks');
@@ -587,7 +435,6 @@ export async function updateCommand(options = {}) {
       fx.copyDir(hooksSrc, hooksDest);
     }
 
-    // Update agents.json (sourced from framework/ — canonical single source of truth)
     updateSpinner.text = 'Updating agents configuration...';
     const agentsSrc = join(__dirname, '..', '..', '..', 'framework', 'agents.json');
     const agentsDest = join(morphPath, 'framework', 'agents.json');
@@ -595,7 +442,6 @@ export async function updateCommand(options = {}) {
       fx.copyFile(agentsSrc, agentsDest);
     }
 
-    // Paridade com setup-infra 7c/8b/8c/8d: sem isto o charter e os evals instalados ficam velhos.
     updateSpinner.text = 'Updating charter, schemas and evals...';
     const canonicalFrameworkDir = join(__dirname, '..', '..', '..', 'framework');
     for (const file of ['MORPH.md', 'phases.json']) {
@@ -610,18 +456,13 @@ export async function updateCommand(options = {}) {
         fx.copyDir(src, join(morphPath, 'framework', dir));
       }
     }
-    // CLI.md vive em framework/docs/ na fonte mas instala achatado em
-    // .morph/framework/CLI.md (o CLAUDE.md residente aponta para lá) —
-    // por isso não entra no loop de nomes acima.
+    // CLI.md instala achatado em .morph/framework/CLI.md, por isso fica fora do loop acima.
     const cliMdSrc = join(canonicalFrameworkDir, 'docs', 'CLI.md');
     if (await pathExists(cliMdSrc)) {
       fx.copyFile(cliMdSrc, join(morphPath, 'framework', 'CLI.md'));
     }
 
-    // Regenerate derived files (phase-utils.js, skill output tables) from output-schema.js.
-    // Escreve DENTRO do pacote da CLI — num `npm link` de desenvolvimento, no
-    // próprio repositório do framework. Em dry a variante `--check` roda no
-    // lugar: ela verifica e não escreve.
+    // Escreve DENTRO do pacote da CLI (o repositório do framework num `npm link`); em dry roda `--check`.
     updateSpinner.text = 'Syncing generated refs...';
     try {
       const generateScript = join(__dirname, '..', '..', '..', 'scripts', 'generate-refs.js');
@@ -634,24 +475,18 @@ export async function updateCommand(options = {}) {
         }
       }
     } catch {
-      // Non-fatal: generator unavailable or files already in sync
     }
 
-    // Update .claude commands and skills
-    // Source: framework/ (canonical for all stacks)
     updateSpinner.text = 'Setting up Claude Code integration...';
     const frameworkDir = join(__dirname, '..', '..', '..', 'framework');
     const claudeDest = join(targetPath, '.claude');
 
-    // Compute project tags for stack-aware installation of skills, agents, and rules.
-    // MUST come from the pre-clean backup: cleanFrameworkDirs() deleted .morph/config/
-    // above and restoreUserConfig() only runs at the end — re-reading the file here
-    // yields [] and silently downgrades the whole install to universal-only assets
-    // (the ".claude/agents/ only has morph-evaluator.md after update" bug).
+    // MUST come from the pre-clean backup: cleanFrameworkDirs() deleted .morph/config/ and re-reading
+    // it here yields [], silently downgrading the install to universal-only assets.
     let projectTags = [];
     try {
       if (configBackup) projectTags = getProjectTags(configBackup);
-    } catch { /* ignore — malformed config */ }
+    } catch {}
 
     let commandsCopied = false;
     const commandsSrc = join(frameworkDir, 'commands');
@@ -664,18 +499,13 @@ export async function updateCommand(options = {}) {
       logger.warn('  ⚠ framework/commands/ source missing — commands not updated');
     }
 
-    // Sync morph skills to .claude/skills/ for native Claude Code discovery
     updateSpinner.text = 'Syncing morph skills to .claude/skills/...';
     const skillsResult = await installSkills(targetPath, { projectTags, fx });
 
-    // Sync native subagents to .claude/agents/
     updateSpinner.text = 'Syncing agents to .claude/agents/...';
     const agentsResult = await installAgents(targetPath, frameworkDir, { projectTags, fx });
     await installDomainAgents(targetPath, frameworkDir, { projectTags, fx });
 
-    // Sync path-scoped rules to .claude/rules/ — stack-filtered with orphan
-    // cleanup (parity with setup-infra), so `update` is a true superset of
-    // `setup-infra --reinstall` and also covers project.stack changes.
     updateSpinner.text = 'Syncing rules to .claude/rules/...';
     const rulesSrc = join(frameworkDir, 'rules');
     const rulesDest = join(claudeDest, 'rules');
@@ -685,8 +515,6 @@ export async function updateCommand(options = {}) {
       rulesResult = installRulesForStack(rulesSrc, rulesDest, projectTags, fx);
     }
 
-    // Sync runtime CLAUDE.md to .claude/CLAUDE.md and derive the personas
-    // block from what installAgents actually installed (managed markers).
     updateSpinner.text = 'Syncing .claude/CLAUDE.md...';
     const runtimeSrc = join(frameworkDir, 'CLAUDE.md');
     const runtimeDest = join(claudeDest, 'CLAUDE.md');
@@ -699,45 +527,34 @@ export async function updateCommand(options = {}) {
       });
     }
 
-    // Sync statusline globally to ~/.claude/
     updateSpinner.text = 'Syncing statusline to ~/.claude/...';
     const HOOKS_SRC = join(__dirname, '..', '..', '..', 'framework', 'hooks', 'claude-code');
     try {
       await installGlobalStatusline(HOOKS_SRC, null, { fx });
     } catch {
-      // Non-critical: global dir may not be writable in all environments
       logger.dim('  ⚠ Could not install statusline globally (non-critical)');
     }
 
-    // Update Claude Code hooks in .claude/settings.local.json
     updateSpinner.text = 'Updating Claude Code hooks...';
     const hooksResult = await installClaudeHooks(targetPath, { fx });
 
-    // Ensure root CLAUDE.md has morph-spec @import (preserves user content)
     updateSpinner.text = 'Checking CLAUDE.md import...';
     const claudeMdDest = join(targetPath, 'CLAUDE.md');
     await injectMorphImport(claudeMdDest, fx);
 
-    // Restore user config after framework reinstallation
     updateSpinner.text = 'Restoring user configuration...';
     restoreUserConfig(morphPath, targetPath, configBackup, cliCheck.current, fx);
     logger.dim('  ✓ User config restored with updated framework version');
 
-    // Update .gitignore + .gitattributes with current morph rules
     updateSpinner.text = 'Updating .gitignore + .gitattributes...';
     await updateGitignore(targetPath, fx);
     await ensureGitattributes(targetPath, fx);
 
     updateSpinner.text = 'Editor excludes for worktrees (.vscode/settings.json)...';
-    try { applyEditorSettings(targetPath, { fx }); } catch { /* fail-open */ }
-
-    // Migration: a .graphifyignore the previous version generated and nobody
-    // edited is swapped for the current one when its RULES change (test doubles
-    // and fixtures back in the graph — a header-only difference is left alone);
-    // an edited one is left alone, with the change to make. Only an existing
-    // file — the graph is opt-in, and `graph build` writes it. A tracked file
-    // reaches worktrees and teammates only once committed: each checkout reads
-    // its own.
+    try { applyEditorSettings(targetPath, { fx }); } catch {}
+
+    // Swap an unedited generated .graphifyignore when its RULES change (header-only diffs are left);
+    // an edited one is left alone with the change printed. Only an existing file: the graph is opt-in.
     let graphIgnore = null;
     if (existsSync(join(targetPath, '.graphifyignore'))) {
       updateSpinner.text = 'Checking .graphifyignore...';
@@ -749,11 +566,8 @@ export async function updateCommand(options = {}) {
       }
     }
 
-    // Migration: untrack a pre-v5 committed state.json so it stops being swept
-    // into feature commits. Gitignore alone can't do this for an already-tracked file.
     const untracked = untrackCommittedStateJson(targetPath, fx);
 
-    // Update .morphversion
     updateSpinner.text = 'Saving version info...';
     await saveProjectMorphVersion(targetPath, cliCheck.current, fx);
 
@@ -761,11 +575,9 @@ export async function updateCommand(options = {}) {
     logger.blank();
 
     if (!dryRun) {
-      // The dashboard's portfolio learns about the project here (fail-open;
-      // outside the project, so not an effect of the update itself).
+      // Outside the project, so not an effect of the update itself.
       registerProject(targetPath, 'update');
 
-      // Show version change
       if (projectCheck.current && projectCheck.current !== cliCheck.current) {
         logger.success(`Updated: ${projectCheck.current} → ${cliCheck.current}`);
       } else if (!projectCheck.current) {
@@ -786,10 +598,8 @@ export async function updateCommand(options = {}) {
         }
       }
 
-      // Counts make a silent stack-filter downgrade visible at a glance —
-      // a dotnet project reporting "1 persona" is a red flag, not a success.
-      // Display only compact tags: project.integrations entries are long
-      // free-text descriptions and would flood the summary line.
+      // Counts make a silent stack-filter downgrade visible (a dotnet project with "1 persona");
+      // only compact tags, since integrations are long free text.
       const compactTags = projectTags.filter(t => !t.includes(' '));
       const tagsLabel = compactTags.length > 0 ? compactTags.join('+') : 'universal only';
       logger.dim(`  ✓ .claude/settings.local.json (${hooksResult.installed} hooks installed)`);
@@ -811,9 +621,7 @@ export async function updateCommand(options = {}) {
       logger.info('Your config.json was preserved.');
     }
 
-    // O resumo sai de `list()` NOS DOIS MODOS — é essa escolha que faz um
-    // ponto de emissão esquecido sumir das duas saídas ao mesmo tempo, em vez
-    // de só do `--dry-run`.
+    // O resumo sai de `list()` NOS DOIS MODOS: um ponto de emissão esquecido some das duas saídas.
     renderEffectsReport(fx.list(), {
       targetPath, packageRoot: contentDir, dryRun, cleaned, notices,
     });