@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/src/lib/git/tree-state.js

@@ -0,0 +1,167 @@
+/**
+ * The working tree as the orchestrator needs it when it takes control back
+ * from a dispatch, in one call instead of `git status` + `git diff --stat` +
+ * `git log` + a marker grep. Everything is read outside `.morph/`, the same
+ * cut the tree fingerprint makes.
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { OUTSIDE_MORPH, treeFingerprint, git as gitBuffer } from './tree-fingerprint.js';
+import { detectDefaultBranch } from './default-branch.js';
+import { resolveBaseRef } from './branch-classifier.js';
+
+/** What an evaluator writes next to a mutation it has not reverted yet. */
+export const MUTATION_MARKER = 'MUTACAO';
+const MAX_LISTED = 50;
+const MAX_COMMITS = 10;
+
+function git(cwd, args, input) {
+  return gitBuffer(cwd, args, input).toString();
+}
+
+function headSha(cwd) {
+  try { return git(cwd, ['rev-parse', 'HEAD']).trim(); } catch { return null; }
+}
+
+/** Every file that differs from HEAD outside `.morph/`, untracked ones one by one. */
+function changedFiles(cwd) {
+  return parsePorcelain(git(cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=all', ...OUTSIDE_MORPH]))
+    .map((e) => e.path);
+}
+
+/** Blob id of each file as it is on disk; null for a file that is gone. */
+function diskBlobs(cwd, paths) {
+  const present = paths.filter((p) => existsSync(join(cwd, p)));
+  const ids = present.length ? git(cwd, ['hash-object', '--stdin-paths'], present.join('\n')).split('\n') : [];
+  const out = Object.fromEntries(paths.map((p) => [p, null]));
+  present.forEach((p, i) => { out[p] = ids[i].trim(); });
+  return out;
+}
+
+/** Blob id of each path in a commit; null where the commit does not have it. */
+function commitBlobs(cwd, commit, paths) {
+  const out = Object.fromEntries(paths.map((p) => [p, null]));
+  if (!commit || !paths.length) return out;
+  const lines = git(cwd, ['cat-file', '--batch-check=%(objectname)'], paths.map((p) => `${commit}:${p}`).join('\n')).split('\n');
+  paths.forEach((p, i) => { out[p] = /^[0-9a-f]{40,64}$/.test(lines[i]?.trim()) ? lines[i].trim() : null; });
+  return out;
+}
+
+/**
+ * What the tree is before a dispatch whose work must leave it unchanged (the
+ * evaluator mutates and reverts): HEAD plus the blob of every file that
+ * differs from it. Kept on disk, so a session that resumes after the agent
+ * died compares against the tree before the dispatch, not its own start.
+ * @returns {{ at: string, head: string|null, files: Object<string, string|null> }|null}
+ */
+export function snapshotTree(cwd) {
+  try {
+    return { at: new Date().toISOString(), head: headSha(cwd), files: diskBlobs(cwd, changedFiles(cwd)) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Files whose content on disk is not what it was in the snapshot. Content,
+ * not status: a mutation committed since shows up, and a file committed
+ * unchanged does not.
+ * @returns {{ at: string, headChanged: boolean, changed: string[], changedCount: number }}
+ */
+export function compareToSnapshot(cwd, snapshot) {
+  const head = headSha(cwd);
+  const candidates = new Set([...Object.keys(snapshot.files || {}), ...changedFiles(cwd)]);
+  if (snapshot.head && head && snapshot.head !== head) {
+    for (const p of git(cwd, ['diff', '--name-only', '-z', snapshot.head, head, ...OUTSIDE_MORPH]).split('\0')) {
+      if (p) candidates.add(p);
+    }
+  }
+  const paths = [...candidates];
+  const now = diskBlobs(cwd, paths);
+  const unlisted = paths.filter((p) => !(p in (snapshot.files || {})));
+  const before = { ...commitBlobs(cwd, snapshot.head, unlisted), ...snapshot.files };
+  const changed = paths.filter((p) => before[p] !== now[p]).sort();
+  return { at: snapshot.at, headChanged: snapshot.head !== head, changed: changed.slice(0, MAX_LISTED), changedCount: changed.length };
+}
+
+/** `git status --porcelain -z`: a rename carries its old path as an extra entry. */
+function parsePorcelain(out) {
+  const entries = [];
+  const parts = out.split('\0');
+  for (let i = 0; i < parts.length; i++) {
+    const item = parts[i];
+    if (!item) continue;
+    const status = item.slice(0, 2);
+    entries.push({ status: status.trim(), path: item.slice(3) });
+    if (status[0] === 'R' || status[0] === 'C') i++;
+  }
+  return entries;
+}
+
+function diffstat(cwd) {
+  const stat = { files: 0, insertions: 0, deletions: 0 };
+  for (const line of git(cwd, ['diff', 'HEAD', '--numstat', ...OUTSIDE_MORPH]).split('\n')) {
+    const [ins, del] = line.split('\t');
+    if (del === undefined) continue;
+    stat.files += 1;
+    stat.insertions += Number(ins) || 0;
+    stat.deletions += Number(del) || 0;
+  }
+  return stat;
+}
+
+function commitsOnTop(cwd) {
+  const base = resolveBaseRef(detectDefaultBranch(cwd), cwd);
+  if (!base) return null;
+  return git(cwd, ['log', `--max-count=${MAX_COMMITS}`, '--format=%h %s', `${base}..HEAD`])
+    .split('\n').filter(Boolean);
+}
+
+/** Untracked files count too; gitignored ones (build output) do not. */
+function markers(cwd) {
+  try {
+    const out = git(cwd, ['grep', '-n', '-I', '--untracked', '-F', '-e', MUTATION_MARKER, ...OUTSIDE_MORPH]);
+    return out.split('\n').filter(Boolean).slice(0, MAX_LISTED).map((line) => {
+      const [file, lineNo] = line.split(':');
+      return { file, line: Number(lineNo) };
+    });
+  } catch (err) {
+    if (err.status === 1) return [];
+    throw err;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ snapshot?: object|null }} [opts] - a `snapshotTree()` to compare with
+ * @returns {{ head: string|null, branch: string|null, fingerprint: string|null,
+ *   dirty: {status: string, path: string}[], dirtyCount: number,
+ *   diffstat: {files: number, insertions: number, deletions: number}|null,
+ *   commits: string[]|null, markers: {file: string, line: number}[],
+ *   sinceBeforeEval: ReturnType<typeof compareToSnapshot>|null }|null}
+ *   null when git cannot answer (outside a repo, or an error): unknown, never
+ *   a clean tree. `commits` is null when there is no default branch to count
+ *   from; `diffstat` is null before the first commit; `sinceBeforeEval` is
+ *   null without a snapshot.
+ */
+export function treeState(cwd, { snapshot = null } = {}) {
+  try {
+    const dirty = parsePorcelain(git(cwd, ['status', '--porcelain=v1', '-z', ...OUTSIDE_MORPH]));
+    let head = null;
+    try { head = git(cwd, ['rev-parse', '--short', 'HEAD']).trim(); } catch { /* no commit yet */ }
+    return {
+      head,
+      branch: head ? git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']).trim() : null,
+      fingerprint: treeFingerprint(cwd),
+      dirty: dirty.slice(0, MAX_LISTED),
+      dirtyCount: dirty.length,
+      diffstat: head ? diffstat(cwd) : null,
+      commits: head ? commitsOnTop(cwd) : null,
+      markers: markers(cwd),
+      sinceBeforeEval: snapshot ? compareToSnapshot(cwd, snapshot) : null,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/lib/graph/god-nodes.js

@@ -7,11 +7,16 @@
  * substituí-lo, porque exaustividade é um valor que o grafo não tem.
  *
  * Só entram nós COM source_file: um god node sem arquivo não orienta ninguém.
+ * E nada de teste: dublês e fixtures estão no grafo para serem achados, não
+ * para disputar centralidade — sem o filtro o `FakeGhlToolbelt` entra no top
+ * 10 do MORPH_GHLBrain e as arestas vindas de teste inflam o grau de `Result`
+ * de 380 para 443. Aresta com uma ponta em teste não conta para ninguém, e
+ * comunidade só de teste some da lista.
  *
  * @module god-nodes
  */
 import { loadGraph } from './graph-loader.js';
-import { buildIndex, resolveEdgeTarget } from './sanitize.js';
+import { buildIndex, resolveEdgeTarget, linksOf, isTestPath } from './sanitize.js';
 
 /** Sem `graphify label`, as comunidades se chamam Community_N — ruído puro. */
 const PLACEHOLDER_LABEL = /^Community[_ ]?\d+$/i;
@@ -37,9 +42,12 @@ export async function scanGraph(projectPath, opts = {}) {
   const bump = (id) => {
     if (id) degree.set(id, (degree.get(id) ?? 0) + 1);
   };
-  for (const link of graph.links ?? []) {
+  const isTest = (id) => isTestPath(index.byId.get(id)?.source_file);
+  for (const link of linksOf(index, graph)) {
+    const target = resolveEdgeTarget(index, link).id;
+    if (isTest(link.source) || (target && isTest(target))) continue;
     bump(link.source);
-    bump(resolveEdgeTarget(index, link).id);
+    bump(target);
   }
 
   const godNodes = [...degree.entries()]
@@ -57,6 +65,7 @@ export async function scanGraph(projectPath, opts = {}) {
   const labels = new Map();
   for (const node of graph.nodes ?? []) {
     if (node.community === undefined || node.community === null) continue;
+    if (isTestPath(node.source_file)) continue;
     sizes.set(node.community, (sizes.get(node.community) ?? 0) + 1);
     if (node.community_label && !labels.has(node.community)) {
       labels.set(node.community, node.community_label);

package/src/lib/graph/graph-health.js

@@ -6,9 +6,46 @@
  *
  * @module graph-health
  */
-import { loadGraph, getFreshness } from './graph-loader.js';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  loadGraph, getFreshness, describeStale, staleCause,
+} from './graph-loader.js';
 import { GRAPHIFY_VERSION, detectGraphifyVersion } from './graphify-runtime.js';
 
+const GRAPHIFY_HOOK_MARKER = /# graphify-(?:checkout-)?hook-start/;
+
+/**
+ * O hook git do próprio graphify (`graphify hook install`, que o setup-infra
+ * instalava até a 8.37) está no repositório? Ele é danoso aqui: num commit
+ * depois de um fast-forward carimba o HEAD num grafo SEM os arquivos que o
+ * merge trouxe — "fresh" falso — e disputa o graph.json com o refresh do
+ * morph-spec. Lê o diretório de hooks que o git usa (`core.hooksPath`
+ * incluído).
+ *
+ * @param {string} projectPath
+ * @returns {boolean}
+ */
+export function graphifyGitHookInstalled(projectPath) {
+  let dir;
+  try {
+    const rel = execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
+      cwd: projectPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+    }).trim();
+    dir = resolve(projectPath, rel);
+  } catch {
+    return false;
+  }
+  return ['post-commit', 'post-checkout'].some((hook) => {
+    try {
+      return GRAPHIFY_HOOK_MARKER.test(readFileSync(join(dir, hook), 'utf-8'));
+    } catch {
+      return false;
+    }
+  });
+}
+
 /**
  * @param {string} projectPath
  * @param {{_version?: () => string|null}} [deps]
@@ -41,7 +78,16 @@ export function auditGraph(projectPath, deps = {}) {
   if (freshness.state === 'stale') {
     status = 'warn';
     details.push(
-      `stale: construído em ${freshness.builtAtCommit.slice(0, 8)}, HEAD é ${freshness.headCommit.slice(0, 8)} — morph-spec graph refresh`,
+      `stale: ${staleCause(freshness)} — ${describeStale(projectPath, freshness)}`,
+    );
+  }
+
+  if (graphifyGitHookInstalled(projectPath)) {
+    status = 'warn';
+    details.push(
+      'hook git do graphify instalado: depois de um fast-forward ele carimba o HEAD num grafo sem os arquivos do merge ' +
+      'e disputa o graph.json com o refresh do morph-spec — remova com `graphify hook uninstall` ' +
+      '(tira também o merge driver do .gitattributes)',
     );
   }
 

package/src/lib/graph/graph-loader.js

@@ -12,7 +12,14 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { execFileSync } from 'node:child_process';
+import {
+  graphFreshness, readRefreshRecord,
+} from '../../../framework/hooks/shared/graph-freshness.js';
+import {
+  isPrimaryTree, readRefreshLock, resolveGraphify,
+} from '../../../framework/hooks/shared/graph-refresh.js';
+import { isSecondaryWorktree, workTreeTop } from '../../../framework/hooks/shared/git-paths.js';
+import { GRAPHIFY_PACKAGE, GRAPHIFY_VERSION } from './graphify-runtime.js';
 
 /**
  * @param {string} projectPath
@@ -50,37 +57,104 @@ export function loadGraph(projectPath) {
   }
 }
 
-function readHead(projectPath) {
-  try {
-    return execFileSync('git', ['rev-parse', 'HEAD'], {
-      cwd: projectPath,
-      encoding: 'utf-8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim() || null;
-  } catch {
-    return null;
-  }
-}
-
 /**
- * O hook post-commit do graphify rebuilda em BACKGROUND: logo depois de um
- * commit o grafo ainda é o do commit anterior. Quem consome precisa saber, ou
- * conclui "ninguém usa isso" a partir de um grafo velho.
+ * O frescor do grafo, pela regra única (framework/hooks/shared/graph-freshness.js):
+ * o carimbo e o registro da última rodada contra o HEAD, e as regras do
+ * `.graphifyignore` por conteúdo. Um grafo velho diz "não existe" sobre o que
+ * o último commit trouxe — quem consome precisa saber, ou conclui "ninguém usa
+ * isso" a partir dele.
  *
  * @param {string} projectPath
- * @param {object} graph
+ * @param {object} graph - o graph.json já parseado (o carimbo sai dele)
  * @param {{_head?: (projectPath: string) => string|null}} [deps]
- * @returns {{builtAtCommit: string|null, headCommit: string|null, state: 'fresh'|'stale'|'unknown'}}
+ * @returns {{builtAtCommit: string|null, headCommit: string|null, state: 'fresh'|'stale'|'unknown', reason?: 'ignore-changed'|'rules-unknown'}}
  */
 export function getFreshness(projectPath, graph, deps = {}) {
-  const headCommit = (deps._head ?? readHead)(projectPath);
-  const builtAtCommit = graph?.built_at_commit ?? null;
-  if (!headCommit || !builtAtCommit) {
-    return { builtAtCommit, headCommit, state: 'unknown' };
+  const f = graphFreshness(projectPath, {
+    graph,
+    ...(deps._head ? { head: deps._head(projectPath) } : {}),
+  });
+  return {
+    builtAtCommit: f.built,
+    headCommit: f.head,
+    state: f.state === 'missing' ? 'unknown' : f.state,
+    ...(f.reason ? { reason: f.reason } : {}),
+  };
+}
+
+const short = (sha) => (sha ? String(sha).slice(0, 8) : '?');
+
+/**
+ * O porquê de um grafo stale, em uma linha — carimbo antigo ou regras.
+ *
+ * @param {{builtAtCommit: string|null, headCommit: string|null, reason?: string}} freshness
+ * @returns {string}
+ */
+export function staleCause(freshness) {
+  if (freshness.reason === 'ignore-changed') {
+    return 'as regras do .graphifyignore mudaram depois da extração';
+  }
+  if (freshness.reason === 'rules-unknown') {
+    return 'sem registro das regras do .graphifyignore com que o grafo foi extraído';
   }
+  return `construído em ${short(freshness.builtAtCommit)}, HEAD é ${short(freshness.headCommit)}`;
+}
+
+/**
+ * O que o refresh automático faz por esta árvore. Ele cobre só a árvore
+ * principal (`auto`); numa worktree, `running` é sempre false — um lock vivo
+ * ali seria o refresh da raiz. `last` é a última rodada registrada para esta
+ * árvore: em background, manual ou a semeadura.
+ *
+ * @param {string} projectPath
+ * @returns {{auto: boolean, running: boolean, since: string|null, pid: number|null, last: {ok: boolean, exit: number|null, head: string|null, ts: string, unavailable?: boolean, seeded?: boolean}|null}}
+ */
+export function refreshState(projectPath) {
+  const auto = isPrimaryTree(projectPath);
+  const lock = auto ? readRefreshLock(projectPath) : null;
+  const record = readRefreshRecord(projectPath);
   return {
-    builtAtCommit,
-    headCommit,
-    state: builtAtCommit === headCommit ? 'fresh' : 'stale',
+    auto,
+    running: Boolean(lock?.live),
+    since: lock?.live ? lock.since : null,
+    pid: lock?.live ? lock.pid : null,
+    last: record ? {
+      ok: record.exit === 0,
+      exit: record.exit ?? null,
+      head: record.head ?? null,
+      ts: record.at,
+      ...(record.unavailable ? { unavailable: true } : {}),
+      ...(record.seeded ? { seeded: true } : {}),
+    } : null,
   };
 }
+
+/**
+ * A frase de grafo stale — a mesma no status, no explain, no affected e no
+ * doctor, e verdadeira sobre o mecanismo: o refresh em background só cobre a
+ * raiz, disparado pelos hooks do morph-spec; a worktree só anda à mão.
+ *
+ * @param {string} projectPath
+ * @param {{builtAtCommit?: string|null, headCommit?: string|null}} [freshness]
+ * @returns {string}
+ */
+export function describeStale(projectPath, freshness = {}) {
+  const tree = workTreeTop(projectPath) ?? projectPath;
+  const state = refreshState(projectPath);
+  if (!state.auto && isSecondaryWorktree(tree)) {
+    return state.last?.seeded
+      ? `grafo semeado da raiz em ${short(state.last.head ?? freshness.builtAtCommit)}; \`morph-spec graph refresh\` atualiza esta worktree`
+      : 'o refresh automático só cobre a raiz; `morph-spec graph refresh` atualiza esta worktree';
+  }
+  if (state.running) {
+    return `refresh em background em andamento desde ${new Date(state.since).toLocaleTimeString()} — confirme no código antes de agir`;
+  }
+  // Registrado como ausente mas já de volta ao PATH: o próximo disparo roda.
+  if (state.last?.unavailable && !resolveGraphify()) {
+    return `graphify fora do PATH: o refresh automático está parado até ele voltar (uv tool install ${GRAPHIFY_PACKAGE}==${GRAPHIFY_VERSION}); depois, morph-spec graph refresh`;
+  }
+  if (state.last && !state.last.ok && state.last.head === (freshness.headCommit ?? null)) {
+    return `o último refresh falhou neste HEAD (exit ${state.last.exit ?? '?'}) e só se repete quando o HEAD andar — rode morph-spec graph refresh e leia a saída`;
+  }
+  return 'o refresh roda em background depois dos comandos git/gh/morph-spec do agente e no início da sessão; para já: morph-spec graph refresh';
+}

package/src/lib/graph/graphifyignore.js

@@ -2,30 +2,53 @@
  * Geração stack-aware do .graphifyignore (ADR-004).
  *
  * Filtrar teste não é cosmético: sem isso o god node #1 do MORPH_GHLBrain é
- * `FakeGhlToolbelt`, um dublê. Pior, os dublês criam um segundo implementador e
- * quebram o guard de "implementador único" do `dispatches_to` — a aresta que
- * atravessa a injeção de dependência cai de 109 para 1.
+ * `FakeGhlToolbelt`, um dublê. E o padrão genérico `tests/` NÃO serve em .NET:
+ * no ProspectPRO os testes vivem em `src/backend/ProspectPRO.Tests/`. Com
+ * `**\/*.Tests/` o grafo caiu de 10.450 para 7.384 nós — 30% era ruído de teste.
  *
- * E o padrão genérico `tests/` NÃO serve em .NET: no ProspectPRO os testes
- * vivem em `src/backend/ProspectPRO.Tests/`. Com `**\/*.Tests/` o grafo caiu de
- * 10.450 para 7.384 nós — 30% era ruído de teste.
+ * Mas dublê, fixture e helper de teste precisam ser ACHÁVEIS: são o que um
+ * teste novo deveria reusar, e fora do grafo `graph explain FakeX` dá
+ * not-found. Por isso o conteúdo dos projetos de teste sai e esses arquivos
+ * voltam. A forma é ditada pela regra do gitignore que o graphify 0.9.50 segue
+ * (detect.py `_is_ignored`): um `!` não reinclui nada sob um diretório já
+ * excluído. Medido num fixture: `**\/*.Tests/` + `!**\/Fakes/` não traz nada de
+ * volta; excluir o CONTEÚDO (`**\/*.Tests/**`), reincluir os diretórios
+ * (`!**\/*.Tests/**\/`) e então os helpers traz. `bin/`/`obj/` vêm DEPOIS das
+ * reinclusões — antes, a reinclusão de diretório os devolveria (`obj/` tem
+ * `.cs` gerado). No MORPH_GHLBrain: +9,6% de nós (11.591 → 12.706), 94
+ * arquivos de teste, nenhum de bin/obj.
+ *
+ * Os dublês quebram o guard de "implementador único" do `dispatches_to` do
+ * graphify (de 122 para 5 arestas no GHLBrain); o saneamento as recupera
+ * (sanitize.js `recoverDispatch`) e tira o teste dos god nodes.
  *
  * Em Next.js o problema é outro: metade dos nós vinha de JSON de configuração,
  * e os god nodes viravam `dependencies` e `compilerOptions`.
  *
  * @module graphifyignore
  */
-import { writeFileSync, existsSync } from 'node:fs';
+import { writeFileSync, existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
+import { ignoreRules } from '../../../framework/hooks/shared/graph-freshness.js';
 
 export const ALWAYS_IGNORED = [
   '.git/', '.morph/', 'artifacts/', ...WORKTREE_DIR_NAMES.map((d) => `${d}/`),
   'coverage/', 'graphify-out/', 'dist/', 'out/',
 ];
 
+const TEST_PROJECTS = ['**/*.Tests', '**/*Tests', '**/*.Test'];
+const TEST_HELPER_DIRS = ['TestDoubles', 'Fakes', 'Stubs', 'Mocks', 'Fixtures', 'Helpers', 'Builders'];
+const TEST_HELPER_FILES = ['*Fixture.cs', '*Fixtures.cs', 'Fake*.cs', 'Stub*.cs', '*Stub.cs'];
+const DOTNET_BUILD_OUTPUT = ['bin/', 'obj/', 'TestResults/'];
+
 const DOTNET_IGNORED = [
-  '**/*.Tests/', '**/*Tests/', '**/*.Test/', 'bin/', 'obj/', 'TestResults/',
+  ...TEST_PROJECTS.map((p) => `${p}/**`),
+  ...TEST_PROJECTS.map((p) => `!${p}/**/`),
+  ...TEST_HELPER_DIRS.map((d) => `!**/${d}/**`),
+  ...TEST_HELPER_FILES.map((f) => `!**/${f}`),
+  ...DOTNET_BUILD_OUTPUT,
 ];
 
 const WEB_IGNORED = [
@@ -35,31 +58,35 @@ const WEB_IGNORED = [
   '/next.config.js', '/next.config.mjs', '/tailwind.config.js', '/tailwind.config.ts',
 ];
 
+const HEADER = '# Gerado por morph-spec (ADR-004). Editável: um arquivo editado nunca é sobrescrito.';
+
+/**
+ * O que a versão anterior gerava — os testes .NET inteiros fora. Só existe
+ * para reconhecer um arquivo que ninguém editou e trocá-lo pelo atual.
+ */
+const PREVIOUS = {
+  header: '# Gerado por morph-spec (ADR-004). Editável: o CLI não sobrescreve.',
+  dotnetTitle: '# .NET — testes em qualquer nível (tests/ genérico não serve)',
+  dotnet: ['**/*.Tests/', '**/*Tests/', '**/*.Test/', ...DOTNET_BUILD_OUTPUT],
+};
+
 const DOTNET_TAGS = new Set(['dotnet', 'aspnet']);
 const WEB_TAGS = new Set([
   'nextjs', 'next', 'next.js', 'react', 'vue', 'nodejs', 'nodejs-cli', 'node-cli',
 ]);
 
-/**
- * @param {string[]} [projectTags] saída de `getProjectTags(config)` — stack
- *   splitado por `-`/`+` mais as integrations
- * @returns {string} conteúdo completo do .graphifyignore
- */
-export function buildGraphifyignore(projectTags = []) {
+const hasDotnetTag = (tags) => [...new Set(tags)].some((t) => DOTNET_TAGS.has(t));
+
+function render(projectTags, { header, dotnetTitle, dotnet }) {
   const tags = new Set(projectTags);
-  const hasDotnet = [...tags].some((t) => DOTNET_TAGS.has(t));
   const hasWeb = [...tags].some((t) => WEB_TAGS.has(t));
 
   const sections = [
-    ['# Gerado por morph-spec (ADR-004). Editável: o CLI não sobrescreve.', ''],
+    [header, ''],
     ['# Sempre', ...ALWAYS_IGNORED],
   ];
-  if (hasDotnet) {
-    sections.push(['', '# .NET — testes em qualquer nível (tests/ genérico não serve)', ...DOTNET_IGNORED]);
-  }
-  if (hasWeb) {
-    sections.push(['', '# Web — dependências e JSON de configuração de raiz', ...WEB_IGNORED]);
-  }
+  if (hasDotnetTag(tags)) sections.push(['', dotnetTitle, ...dotnet]);
+  if (hasWeb) sections.push(['', '# Web — dependências e JSON de configuração de raiz', ...WEB_IGNORED]);
 
   const seen = new Set();
   const lines = [];
@@ -73,15 +100,105 @@ export function buildGraphifyignore(projectTags = []) {
 }
 
 /**
- * Escreve o .graphifyignore. Arquivo já existente é do usuário: não é tocado.
+ * @param {string[]} [projectTags] saída de `getProjectTags(config)` — stack
+ *   splitado por `-`/`+` mais as integrations
+ * @returns {string} conteúdo completo do .graphifyignore
+ */
+export function buildGraphifyignore(projectTags = []) {
+  return render(projectTags, {
+    header: HEADER,
+    dotnetTitle: '# .NET — conteúdo dos projetos de teste fora; dublês, fixtures e helpers dentro',
+    dotnet: DOTNET_IGNORED,
+  });
+}
+
+const normalize = (text) => String(text).replace(/^/, '').replace(/\r\n/g, '\n');
+
+/**
+ * Escreve ou migra o .graphifyignore.
+ *
+ *   ausente                                → escreve o atual
+ *   idêntico ao que a versão anterior
+ *   gerava para as mesmas tags             → troca pelo atual (`migrated`) —
+ *                                            só se as REGRAS mudam (em
+ *                                            projeto sem .NET a diferença é
+ *                                            só o cabeçalho, e reescrever
+ *                                            seria um diff à toa num arquivo
+ *                                            versionado)
+ *   qualquer outra coisa                   → é do usuário: não toca, e em
+ *                                            projeto .NET que ainda exclui os
+ *                                            testes inteiros devolve em
+ *                                            `outdated` a troca a fazer
  *
  * @param {string} projectPath
  * @param {string[]} [projectTags]
- * @returns {{written: boolean, path: string}}
+ * @param {{fx?: {writeFile: (path: string, content: string) => void}}} [opts]
+ *   coletor de efeitos do `update` — com ele, o `--dry-run` prevê a escrita
+ * @returns {{written: boolean, migrated?: boolean, outdated?: {remove: string[], add: string[]}, path: string}}
  */
-export function writeGraphifyignore(projectPath, projectTags = []) {
+export function writeGraphifyignore(projectPath, projectTags = [], { fx } = {}) {
   const path = join(projectPath, '.graphifyignore');
-  if (existsSync(path)) return { written: false, path };
-  writeFileSync(path, buildGraphifyignore(projectTags), 'utf-8');
-  return { written: true, path };
+  const current = buildGraphifyignore(projectTags);
+  const write = () => (fx ? fx.writeFile(path, current) : writeFileSync(path, current, 'utf-8'));
+
+  if (!existsSync(path)) {
+    write();
+    return { written: true, path };
+  }
+
+  let existing;
+  try {
+    existing = normalize(readFileSync(path, 'utf-8'));
+  } catch {
+    return { written: false, path };
+  }
+  if (existing === current) return { written: false, path };
+  if (existing === render(projectTags, PREVIOUS)) {
+    // A régua é a mesma do frescor do grafo (graph-freshness.js): o que o
+    // graphify lê, sem cabeçalho nem comentário.
+    if (ignoreRules(existing) === ignoreRules(current)) return { written: false, path };
+    write();
+    return { written: true, migrated: true, path };
+  }
+
+  // Acrescentar não basta: enquanto `**/*.Tests/` excluir o DIRETÓRIO, nenhum
+  // `!` reinclui o que está dentro dele.
+  const lines = new Set(existing.split('\n').map((l) => l.trim()));
+  const remove = PREVIOUS.dotnet.slice(0, 3).filter((l) => lines.has(l));
+  if (hasDotnetTag(projectTags) && remove.length) {
+    const add = DOTNET_IGNORED.filter((l) => !DOTNET_BUILD_OUTPUT.includes(l) && !lines.has(l));
+    return { written: false, outdated: { remove, add }, path };
+  }
+  return { written: false, path };
+}
+
+/**
+ * A frase que todo chamador imprime para um `outdated` — uma só.
+ *
+ * @param {{remove: string[], add: string[]}} outdated
+ * @returns {string}
+ */
+export function describeOutdatedIgnore(outdated) {
+  return `.graphifyignore editado mantém os testes .NET inteiros fora do grafo ` +
+    `(dublês e fixtures dão not-found). Troque ${outdated.remove.join(' ')} por, nesta ordem e ` +
+    `antes de bin/ e obj/: ${outdated.add.join(' ')} — depois, morph-spec graph refresh`;
+}
+
+/**
+ * O `.graphifyignore` é versionado? Então uma migração só chega às worktrees
+ * e ao resto do time depois de commitada — cada checkout lê o seu. Fail-open:
+ * sem git, false.
+ *
+ * @param {string} projectPath
+ * @returns {boolean}
+ */
+export function graphifyignoreTracked(projectPath) {
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', '.graphifyignore'], {
+      cwd: projectPath, stdio: 'ignore', windowsHide: true, timeout: 10000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
 }