@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

package/src/commands/observability/cost.js

@@ -1,5 +1,5 @@
 /**
- * `morph-spec cost [feature] [--by task|phase] [--all-trees] [--json]`
+ * `morph-spec cost [feature] [--by task|phase] [--all-trees] [--metrics [--top n]] [--json]`
  *
  * A cost-facing view over the same harness event stream `telemetry` reads
  * (.morph/logs/events.jsonl): how much wall-clock time was spent inside
@@ -16,11 +16,14 @@
  * `sessionUsage` (when present) is the exception: real tokens, observed
  * directly, not a proxy — see aggregateCost's docstring for the contract.
  *
- * `--all-trees` (Furo 3) widens the source from "just the current tree" to
- * every git worktree that has its own events.jsonl — a fleet running N
- * features in N worktrees otherwise only ever sees whichever tree `cost` was
- * run from. Reuses the same worktree enumeration `doctor --worktrees`/`fleet`
- * use (see loadTelemetryAllTrees in telemetry-reader.js).
+ * `--all-trees` widens the source from "just the current tree" to every git
+ * worktree that has its own events.jsonl plus the logs `finish` saved before
+ * removing a worktree, deduplicated by eventId.
+ *
+ * `--metrics` measures the loop instead: turns, tool calls by orchestrator and
+ * sub-agent, time per command class, identical reruns and why, rereads, how
+ * many feature-scope verifies each feature ran, git calls per task and whether
+ * the reuse validator ran in root and worktree (see lib/telemetry/metrics.js).
  *
  * Read-only, always exits 0 on a normal (even empty) run — fail-open, an
  * empty stream is an answer, not an error. Only `--by` with an unknown value
@@ -28,7 +31,8 @@
  */
 
 import chalk from 'chalk';
-import { loadTelemetry, loadTelemetryAllTrees, aggregateCost } from '../../lib/telemetry/telemetry-reader.js';
+import { loadTelemetry, loadTelemetryAllTrees, aggregateCost, dedupeEvents } from '../../lib/telemetry/telemetry-reader.js';
+import { computeMetrics } from '../../lib/telemetry/metrics.js';
 
 const BYTES_CAVEAT =
   'Bytes re-ingeridos são um PROXY determinístico de custo (o que as ferramentas leram do disco) — NÃO são tokens reais. Hooks não enxergam o uso real de tokens do modelo.';
@@ -87,17 +91,30 @@ function printPhases(phases) {
   }
 }
 
+function tokenLine(u) {
+  return `  input=${u.inputTokens}  output=${u.outputTokens}  `
+    + `cacheRead=${u.cacheReadTokens}  cacheCreation=${u.cacheCreationTokens}`;
+}
+
 /**
- * Real (hook-observed) token counts, when the stream has `SessionUsage`
- * events — the non-proxy sibling of the bytes-re-ingested numbers above.
- * No-op when absent (aggregateCost returns `null`, never a zeroed object).
+ * Real (hook-observed) token counts — the non-proxy sibling of the bytes
+ * above: the main sessions and, separately, the sub-agents.
  */
