@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -1,39 +1,31 @@
-/**
- * A hash of what a verify run reads: the commit, the uncommitted changes and
- * the untracked files, plus the project's `config.json` (it names the test
- * commands). Everything else under `.morph/` stays out — verify itself writes
- * feature.json and the logs on every run, and counting that would make two
- * runs over the same code look different.
- */
+// `.morph/` stays out except `config.json` minus `expectedCount`, as in `treeMovedSince`:
+// committing verify's own bookkeeping must not make the same code look different.
 
 import { execFileSync } from 'child_process';
 import { createHash } from 'crypto';
 import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
+import { withoutBaseline } from './evidence-staleness.js';
 
-/** Pathspec for "the project minus its `.morph/` bookkeeping". */
 export const OUTSIDE_MORPH = ['--', '.', ':(exclude).morph'];
 const MAX_OUTPUT = 64 * 1024 * 1024;
 
-/** git output as a Buffer; stderr dropped, throws on a non-zero exit. */
 export function git(projectPath, args, input) {
   return execFileSync('git', args, {
     cwd: projectPath, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'], maxBuffer: MAX_OUTPUT, input,
   });
 }
 
-/**
- * @param {string} projectPath
- * @returns {string|null} sha256 hex, or null outside a git repo / on any git error
- */
+/** @returns {string|null} sha256 hex, or null outside a git repo / on any git error */
 export function treeFingerprint(projectPath) {
   try {
     const hash = createHash('sha256');
     let head = null;
     try { head = git(projectPath, ['rev-parse', 'HEAD']).toString().trim(); } catch { /* no commit yet */ }
-    hash.update(`head\0${head ?? 'no-commit'}\0`);
-    // Before the first commit there is no HEAD to diff against: every file is
-    // untracked, and the listing below covers them.
+    const tree = head
+      ? git(projectPath, ['ls-tree', '-z', 'HEAD']).toString().split('\0').filter((e) => e && e.split('\t')[1] !== '.morph')
+      : ['no-commit'];
+    hash.update(`tree\0${tree.join('\0')}\0`);
     if (head) hash.update(git(projectPath, ['diff', 'HEAD', '--binary', ...OUTSIDE_MORPH]));
     hash.update('\0untracked\0');
     const untracked = git(projectPath, ['ls-files', '--others', '--exclude-standard', '-z', ...OUTSIDE_MORPH])
@@ -50,9 +42,17 @@ export function treeFingerprint(projectPath) {
     }
     const config = join(projectPath, '.morph', 'config', 'config.json');
     hash.update('\0config\0');
-    if (existsSync(config)) hash.update(readFileSync(config));
+    if (existsSync(config)) hash.update(normalizedConfig(readFileSync(config, 'utf8')));
     return hash.digest('hex');
   } catch {
     return null;
   }
 }
+
+function normalizedConfig(text) {
+  try {
+    return JSON.stringify(withoutBaseline(text));
+  } catch {
+    return text;
+  }
+}

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

@@ -1,17 +1,9 @@
-/**
- * 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;
@@ -24,13 +16,11 @@ 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') : [];
@@ -39,7 +29,6 @@ function diskBlobs(cwd, paths) {
   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;
@@ -49,10 +38,8 @@ function commitBlobs(cwd, commit, paths) {
 }
 
 /**
- * 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.
+ * HEAD plus the blob of every file that differs from it, kept on disk so a resumed
+ * session 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) {
@@ -64,9 +51,8 @@ export function snapshotTree(cwd) {
 }
 
 /**
- * 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.
+ * Compares 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) {
@@ -85,7 +71,7 @@ export function compareToSnapshot(cwd, snapshot) {
   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. */
+// With `-z`, a rename or copy carries its old path as an extra entry.
 function parsePorcelain(out) {
   const entries = [];
   const parts = out.split('\0');
@@ -118,7 +104,6 @@ function commitsOnTop(cwd) {
     .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]);
@@ -132,19 +117,7 @@ function markers(cwd) {
   }
 }
 
