@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/commands/project/update.js

@@ -1,21 +1,17 @@
-import { join, dirname } from 'path';
+import { join, dirname, relative, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
-import { existsSync } from 'fs';
+import { existsSync, readdirSync } from 'fs';
+import { homedir } from 'os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-import fs from 'fs-extra';
 import ora from 'ora';
 import chalk from 'chalk';
 import { logger } from '../../utils/logger.js';
 import {
   getContentDir,
-  copyDirectory,
-  copyFile,
   pathExists,
-  ensureDir,
   readJson,
-  writeJson,
   updateGitignore,
   ensureGitattributes
 } from '../../utils/file-copier.js';
@@ -24,7 +20,10 @@ import {
   checkProjectOutdated,
   saveProjectMorphVersion,
   getUpdateInstructions,
-  detectInstallMethod
+  detectInstallMethod,
+  getInstalledCLIVersion,
+  majorJump,
+  MAJOR_JUMP_LIMIT
 } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
@@ -33,6 +32,7 @@ import { injectMorphImport } from '../../utils/claude-md-injector.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateClaudeMdAgentsBlock, installRulesForStack } from '../../scripts/setup-infra.js';
 import { reconcileLegacyTemplatesCopy } from '../../lib/installers/templates-reconcile.js';
+import { createEffects } from '../../lib/installers/effects.js';
 
 /**
  * Backup user's config.json before cleaning
@@ -53,13 +53,23 @@ async function backupUserConfig(morphPath) {
 }
 
 /**
- * Clean framework directories but preserve .morph/project/
- * @param {string} morphPath - Path to .morph directory
- * @param {string} targetPath - Project root path
+ * 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[]}
  */
-async function cleanFrameworkDirs(morphPath, targetPath) {
+export function frameworkDirsToClean(morphPath, targetPath) {
   const claudeDir = join(targetPath, '.claude');
-  const dirsToClean = [
+  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
@@ -77,16 +87,68 @@ async function cleanFrameworkDirs(morphPath, targetPath) {
     join(claudeDir, 'skills'),
     join(claudeDir, 'agents'),
   ];
+}
+
+/**
+ * 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 {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let files = 0;
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() && !entry.isSymbolicLink()) {
+      files += sweepRemove(full, fx);
+    } else {
+      fx.remove(full);
+      files += 1;
+    }
+  }
+  fx.remove(dir);
+  return files;
+}
 
-  for (const dir of dirsToClean) {
+/**
+ * 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
+ */
+function cleanFrameworkDirs(morphPath, targetPath, fx) {
+  const cleaned = [];
+  for (const dir of frameworkDirsToClean(morphPath, targetPath)) {
     try {
-      if (await pathExists(dir)) {
-        await fs.remove(dir);
+      if (existsSync(dir)) {
+        cleaned.push({ dir, files: sweepRemove(dir, fx) });
       }
     } catch (error) {
       // Continue even if cleanup fails for one directory
     }
   }
+  return cleaned;
 }
 
 /**
@@ -95,16 +157,17 @@ async function cleanFrameworkDirs(morphPath, targetPath) {
  * @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
  */
-async function restoreUserConfig(morphPath, targetPath, configBackup, currentVersion) {
+function restoreUserConfig(morphPath, targetPath, configBackup, currentVersion, fx) {
   const configDir = join(morphPath, 'config');
-  await ensureDir(configDir);
+  fx.ensureDir(configDir);
   const configPath = join(configDir, 'config.json');
 
   if (configBackup) {
     // Preserve user data but update framework version
     configBackup.frameworkVersion = currentVersion;
-    await writeJson(configPath, configBackup);
+    fx.writeJson(configPath, configBackup);
   } else {
     // Create basic config if none existed
     const dirName = targetPath.split(/[\\/]/).pop();
@@ -116,7 +179,32 @@ async function restoreUserConfig(morphPath, targetPath, configBackup, currentVer
         architecture: 'unknown'
       }
     };
-    await writeJson(configPath, defaultConfig);
+    fx.writeJson(configPath, defaultConfig);
+  }
+}
+
+/**
+ * `.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}
+ */
+export function stateJsonIsTracked(targetPath) {
+  try {
+    const isRepo = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: targetPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore']
+    });
+    if (isRepo.status !== 0) return false;
+
+    const tracked = spawnSync('git', ['ls-files', '--error-unmatch', '.morph/state.json'], {
+      cwd: targetPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return tracked.status === 0;
+  } catch {
+    return false;
   }
 }
 
@@ -133,56 +221,227 @@ async function restoreUserConfig(morphPath, targetPath, configBackup, currentVer
  * 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) {
+export function untrackCommittedStateJson(targetPath, fx = createEffects({ dryRun: false })) {
+  if (!stateJsonIsTracked(targetPath)) return false; // not tracked — nothing to migrate
+  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 }>}
+ */
+export async function readVersionRegisters(targetPath) {
+  let morphVersion = null;
+  let frameworkVersion = null;
   try {
-    const isRepo = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
-      cwd: targetPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore']
-    });
-    if (isRepo.status !== 0) return false;
+    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 */ }
+  try {
+    const c = await readJson(join(targetPath, '.morph', 'config', 'config.json'));
+    frameworkVersion = typeof c?.frameworkVersion === 'string' ? c.frameworkVersion : null;
+  } catch { /* idem */ }
 
-    // Is .morph/state.json currently tracked?
-    const tracked = spawnSync('git', ['ls-files', '--error-unmatch', '.morph/state.json'], {
-      cwd: targetPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore']
-    });
-    if (tracked.status !== 0) return false; // not tracked — nothing to migrate
+  const diverged = Boolean(morphVersion && frameworkVersion && morphVersion !== frameworkVersion);
+  return { morphVersion, frameworkVersion, diverged };
+}
 
-    const rm = spawnSync('git', ['rm', '--cached', '--quiet', '.morph/state.json'], {
-      cwd: targetPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore']
-    });
-    return rm.status === 0;
-  } catch {
-    return false;
+/**
+ * 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[]}
+ */
+export function majorGuardLines(verdict, registers, targetVersion) {
+  const lines = [];
+  if (verdict.reason === 'unknown-installed') {
+    lines.push(`Recusado: versão instalada indeterminável (\`.morph/.morphversion\` ausente ou ilegível).`);
+    lines.push(`  Tratado como salto grande, com motivo próprio: "não sei quão velho isto é" é `
+      + `precisamente quando sobrescrever às cegas é mais perigoso.`);
+  } else {
+    lines.push(`Recusado: salto de ${verdict.jump} majors (${registers.morphVersion} → ${targetVersion}); `
+      + `o limite sem \`--force\` é ${MAJOR_JUMP_LIMIT}.`);
   }
+  lines.push(`  Registro que decidiu: \`.morph/.morphversion → morphVersion\` = `
+    + `${registers.morphVersion ?? 'ausente'}.`);
+  if (registers.diverged) {
+    lines.push(`  Divergência: \`config.json → frameworkVersion\` diz ${registers.frameworkVersion}, `
+      + `e NÃO foi ele que decidiu — o \`update\` escreve esse campo e nunca o lê para decidir.`);
+  }
+  lines.push('  Para prosseguir mesmo assim: `morph-spec update --force`.');
+  lines.push('  Para ver o que aconteceria antes de decidir: `morph-spec update --dry-run`.');
+  return lines;
 }
 
-export async function updateCommand(options) {
-  const targetPath = process.cwd();
-  const contentDir = getContentDir();
-  const morphPath = join(targetPath, '.morph');
+/** Rótulo humano de cada verbo, para agrupar o relatório por natureza do efeito. */
+const VERB_GROUPS = {
+  remove: 'Apagar',
+  ensureDir: 'Criar diretório',
+  copyDir: 'Copiar diretório',
+  copyFile: 'Copiar arquivo',
+  writeFile: 'Escrever',
+  writeJson: 'Escrever (JSON)',
+  mergeJson: 'Mesclar (JSON)',
+  spawn: 'Executar',
+  gitIndex: 'Índice do git',
+};
+
+function isUnder(path, root) {
+  if (!path || !root) return false;
+  const rel = relative(root, path);
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
 
-  logger.header('MORPH-SPEC Update');
+/**
+ * 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.
+ */
+function effectLocation(effect) {
+  if (effect.verb !== 'spawn') return effect.target;
+  const args = Array.isArray(effect.args) ? effect.args : [];
+  const script = args.find((a) => /\.(js|mjs|cjs)$/.test(String(a)));
+  return script || effect.target;
+}
 
-  // Check if MORPH is initialized
-  let needsInitialization = false;
-  if (!(await pathExists(morphPath))) {
-    logger.warn('MORPH not fully initialized. Creating basic structure...');
-    needsInitialization = true;
+/**
+ * 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');
 
-    // Create basic .morph structure
-    await ensureDir(join(morphPath, 'context'));
-    await ensureDir(join(morphPath, 'features'));
-    await ensureDir(join(morphPath, 'framework'));
-    await ensureDir(join(morphPath, 'config'));
-    logger.dim('  ✓ Created .morph directory structure');
+  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.
+  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):'
+    : 'Efeitos desta execução:');
+  logger.blank();
+
+  for (const notice of notices) logger.warn(notice);
+  if (notices.length) logger.blank();
+
+  if (cleaned.length) {
+    logger.info('Apagados por inteiro antes da reinstalação:');
+    for (const { dir, files } of cleaned) {
+      logger.dim(`  − ${relative(targetPath, dir) || dir} (${files} arquivo(s))`);
+    }
+    logger.blank();
   }
 
-  // Check CLI version
+  const cleanedRoots = cleaned.map((c) => c.dir);
+  const insideCleaned = (e) => e.verb === 'remove'
+    && cleanedRoots.some((root) => e.target === root || isUnder(e.target, root));
+
+  const outside = [];
+  const inPackage = [];
+  const rest = [];
+  for (const e of effects) {
+    if (insideCleaned(e)) continue; // já contabilizado acima, e são centenas
+    const where = effectLocation(e);
+    if (isUnder(where, globalClaudeDir) || where === globalClaudeDir) outside.push(e);
+    else if (isUnder(where, packageRoot) && !isUnder(where, targetPath)) inPackage.push(e);
+    else rest.push(e);
+  }
+
+  const line = (e) => {
+    const label = VERB_GROUPS[e.verb] ?? e.verb;
+    const target = isUnder(e.target, targetPath) ? relative(targetPath, e.target) : e.target;
+    const suffix = e.detail ? ` ${e.detail}` : '';
+    return `  ${label}: ${target}${suffix}`;
+  };
+
+  if (rest.length) {
+    logger.info('No projeto:');
+    for (const e of rest) logger.dim(line(e));
+    logger.blank();
+  }
+
+  if (outside.length) {
+    logger.info('FORA do projeto (diretório pessoal do usuário):');
+    for (const e of outside) logger.dim(line(e));
+    logger.blank();
+  }
+
+  if (inPackage.length) {
+    logger.info('DENTRO do pacote da CLI (num `npm link` isto é o repositório do framework):');
+    for (const e of inPackage) logger.dim(line(e));
+    logger.blank();
+  }
+
+  logger.dim(`Total: ${effects.length} efeito(s) — ${cleaned.length} diretório(s) apagado(s) por inteiro, `
+    + `${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
+  // 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.');
+  logger.blank();
+}
+
+export async function updateCommand(options = {}) {
+  const targetPath = process.cwd();
+  const contentDir = getContentDir();
+  const morphPath = join(targetPath, '.morph');
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const fx = options.effects ?? createEffects({ dryRun });
+  const notices = [];
+
+  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").
   const spinner = ora('Checking versions...').start();
-  const cliCheck = await checkCLIOutdated();
+  // `cliCheck` é injetável para que o canário de igualdade dry × real não
+  // dependa do registro npm; a CLI nunca o passa.
+  const cliCheck = options.cliCheck ?? await checkCLIOutdated();
   const projectCheck = await checkProjectOutdated(targetPath);
-
+  const registers = await readVersionRegisters(targetPath);
   spinner.stop();
 
   // Display version info
@@ -202,33 +461,83 @@ export async function updateCommand(options) {
   }
   logger.blank();
 
-  // If CLI is outdated, stop and instruct user
+  // 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.
   if (cliCheck.isOutdated && cliCheck.latest) {
-    logger.warn(`Your CLI is outdated (${cliCheck.current} → ${cliCheck.latest})`);
-    logger.blank();
-    logger.info('Please update the CLI first:');
-    logger.blank();
+    if (dryRun) {
+      notices.push(`A CLI local está desatualizada (${cliCheck.current} → ${cliCheck.latest}). `
+        + 'O relatório abaixo é o do que a CLI ATUAL faria.');
+    } else {
+      logger.warn(`Your CLI is outdated (${cliCheck.current} → ${cliCheck.latest})`);
+      logger.blank();
+      logger.info('Please update the CLI first:');
+      logger.blank();
+
+      const method = detectInstallMethod();
+      const instructions = getUpdateInstructions(method);
+
+      instructions.forEach(line => {
+        if (line === '') {
+          logger.blank();
+        } else if (line.startsWith('Or ')) {
+          logger.dim(line);
+        } else {
+          logger.box([line]);
+        }
+      });
 
-    const method = detectInstallMethod();
-    const instructions = getUpdateInstructions(method);
+      logger.blank();
+      logger.dim('Then run "morph-spec update" again.');
+      process.exit(0);
+    }
+  }
 
-    instructions.forEach(line => {
-      if (line === '') {
-        logger.blank();
-      } else if (line.startsWith('Or ')) {
-        logger.dim(line);
-      } else {
-        logger.box([line]);
-      }
-    });
+  // ── Freio de major, ANTES de qualquer mutação ────────────────────────────
+  const needsInitialization = !(await pathExists(morphPath));
+  const targetVersion = cliCheck.current ?? getInstalledCLIVersion();
+  const verdict = needsInitialization
+    // Instalação nova: não há versão anterior a saltar. O freio existe para
+    // proteger uma instalação EXISTENTE de ser sobrescrita às cegas.
+    ? { refuse: false, reason: null, jump: null }
+    : majorJump(registers.morphVersion, targetVersion);
+
+  if (verdict.refuse) {
+    const lines = majorGuardLines(verdict, registers, targetVersion);
+    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.
+      notices.push(...lines);
+    } else {
+      logger.error(lines[0]);
+      for (const l of lines.slice(1)) logger.dim(l);
+      logger.blank();
+      process.exitCode = 1;
+      return { refused: true, reason: verdict.reason, effects: fx.list() };
+    }
+  } else if (registers.diverged) {
+    notices.push(`Os dois registros de versão do projeto discordam: `
+      + `\`.morph/.morphversion\` = ${registers.morphVersion}, `
+      + `\`config.json → frameworkVersion\` = ${registers.frameworkVersion}. `
+      + `Quem decide é o primeiro.`);
+  }
 
-    logger.blank();
-    logger.dim('Then run "morph-spec update" again.');
-    process.exit(0);
+  // ── A partir daqui, tudo passa pelo coletor ──────────────────────────────
+  if (needsInitialization) {
+    logger.warn('MORPH not fully initialized. Creating basic structure...');
+    fx.ensureDir(join(morphPath, 'context'));
+    fx.ensureDir(join(morphPath, 'features'));
+    fx.ensureDir(join(morphPath, 'framework'));
+    fx.ensureDir(join(morphPath, 'config'));
+    logger.dim('  ✓ Created .morph directory structure');
   }
 
   // Proceed with update
-  const updateSpinner = ora('Updating MORPH-SPEC...').start();
+  const updateSpinner = ora(dryRun ? 'Prevendo efeitos...' : 'Updating MORPH-SPEC...').start();
+  let cleaned = [];
 
   try {
     // Backup user config before cleaning
@@ -240,7 +549,7 @@ export async function updateCommand(options) {
 
     // Clean framework directories (preserve .morph/project/)
     updateSpinner.text = 'Cleaning old framework files...';
-    await cleanFrameworkDirs(morphPath, targetPath);
+    cleaned = cleanFrameworkDirs(morphPath, targetPath, fx);
     logger.dim('  ✓ Old framework files removed');
 
     const updateTemplates = !options.standards || options.templates;
@@ -253,7 +562,7 @@ export async function updateCommand(options) {
     if (updateTemplates) {
       updateSpinner.text = 'Checking for a legacy templates copy...';
       const templatesDest = join(morphPath, 'framework', 'templates');
-      templatesReconcile = reconcileLegacyTemplatesCopy(templatesDest, projectCheck.current);
+      templatesReconcile = reconcileLegacyTemplatesCopy(templatesDest, projectCheck.current, fx);
     }
 
     // Update standards
@@ -261,7 +570,7 @@ export async function updateCommand(options) {
       updateSpinner.text = 'Updating standards...';
       const standardsSrc = join(contentDir, 'framework', 'standards');
       const standardsDest = join(morphPath, 'framework', 'standards');
-      await copyDirectory(standardsSrc, standardsDest);
+      fx.copyDir(standardsSrc, standardsDest);
     }
 
     // Update hooks (runtime hook scripts under .morph/framework/hooks/)
@@ -269,7 +578,7 @@ export async function updateCommand(options) {
     const hooksSrc = join(__dirname, '..', '..', '..', 'framework', 'hooks');
     const hooksDest = join(morphPath, 'framework', 'hooks');
     if (await pathExists(hooksSrc)) {
-      await copyDirectory(hooksSrc, hooksDest);
+      fx.copyDir(hooksSrc, hooksDest);
     }
 
     // Update agents.json (sourced from framework/ — canonical single source of truth)
@@ -277,7 +586,7 @@ export async function updateCommand(options) {
     const agentsSrc = join(__dirname, '..', '..', '..', 'framework', 'agents.json');
     const agentsDest = join(morphPath, 'framework', 'agents.json');
     if (await pathExists(agentsSrc)) {
-      await copyFile(agentsSrc, agentsDest);
+      fx.copyFile(agentsSrc, agentsDest);
     }
 
     // Update the remaining framework payloads (parity with setup-infra 7b/7c/8b/8c/8d) —
@@ -288,13 +597,13 @@ export async function updateCommand(options) {
     for (const file of ['MORPH.md', 'phases.json']) {
       const src = join(canonicalFrameworkDir, file);
       if (await pathExists(src)) {
-        await copyFile(src, join(morphPath, 'framework', file));
+        fx.copyFile(src, join(morphPath, 'framework', file));
       }
     }
     for (const dir of ['schemas', 'rubrics', 'evals']) {
       const src = join(canonicalFrameworkDir, dir);
       if (await pathExists(src)) {
-        await copyDirectory(src, join(morphPath, 'framework', dir));
+        fx.copyDir(src, join(morphPath, 'framework', dir));
       }
     }
     // CLI.md vive em framework/docs/ na fonte mas instala achatado em
@@ -302,17 +611,21 @@ export async function updateCommand(options) {
     // por isso não entra no loop de nomes acima.
     const cliMdSrc = join(canonicalFrameworkDir, 'docs', 'CLI.md');
     if (await pathExists(cliMdSrc)) {
-      await copyFile(cliMdSrc, join(morphPath, 'framework', 'CLI.md'));
+      fx.copyFile(cliMdSrc, join(morphPath, 'framework', 'CLI.md'));
     }
 
-    // Regenerate derived files (phase-utils.js, skill output tables) from output-schema.js
-    // Only runs when the generator script is present (framework dev installs via npm link)
+    // 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.
     updateSpinner.text = 'Syncing generated refs...';
     try {
       const generateScript = join(__dirname, '..', '..', '..', 'scripts', 'generate-refs.js');
       if (existsSync(generateScript)) {
-        const result = spawnSync(process.execPath, [generateScript], { encoding: 'utf8' });
-        if (result.status === 0) {
+        const result = fx.spawn(process.execPath, [generateScript], {
+          dryRunArgs: [generateScript, '--check'],
+        });
+        if (result && result.status === 0 && !dryRun) {
           logger.dim('  ✓ Generated refs synced (phase-utils.js, skill outputs)');
         }
       }
@@ -332,7 +645,7 @@ export async function updateCommand(options) {
     const commandsSrc = join(frameworkDir, 'commands');
     const commandsDest = join(claudeDest, 'commands');
     if (await pathExists(commandsSrc)) {
-      await copyDirectory(commandsSrc, commandsDest);
+      fx.copyDir(commandsSrc, commandsDest);
       commandsCopied = true;
     } else {
       logger.warn('  ⚠ framework/commands/ source missing — commands not updated');
@@ -350,12 +663,12 @@ export async function updateCommand(options) {
 
     // 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 });
+    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 });
-    await installDomainAgents(targetPath, frameworkDir, { projectTags });
+    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
@@ -365,8 +678,8 @@ export async function updateCommand(options) {
     const rulesDest = join(claudeDest, 'rules');
     let rulesResult = null;
     if (await pathExists(rulesSrc)) {
-      await ensureDir(rulesDest);
-      rulesResult = installRulesForStack(rulesSrc, rulesDest, projectTags);
+      fx.ensureDir(rulesDest);
+      rulesResult = installRulesForStack(rulesSrc, rulesDest, projectTags, fx);
     }
 
     // Sync runtime CLAUDE.md to .claude/CLAUDE.md and derive the personas
@@ -375,15 +688,19 @@ export async function updateCommand(options) {
     const runtimeSrc = join(frameworkDir, 'CLAUDE.md');
     const runtimeDest = join(claudeDest, 'CLAUDE.md');
     if (await pathExists(runtimeSrc)) {
-      await copyFile(runtimeSrc, runtimeDest);
-      await updateClaudeMdAgentsBlock(runtimeDest, agentsResult?.agents ?? []);
+      fx.copyFile(runtimeSrc, runtimeDest);
+      // Em dry o destino ainda não recebeu a cópia acima; ler a ORIGEM é o que
+      // faz previsão e execução decidirem igual sobre os marcadores.
+      await updateClaudeMdAgentsBlock(runtimeDest, agentsResult?.agents ?? [], {
+        fx, readFrom: dryRun ? runtimeSrc : runtimeDest,
+      });
     }
 
     // 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);
+      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)');
@@ -391,88 +708,87 @@ export async function updateCommand(options) {
 
     // Update Claude Code hooks in .claude/settings.local.json
     updateSpinner.text = 'Updating Claude Code hooks...';
-    const hooksResult = await installClaudeHooks(targetPath);
+    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);
+    await injectMorphImport(claudeMdDest, fx);
 
     // Restore user config after framework reinstallation
     updateSpinner.text = 'Restoring user configuration...';
-    await restoreUserConfig(morphPath, targetPath, configBackup, cliCheck.current);
+    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);
-    await ensureGitattributes(targetPath);
+    await updateGitignore(targetPath, fx);
+    await ensureGitattributes(targetPath, fx);
 
     // 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);
+    const untracked = untrackCommittedStateJson(targetPath, fx);
 
     // Update .morphversion
     updateSpinner.text = 'Saving version info...';
-    await saveProjectMorphVersion(targetPath, cliCheck.current);
+    await saveProjectMorphVersion(targetPath, cliCheck.current, fx);
 
-    updateSpinner.succeed('MORPH-SPEC updated successfully!');
+    updateSpinner.succeed(dryRun ? 'Previsão concluída (nada foi tocado).' : 'MORPH-SPEC updated successfully!');
     logger.blank();
 
-    // Show version change
-    if (projectCheck.current && projectCheck.current !== cliCheck.current) {
-      logger.success(`Updated: ${projectCheck.current} → ${cliCheck.current}`);
-    } else if (!projectCheck.current) {
-      logger.success(`Updated to v${cliCheck.current}`);
-    } else {
-      logger.success(`Already up to date (v${cliCheck.current})`);
-    }
-
-    logger.blank();
-    logger.info('Updated files:');
-    if (updateTemplates) {
-      if (templatesReconcile === 'removed-legacy') {
-        logger.dim('  ✓ .morph/framework/templates/ (legacy installer copy removed — resolved from package)');
-      } else if (templatesReconcile === 'preserved-override') {
-        logger.dim('  ⚠ .morph/framework/templates/ (local override present — preserved untouched, not updated)');
+    if (!dryRun) {
+      // Show version change
+      if (projectCheck.current && projectCheck.current !== cliCheck.current) {
+        logger.success(`Updated: ${projectCheck.current} → ${cliCheck.current}`);
+      } else if (!projectCheck.current) {
+        logger.success(`Updated to v${cliCheck.current}`);
       } else {
-        logger.dim('  · .morph/framework/templates/ (not present — resolved from package, no local override)');
+        logger.success(`Already up to date (v${cliCheck.current})`);
       }
+
+      logger.blank();
+      logger.info('Updated files:');
+      if (updateTemplates) {
+        if (templatesReconcile === 'removed-legacy') {
+          logger.dim('  ✓ .morph/framework/templates/ (legacy installer copy removed — resolved from package)');
+        } else if (templatesReconcile === 'preserved-override') {
+          logger.dim('  ⚠ .morph/framework/templates/ (local override present — preserved untouched, not updated)');
+        } else {
+          logger.dim('  · .morph/framework/templates/ (not present — resolved from package, no local override)');
+        }
+      }
+
+      // 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.
+      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)`);
+      logger.dim(`  ✓ .claude/skills/ (${skillsResult?.installed ?? '?'} skills — stack: ${tagsLabel})`);
+      logger.dim(`  ✓ .claude/agents/ (${agentsResult?.agents?.length ?? '?'} personas — stack: ${tagsLabel})`);
+      logger.dim(`  ✓ .claude/rules/ (${rulesResult?.installed ?? '?'} stack-filtered rules)`);
+      if (commandsCopied) logger.dim('  ✓ .claude/commands/');
+      if (untracked) {
+        logger.dim('  ✓ .morph/state.json untracked (git rm --cached) — commit to finalize');
+        logger.warn('Migration: .morph/state.json was removed from git tracking. The');
+        logger.dim('  working file stays (rebuilt from feature.json); commit the deletion');
+        logger.dim('  so it stops being swept into per-feature commits.');
+      }
+      logger.blank();
+      logger.info('Your config.json was preserved.');
     }
-    if (updateStandards) logger.dim('  ✓ .morph/framework/standards/');
-    logger.dim('  ✓ .morph/framework/hooks/');
-    logger.dim('  ✓ .morph/framework/agents.json');
-    logger.dim('  ✓ .morph/framework/MORPH.md + phases.json (NLH charter)');
-    logger.dim('  ✓ .morph/framework/schemas/ + rubrics/ + evals/ (bar 9 + LLM rubrics)');
-    if (commandsCopied) logger.dim('  ✓ .claude/commands/');
-
-    // 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.
-    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)`);
-    logger.dim(`  ✓ .claude/skills/ (${skillsResult?.installed ?? '?'} skills — stack: ${tagsLabel})`);
-    logger.dim(`  ✓ .claude/agents/ (${agentsResult?.agents?.length ?? '?'} personas — stack: ${tagsLabel})`);
-    logger.dim(`  ✓ .claude/rules/ (${rulesResult?.installed ?? '?'} stack-filtered rules)`);
-    logger.dim('  ✓ .claude/CLAUDE.md (runtime quick reference)');
-    logger.dim('  ✓ ~/.claude/statusline.sh (global statusline synced)');
-    logger.dim('  ✓ CLAUDE.md');
-    logger.dim('  ✓ .gitignore (morph rules updated)');
-    if (untracked) {
-      logger.dim('  ✓ .morph/state.json untracked (git rm --cached) — commit to finalize');
-      logger.warn('Migration: .morph/state.json was removed from git tracking. The');
-      logger.dim('  working file stays (rebuilt from feature.json); commit the deletion');
-      logger.dim('  so it stops being swept into per-feature commits.');
-    }
-    logger.blank();
-    logger.info('Your config.json was preserved.');
-    logger.dim('Review the updated files for any new features.');
-    logger.blank();
 
+    // 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`.
+    renderEffectsReport(fx.list(), {
+      targetPath, packageRoot: contentDir, dryRun, cleaned, notices,
+    });
+
+    return { refused: false, dryRun, effects: fx.list() };
   } catch (error) {
-    updateSpinner.fail('Update failed');
+    updateSpinner.fail(dryRun ? 'Previsão falhou' : 'Update failed');
     logger.error(error.message);
     process.exit(1);
   }