-function printSessionUsage(sessionUsage) {
-  if (!sessionUsage) return;
-  console.log('\n' + chalk.white.bold('Tokens reais (sessões observadas)')
-    + chalk.gray(` · ${sessionUsage.sessions} SessionUsage`));
-  console.log(`  input=${sessionUsage.inputTokens}  output=${sessionUsage.outputTokens}  `
-    + `cacheRead=${sessionUsage.cacheReadTokens}  cacheCreation=${sessionUsage.cacheCreationTokens}`);
+function printSessionUsage(summary) {
+  const { sessionUsage, agentUsage, sessionUsageLegacySamples } = summary;
+  if (sessionUsage) {
+    console.log('\n' + chalk.white.bold('Tokens reais (sessões observadas)')
+      + chalk.gray(` · ${sessionUsage.sessions} sessão(ões), ${sessionUsage.samples} amostra(s)`));
+    console.log(tokenLine(sessionUsage));
+  }
+  if (agentUsage) {
+    console.log('\n' + chalk.white.bold('Tokens reais (sub-agents)')
+      + chalk.gray(` · ${agentUsage.agents} agente(s), ${agentUsage.samples} amostra(s)`));
+    console.log(tokenLine(agentUsage));
+  }
+  if (sessionUsageLegacySamples > 0) {
+    console.log(chalk.gray(`  ${sessionUsageLegacySamples} amostra(s) SessionUsage antigas (sem delta) fora da soma: eram o total acumulado, repetido a cada Stop.`));
+  }
 }
 
 function printSummary(summary) {
@@ -112,7 +129,115 @@ function printSummary(summary) {
     for (const t of summary.tools) console.log(`  ${t.name.padEnd(16)} ${t.count}`);
   }
 
-  printSessionUsage(summary.sessionUsage);
+  printSessionUsage(summary);
+}
+
+function pct(r) {
+  return r === null || r === undefined ? '-' : `${Math.round(r * 1000) / 10}%`;
+}
+
+function split(counts) {
+  return `${counts.total} (orq ${counts.orchestrator} · sub ${counts.subagent}${counts.unknown ? ` · sem agente ${counts.unknown}` : ''})`;
+}
+
+function printMetricsBody(m, { by }) {
+  const legacyShare = m.window.events ? m.coverage.legacy / m.window.events : 0;
+  console.log(chalk.gray(`janela: ${m.window.from ?? '-'} → ${m.window.to ?? '-'} · ${m.window.events} eventos`
+    + ` · ${pct(1 - legacyShare)} no esquema v2`));
+  if (m.coverage.legacy) {
+    console.log(chalk.gray('  eventos v1 não têm agente, exit code, duração nem janela de Read: entram como "sem agente" e rerun "unknown-*".'));
+  }
+
+  console.log('\n' + chalk.white.bold('Turnos e chamadas'));
+  console.log(`  turnos: ${m.turns ? split(m.turns) : 'desconhecido (nenhum PostToolBatch na janela)'}`
+    + (m.turnsPerTaskMedian !== null ? chalk.gray(` · mediana por task ${m.turnsPerTaskMedian}`) : ''));
+  console.log(`  chamadas de ferramenta: ${split(m.toolCalls)}`);
+  const perTask = m.perTaskByFeature;
+  if (perTask.toolCalls !== null) {
+    console.log(`  por task (total da feature ÷ tasks dela, mediana): ${perTask.toolCalls} chamadas`
+      + (perTask.turns !== null ? ` · ${perTask.turns} turnos` : '') + ` · ${perTask.git} git status+diff`
+      + chalk.gray(` · as janelas TaskStart→TaskEnd têm ${pct(m.taskWindowCoverage)} das chamadas`));
+  }
+
+  console.log('\n' + chalk.white.bold('Tempo por classe de comando'));
+  for (const [klass, t] of Object.entries(m.timeByClass).sort((a, b) => b[1].measuredMs - a[1].measuredMs)) {
+    const unmeasured = t.unmeasured ? chalk.gray(` (${t.unmeasured} sem duração)`) : '';
+    console.log(`  ${klass.padEnd(12)} ${fmtDuration(t.measuredMs / 1000).padStart(8)}  ${t.runs} execução(ões)${unmeasured}`);
+  }
+
+  console.log('\n' + chalk.white.bold('Rerun do mesmo comando em ≤10 min (mesma feature; o filtro de saída não conta)'));
+  console.log(`  total: ${pct(m.reruns.rate)} repetidas (${m.reruns.reruns}/${m.reruns.runs}) · ${pct(m.reruns.burstRate)} em rajada — testes, builds e verifies`);
+  for (const [kind, r] of Object.entries(m.rerunsByKind).sort((a, b) => b[1].runs - a[1].runs)) {
+    console.log(`  ${kind.padEnd(22)} ${pct(r.rate).padStart(6)} repetidas  ${pct(r.burstRate).padStart(6)} em rajada  (${r.runs} execuções)`);
+  }
+  const classes = Object.entries(m.rerunClasses);
+  if (classes.length) console.log(chalk.gray(`  por quê: ${classes.map(([k, n]) => `${k} ${n}`).join(' · ')}`));
+
+  console.log('\n' + chalk.white.bold('Releitura de arquivo (mesma janela, mesma feature)'));
+  console.log(`  ${pct(m.rereads.rate)} dos bytes lidos (${fmtBytes(m.rereads.redundantBytes)} de ${fmtBytes(m.rereads.bytes)}, ${m.rereads.reads} leituras)`);
+  if (m.rereads.windowed < m.rereads.reads) {
+    console.log(chalk.gray(`  ${m.rereads.reads - m.rereads.windowed} leitura(s) sem janela gravada (v1) contam o arquivo inteiro: a taxa é um teto`));
+  }
+  for (const f of m.topRereads) {
+    console.log(`  ${fmtBytes(f.redundantBytes).padStart(9)}  ${f.reads}×  ${f.file}${chalk.gray(` [${f.feature ?? '-'}]`)}`);
+  }
+
+  console.log('\n' + chalk.white.bold('verify, git e reuso'));
+  const perFeature = Object.entries(m.verify.byFeature).sort((a, b) => b[1].feature - a[1].feature);
+  console.log(`  verify de feature por feature: mediana ${m.verify.featureScopeMedian ?? '-'}`
+    + (perFeature.length ? chalk.gray(` (${perFeature.slice(0, 5).map(([f, v]) => `${f} ${v.feature}`).join(', ')})`) : ''));
+  const repeats = Object.entries(m.verify.unchangedRepeats);
+  if (repeats.length) {
+    console.log(`  verify de feature sobre a mesma árvore do anterior: ${repeats.reduce((n, [, v]) => n + v, 0)}`
+      + chalk.gray(` (${repeats.map(([f, n]) => `${f} ${n}`).join(', ')})`));
+  }
+  if (m.dotnetFullSuite.runs) {
+    const phases = Object.entries(m.dotnetFullSuite.byPhase).map(([p, v]) => `${p} ${v.withBuild}/${v.runs}`).join(' · ');
+    console.log(`  suíte .NET inteira que recompila (sem --no-build): ${m.dotnetFullSuite.withBuild}/${m.dotnetFullSuite.runs}`
+      + chalk.gray(` (${phases})`));
+  }
+  console.log(`  git status / diff por task: mediana ${m.gitPerTaskMedian.status ?? '-'} / ${m.gitPerTaskMedian.diff ?? '-'}`
+    + chalk.gray(` · total ${m.git.status} / ${m.git.diff}`));
+  const trees = Object.entries(m.reuse.byTree);
+  console.log(`  reuse-validator: ${trees.length
+    ? trees.map(([tree, s]) => `${tree} rodou ${s.ran}, pulou ${s.skipped}`).join(' · ')
+    : 'nenhum evento Verify na janela'}`);
+  for (const [reason, n] of Object.entries(m.reuse.skipReasons)) console.log(chalk.gray(`    pulou ${n}×: ${reason}`));
+
+  if (by === 'task') {
+    for (const t of m.tasks) {
+      const status = t.open ? chalk.yellow('[em aberto]') : (t.status || '-');
+      console.log('\n' + chalk.white.bold(`Task ${t.task}`) + chalk.gray(` · ${t.feature ?? '(sem feature)'}`) + ` · ${status}`);
+      console.log(`  turnos ${t.turns ? split(t.turns) : '-'} · chamadas ${split(t.toolCalls)}`);
+      const time = Object.entries(t.timeByClass).map(([k, v]) => `${k} ${fmtDuration(v.measuredMs / 1000)}`).join(' · ');
+      if (time) console.log(`  tempo: ${time}`);
+      console.log(`  rerun ${pct(t.reruns.rate)} (${t.reruns.reruns}/${t.reruns.runs}) · releitura ${pct(t.rereads.rate)} · git status/diff ${t.git.status}/${t.git.diff}`);
+    }
+  }
+}
+
+/**
+ * `--metrics`: the loop measurements over the current tree (and, with
+ * `--all-trees`, every tree plus the finish backups, deduplicated).
+ */
+function printMetrics(feature, options, cwd) {
+  const events = options.allTrees
+    ? dedupeEvents(loadTelemetryAllTrees(cwd).flatMap((t) => t.events))
+    : loadTelemetry(cwd);
+  const metrics = computeMetrics(events, { feature, top: options.top });
+
+  if (options.json) {
+    console.log(JSON.stringify(metrics));
+    return;
+  }
+  if (metrics.window.events === 0) {
+    const scope = feature ? ` para a feature "${feature}"` : '';
+    console.log(chalk.gray(`Telemetria vazia${scope} — nada a medir.`));
+    return;
+  }
+  const scope = feature ? chalk.cyan(` · feature ${feature}`) : '';
+  console.log(chalk.white.bold(`Medições do loop${options.allTrees ? ' — todas as árvores + finish-backup' : ''}`) + scope);
+  printMetricsBody(metrics, options);
 }
 
 /**
@@ -132,7 +257,7 @@ function printAllTrees(feature, options, cwd) {
     path,
     ...aggregateCost(events, { feature }),
   }));
-  const combined = aggregateCost(treesData.flatMap((t) => t.events), { feature });
+  const combined = aggregateCost(dedupeEvents(treesData.flatMap((t) => t.events)), { feature });
 
   if (options.json) {
     console.log(JSON.stringify({ allTrees: true, trees: perTree, combined }));
@@ -183,6 +308,11 @@ export function costCommand(feature, options = {}) {
 
   const cwd = options.cwd || process.cwd();
 
+  if (options.metrics) {
+    printMetrics(feature, options, cwd);
+    return;
+  }
+
   if (options.allTrees) {
     // Same fail-open + Windows-flush discipline as the single-tree path
     // below — no forced process.exit(), --json included.

package/src/commands/project/doctor.js

@@ -16,7 +16,7 @@ import {
   getInstalledCLIVersion
 } from '../../utils/version-checker.js';
 import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
-import { checkMissingAgents, checkAgentsDrift } from '../../utils/agents-installer.js';
+import { checkMissingAgents, checkAgentsDrift, maxTurnsError, surfacesError } from '../../utils/agents-installer.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { auditGraph } from '../../lib/graph/graph-health.js';
 import { auditFeatureLifecycle } from '../../core/state/lifecycle-audit.js';
@@ -191,6 +191,23 @@ 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.
+  const maxTurnsErrors = agentEntries
+    .map(([id, data]) => maxTurnsError(id, data?.maxTurns))
+    .filter(Boolean);
+  checks.push(maxTurnsErrors.length > 0
+    ? { 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);
+  checks.push(surfacesErrors.length > 0
+    ? { name: 'agents.json surfaces', status: 'error', msg: surfacesErrors.join(' | ') }
+    : { name: 'agents.json surfaces', status: 'ok' });
+
   if (missingV5Fields.length > 0 && isV5) {
     const sample = missingV5Fields.slice(0, 3).join(', ');
     checks.push({
@@ -348,12 +365,23 @@ async function doctorFullCommand(frameworkRoot) {
           projectTags = getProjectTags(JSON.parse(rawCfg));
         } catch { /* no tags */ }
       }