-/**
- * @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.
- */
+/** @returns {object|null} null when git cannot answer: unknown, never a clean tree. */
 export function treeState(cwd, { snapshot = null } = {}) {
   try {
     const dirty = parsePorcelain(git(cwd, ['status', '--porcelain=v1', '-z', ...OUTSIDE_MORPH]));

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

@@ -1,31 +1,11 @@
-/**
- * God nodes e comunidades para o contexto de arquitetura.
- *
- * O inventário do architecture-scanner diz o que EXISTE; os god nodes dizem o
- * que é CENTRAL. No ProspectPRO, seis linhas (`Result` 223, `Abstractions` 217,
- * `Repository` 156, `cn()` 141) orientam melhor que 665 de inventário — sem
- * 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
- */
+// Só nós com source_file, e nada de teste: dublês e fixtures estão no grafo para serem achados, não para
+// disputar centralidade. Aresta com uma ponta em teste não conta, e comunidade só de teste some.
 import { loadGraph } from './graph-loader.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;
 
-/**
- * @param {string} projectPath
- * @param {{top?: number, topCommunities?: number}} [opts]
- * @returns {Promise<{available: boolean, godNodes: Array<{label: string, source_file: string, degree: number}>, communities: Array<{id: number, label: string, size: number, labeled: boolean}>}>}
- */
 export async function scanGraph(projectPath, opts = {}) {
   const top = opts.top ?? 10;
   const topCommunities = opts.topCommunities ?? 10;

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

@@ -1,11 +1,4 @@
-/**
- * Auditoria do grafo para o `morph-spec doctor`.
- *
- * Nunca devolve estado de erro: o grafo é opcional (ADR-002) e não pode pintar
- * de vermelho o doctor de um projeto que não o usa. O pior veredito é `warn`.
- *
- * @module graph-health
- */
+// Nunca devolve erro: o grafo é opcional e não pode pintar de vermelho o doctor de quem não o usa.
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -16,17 +9,8 @@ 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}
- */
+// O hook git do próprio graphify é danoso: depois de um fast-forward carimba o HEAD num grafo sem os
+// arquivos do merge ("fresh" falso) e disputa o graph.json com o refresh. Respeita `core.hooksPath`.
 export function graphifyGitHookInstalled(projectPath) {
   let dir;
   try {
@@ -46,11 +30,6 @@ export function graphifyGitHookInstalled(projectPath) {
   });
 }
 
-/**
- * @param {string} projectPath
- * @param {{_version?: () => string|null}} [deps]
- * @returns {{status: 'ok'|'warn'|'absent', msg: string, details: string[]}}
- */
 export function auditGraph(projectPath, deps = {}) {
   const installed = (deps._version ?? detectGraphifyVersion)();
   const loaded = loadGraph(projectPath);

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

@@ -1,15 +1,4 @@
-/**
- * Leitura fail-open do graph.json produzido pelo graphify.
- *
- * Medido em 2026-08-27 sobre o MORPH_GHLBrain (11,46 MB, 6.829 nós, 15.668
- * arestas): JSON.parse leva 52 ms e 28 MB de heap. Streaming e cache são
- * desnecessários nesse porte — se um dia deixarem de ser, a troca acontece só
- * aqui, porque este módulo é a única porta de leitura do grafo.
- *
- * Nada aqui lança: ausência de grafo é um estado válido do projeto (ADR-002).
- *
- * @module graph-loader
- */
+// A única porta de leitura do grafo, e nada aqui lança: ausência de grafo é um estado válido do projeto.
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import {
@@ -21,18 +10,10 @@ import {
 import { isSecondaryWorktree, workTreeTop } from '../../../framework/hooks/shared/git-paths.js';
 import { GRAPHIFY_PACKAGE, GRAPHIFY_VERSION } from './graphify-runtime.js';
 
-/**
- * @param {string} projectPath
- * @returns {string} caminho canônico do graph.json do projeto
- */
 export function resolveGraphPath(projectPath) {
   return join(projectPath, 'graphify-out', 'graph.json');
 }
 
-/**
- * @param {string} projectPath
- * @returns {{ok: boolean, reason?: 'missing'|'unreadable'|'malformed', graph?: object, path: string}}
- */
 export function loadGraph(projectPath) {
   const path = resolveGraphPath(projectPath);
   if (!existsSync(path)) return { ok: false, reason: 'missing', path };
@@ -57,18 +38,7 @@ export function loadGraph(projectPath) {
   }
 }
 
-/**
- * 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 - 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', reason?: 'ignore-changed'|'rules-unknown'}}
- */
+// Um grafo velho diz "não existe" sobre o que o último commit trouxe: quem consome precisa saber.
 export function getFreshness(projectPath, graph, deps = {}) {
   const f = graphFreshness(projectPath, {
     graph,
@@ -84,12 +54,6 @@ export function getFreshness(projectPath, graph, deps = {}) {
 
 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';
@@ -100,15 +64,8 @@ export function staleCause(freshness) {
   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}}
- */
+// O refresh automático cobre só a árvore principal; numa worktree `running` é sempre false, porque um
+// lock vivo ali seria o refresh da raiz.
 export function refreshState(projectPath) {
   const auto = isPrimaryTree(projectPath);
   const lock = auto ? readRefreshLock(projectPath) : null;
@@ -129,15 +86,7 @@ export function refreshState(projectPath) {
   };
 }
 
-/**
- * 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}
- */
+/** A frase única de grafo stale do status, explain, affected e doctor. */
 export function describeStale(projectPath, freshness = {}) {
   const tree = workTreeTop(projectPath) ?? projectPath;
   const state = refreshState(projectPath);

package/src/lib/graph/graphify-runtime.js

@@ -1,23 +1,9 @@
-/**
- * Descoberta do runtime Python e argv de instalação do graphify.
- *
- * O binário instalado chama-se `graphify` (e `graphify-mcp` para o servidor
- * MCP). NUNCA use `python -m graphify.serve`, que é o que o README oficial
- * manda: com `uv tool install` o pacote vive num venv isolado e o Python do
- * sistema não o enxerga (ModuleNotFoundError) — medido no eval, Eixo 2.
- *
- * Toda descoberta é injetável (`_which`, `_run`) para que o teste cubra Windows
- * e POSIX sem depender do PATH da máquina que roda o CI.
- *
- * @module graphify-runtime
- */
+// O binário é `graphify` (e `graphify-mcp`). NUNCA `python -m graphify.serve`, como manda o README oficial:
+// com `uv tool install` o pacote vive num venv isolado que o Python do sistema não enxerga.
 import { execFileSync } from 'node:child_process';
 
-/**
- * Pin exato: 0.9.50 é a única versão medida no eval e a base do fixture de
- * regressão. O graphify é pré-1.0 com release quase diária, então semver não
- * garante nada — bump é decisão consciente, com re-run do fixture.
- */
+// Pin exato: o graphify é pré-1.0 com release quase diária e semver não garante nada; subir é decisão
+// consciente, com o fixture de regressão regerado.
 export const GRAPHIFY_VERSION = '0.9.50';
 export const GRAPHIFY_PACKAGE = 'graphifyy';
 export const GRAPHIFY_BIN = 'graphify';
@@ -38,14 +24,7 @@ function whichSync(bin) {
   }
 }
 
-/**
- * uv > pipx > python3 > python. `kind: null` significa "sem Python": o step do
- * setup-infra registra e segue, e o framework continua funcionando por grep
- * (ADR-002).
- *
- * @param {{_which?: (bin: string) => string|null}} [deps]
- * @returns {{kind: 'uv'|'pipx'|'python3'|'python'|null, bin: string|null}}
- */
+// `kind: null` é "sem Python": o setup registra e segue, e o framework continua funcionando por grep.
 export function detectInstaller(deps = {}) {
   const which = deps._which ?? whichSync;
   for (const kind of PREFERENCE) {
@@ -60,13 +39,7 @@ export function detectInstaller(deps = {}) {
   return { kind: null, bin: null };
 }
 
-/**
- * @param {'uv'|'pipx'|'python3'|'python'} kind
- * @param {{withSql: boolean}} opts sem o extra `[sql]` os arquivos .sql são
- *   ignorados em silêncio (92 no ProspectPRO) — só um aviso no meio do output
- *   denuncia
- * @returns {{cmd: string, args: string[]}}
- */
+// Sem o extra `[sql]` os arquivos .sql são ignorados em silêncio.
 export function installArgs(kind, { withSql }) {
   const spec = `${GRAPHIFY_PACKAGE}${withSql ? '[sql]' : ''}==${GRAPHIFY_VERSION}`;
   switch (kind) {
@@ -82,10 +55,7 @@ export function installArgs(kind, { withSql }) {
   }
 }
 
-/**
- * @param {{_run?: () => string}} [deps]
- * @returns {string|null} versão instalada, ou null se o binário não responde
- */
+/** Versão instalada, ou null se o binário não responde. */
 export function detectGraphifyVersion(deps = {}) {
   const run = deps._run ?? (() => execFileSync(GRAPHIFY_BIN, ['--version'], {
     encoding: 'utf-8',

package/src/lib/graph/graphifyignore.js

@@ -1,32 +1,6 @@
-/**
- * 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ê. 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
- */
+// Teste sai do grafo, mas dublês e helpers voltam: são o que um teste novo reusa. Pela regra do gitignore
+// um `!` não reinclui nada sob diretório excluído, então exclui-se o conteúdo, reincluem-se os diretórios e
+// então os helpers; `bin/`/`obj/` vêm depois, senão a reinclusão os devolveria.
 import { writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
@@ -60,10 +34,7 @@ const WEB_IGNORED = [
 
 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.
- */
+// O que a geração anterior escrevia: só reconhece um arquivo que ninguém editou, para trocá-lo.
 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)',
@@ -99,11 +70,6 @@ function render(projectTags, { header, dotnetTitle, dotnet }) {
   return `${lines.join('\n')}\n`;
 }
 
-/**
- * @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,
@@ -114,28 +80,8 @@ export function buildGraphifyignore(projectTags = []) {
 
 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]
- * @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}}
- */
+// Ausente → escreve. Idêntico ao que a geração anterior escrevia → migra, só se as regras mudam.
+// Qualquer outra coisa é do usuário: não toca, e em .NET devolve em `outdated` a troca a fazer.
 export function writeGraphifyignore(projectPath, projectTags = [], { fx } = {}) {
   const path = join(projectPath, '.graphifyignore');
   const current = buildGraphifyignore(projectTags);
@@ -172,26 +118,14 @@ export function writeGraphifyignore(projectPath, projectTags = [], { fx } = {})
   return { written: false, path };
 }
 
-/**
- * A frase que todo chamador imprime para um `outdated` — uma só.
- *
- * @param {{remove: string[], add: string[]}} outdated
- * @returns {string}
- */
+/** A frase única que todo chamador imprime para um `outdated`. */
 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}
- */
+// Versionado, uma migração só chega às worktrees depois de commitada. Fail-open: sem git, false.
 export function graphifyignoreTracked(projectPath) {
   try {
     execFileSync('git', ['ls-files', '--error-unmatch', '--', '.graphifyignore'], {