-      const drift = checkAgentsDrift(frameworkRoot, join(frameworkRoot, '.morph/framework'), projectTags);
+      // The MCP registry comes from the package, like the installer's: the
+      // installed .morph/framework/ has no mcp/, and rendering without it
+      // flagged every persona with an `mcp` grant as stale on a clean install.
+      const drift = checkAgentsDrift(frameworkRoot, join(frameworkRoot, '.morph/framework'), projectTags,
+        { mcpRegistryDir: join(import.meta.dirname, '..', '..', '..', 'framework') });
+      if (drift.invalid.length > 0) {
+        check('Personas agents.json valid', false, false,
+          `${drift.invalid.map(i => i.reason).join(' | ')} — corrija o agents.json e rode 'morph-spec update'`);
+      }
       check(`Personas installed (${drift.expected - drift.missing.length}/${drift.expected})`,
         drift.missing.length === 0, false,
         drift.missing.length > 0 ? `missing: ${drift.missing.join(', ')} — run 'morph-spec setup-infra --reinstall'` : '');
+      // Name WHAT differs per file (frontmatter key or body): a hand-edited
+      // maxTurns and a CLI upgrade that changed the body read differently.
+      const staleList = drift.stale.map(f => `${f} (${(drift.staleFields[f] ?? []).join(', ')})`);
       check('Personas up-to-date (no drift)', drift.stale.length === 0, true,
-        drift.stale.length > 0 ? `stale/hand-edited: ${drift.stale.join(', ')} — regenerate via 'morph-spec setup-infra --reinstall'` : '');
+        drift.stale.length > 0 ? `stale/hand-edited: ${staleList.join(', ')} — regenerate via 'morph-spec setup-infra --reinstall'` : '');
       check('No orphan morph-* agents', drift.orphans.length === 0, true,
         drift.orphans.length > 0 ? `orphans: ${drift.orphans.join(', ')}` : '');
     } catch {
@@ -653,23 +681,54 @@ async function doctorMcpCommand(targetPath) {
  * 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.
  */
 export async function doctorWorktreesCommand(targetPath, options = {}) {
   const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
 
+  let backupRetention = null;
+  let prune = null;
   if (options.prune) {
     const beforeIssues = auditWorktrees(targetPath);
     const beforeMissing = beforeIssues.filter((i) => i.type === 'registered-missing').length;
     const beforeDangling = beforeIssues.filter((i) => i.type === 'dangling-registration').length;
     const beforeEmptyDirs = beforeIssues.filter((i) => i.type === 'unregistered-dir' && i.empty).length;
     const result = await pruneWorktrees(targetPath);
-    if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
-    else logger.warn(`prune falhou: ${result.error}`);
-    if (result.removedEmptyDirs.length) {
-      logger.success(`${result.removedEmptyDirs.length}/${beforeEmptyDirs} diretório(s) vazio(s) removido(s): ${result.removedEmptyDirs.join(', ')}`);
+    // Under --json the only thing on stdout is the JSON: a status line in front
+    // of it breaks every caller that parses the output.
+    prune = {
+      pruned: Boolean(result.pruned),
+      ...(result.pruned ? { orphanRegistrations: beforeMissing } : { error: result.error }),
+      removedEmptyDirs: result.removedEmptyDirs,
+      clearedRegistrations: result.clearedRegistrations.map((r) => r.feature),
+    };
+    if (!options.json) {
+      if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
+      else logger.warn(`prune falhou: ${result.error}`);
+      if (result.removedEmptyDirs.length) {
+        logger.success(`${result.removedEmptyDirs.length}/${beforeEmptyDirs} diretório(s) vazio(s) removido(s): ${result.removedEmptyDirs.join(', ')}`);
+      }
+      if (result.clearedRegistrations.length) {
+        logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
+      }
     }
-    if (result.clearedRegistrations.length) {
-      logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
+
+    const { resolvePrimaryRoot } = await import('./worktree.js');
+    const { applyBackupRetention, summarizeRetention } = await import('../../lib/worktree/finish-backup.js');
+    // The explicit prune is the one that reaches the backups written before the
+    // retention existed (no manifest): the automatic one never touches them.
+    backupRetention = summarizeRetention(applyBackupRetention(resolvePrimaryRoot(targetPath), { includeLegacy: true }));
+    if (backupRetention?.skipped && !options.json) {
+      logger.warn(`retenção dos backups do finish PULADA: ${backupRetention.skipped}`);
+    } else if (backupRetention && !options.json) {
+      const stripped = backupRetention.secretsStripped ? `, ${backupRetention.secretsStripped} arquivo(s) .env* apagado(s)` : '';
+      const adopted = backupRetention.adopted ? `, ${backupRetention.adopted} backup(s) antigo(s) mantido(s) ganharam manifesto` : '';
+      logger.success(`retenção dos backups do finish: ${backupRetention.removed ?? 0} pasta(s) removida(s)${stripped}${adopted}`);
+      for (const d of backupRetention.declined || []) logger.warn(`backup mantido: ${d.backup} (${d.reason})`);
     }
   }
 
@@ -684,7 +743,7 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
   const isProblem = (i) => !['info', 'warn'].includes(i.severity);
 
   if (options.json) {
-    console.log(JSON.stringify({ issues }, null, 2));
+    console.log(JSON.stringify({ issues, ...(prune ? { prune } : {}), ...(backupRetention ? { backupRetention } : {}) }, null, 2));
     return !issues.some(isProblem);
   }
 
@@ -1390,6 +1449,19 @@ export async function doctorCommand(options = {}) {
     checks.push({ name: 'codebase graph', status: 'ok', msg: graphAudit.msg });
   }
 
+  // O que o morph-spec guarda dentro do `.git` (backups do finish, registros de
+  // porta e de claim) cresce sem aparecer em `git status`. Informação — `ok` ou
+  // `warn`, nunca falha —, e nenhuma linha quando não há nada guardado.
+  try {
+    const { resolvePrimaryRoot } = await import('./worktree.js');
+    const { morphStoreCheck } = await import('../../lib/worktree/finish-backup.js');
+    const storeCheck = morphStoreCheck(resolvePrimaryRoot(targetPath));
+    if (storeCheck) {
+      checks.push(storeCheck);
+      if (storeCheck.status === 'warn') hasWarnings = true;
+    }
+  } catch { /* fail-open */ }
+
   // Check key templates exist (in framework package, not project copy)
   const frameworkTemplatesRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
   const keyTemplates = [

package/src/commands/project/update.js

@@ -33,6 +33,9 @@ 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';
+import {
+  writeGraphifyignore, describeOutdatedIgnore, graphifyignoreTracked,
+} from '../../lib/graph/graphifyignore.js';
 
 /**
  * Backup user's config.json before cleaning
@@ -725,6 +728,24 @@ export async function updateCommand(options = {}) {
     await updateGitignore(targetPath, fx);
     await ensureGitattributes(targetPath, fx);
 
+    // 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.
+    let graphIgnore = null;
+    if (existsSync(join(targetPath, '.graphifyignore'))) {
+      updateSpinner.text = 'Checking .graphifyignore...';
+      graphIgnore = writeGraphifyignore(targetPath, projectTags, { fx });
+      if (graphIgnore.outdated) notices.push(describeOutdatedIgnore(graphIgnore.outdated));
+      if (graphIgnore.migrated && graphifyignoreTracked(targetPath)) {
+        notices.push('.graphifyignore é versionado: commite a migração (git add .graphifyignore) — '
+          + 'as worktrees e o resto do time leem o arquivo do próprio checkout e só recebem as regras novas depois do commit');
+      }
+    }
+
     // 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);
@@ -769,6 +790,10 @@ export async function updateCommand(options = {}) {
       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 (graphIgnore?.migrated) {
+        logger.dim('  ✓ .graphifyignore (dublês, fixtures e helpers de teste voltam ao grafo da raiz no próximo refresh');
+        logger.dim('    em background — início de sessão ou comando git do agente; numa worktree: morph-spec graph refresh)');
+      }
       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');