@polymorphism-tech/morph-spec 8.37.1 → 8.38.0

package/src/dashboard/scanner/hooks-scanner.js

@@ -38,6 +38,8 @@ const EVENT_KEYS = {
   UserPromptSubmit: 'user-prompt',
   PreToolUse: 'pre-tool-use',
   PostToolUse: 'post-tool-use',
+  PostToolUseFailure: 'post-tool-use',
+  PostToolBatch: 'post-tool-use',
   Stop: 'stop',
   SubagentStop: 'stop',
   PreCompact: 'pre-compact',
@@ -76,7 +78,12 @@ export function hookRegistrations(definitions = getHookDefinitions()) {
         : [file];
       for (const f of files) {
         if (!byFile.has(f)) byFile.set(f, []);
-        byFile.get(f).push({ event: key, rawEvent: def.event, matcher: def.matcher || null });
+        const entries = byFile.get(f);
+        const matcher = def.matcher || null;
+        // Several raw events share one Inspector column (PostToolUse and its
+        // Failure/Batch siblings): one node per column, not one per event.
+        if (entries.some((e) => e.event === key && e.matcher === matcher)) continue;
+        entries.push({ event: key, rawEvent: def.event, matcher });
       }
     }
   }

package/src/dashboard/scanner/standards-scanner.js

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
+import { personaStandardIds } from '../../utils/agents-installer.js';
 
 export function scanStandards(frameworkDir, agents) {
   const standardsJsonPath = join(frameworkDir, 'standards', 'STANDARDS.json');
@@ -7,7 +8,7 @@ export function scanStandards(frameworkDir, agents) {
   const sJson = JSON.parse(readFileSync(standardsJsonPath, 'utf8'));
   const refMap = {};
   for (const agent of agents) {
-    for (const std of agent.standards || []) {
+    for (const std of personaStandardIds(agent)) {
       // agents.json stores standards as plain id STRINGS. Reading `std.id` off
       // a string yields undefined, so every reference piled into refMap
       // [undefined] and the lookup below missed all 60 — the Standards graph

package/src/lib/ai/comment-stripper.js

@@ -2,14 +2,17 @@
  * comment-stripper.js — apagar comentários SEM apagar o que está dentro de uma
  * string, preservando comprimento e quebras de linha.
  *
- * Existe uma vez só, e serve a dois consumidores que fariam a MESMA coisa de
+ * Existe uma vez só, e serve a consumidores que fariam a MESMA coisa de
  * jeitos ligeiramente diferentes se cada um escrevesse o seu:
  *
  *   - `code-audit.js` — não pode acusar `AgentThread` que só aparece num
  *     comentário ou numa mensagem de log;
  *   - `registry-audit.js` — precisa ler **JSONC**, a forma que o exemplar
  *     canônico `model-registry.v2.json` usa e que o leitor C# do kit aceita de
- *     propósito (`JsonCommentHandling.Skip`, `AllowTrailingCommas`).
+ *     propósito (`JsonCommentHandling.Skip`, `AllowTrailingCommas`);
+ *   - `dotnet-test-introspection.js` — lê o `global.json` por `jsoncToJson`;
+ *   - `validators/code-budget/comment-scanner.js` — acha as linhas de
+ *     comentário de `.cs`/`.ts`/`.js`, e é o único que liga a opção `js`.
  *
  * **Por que não um regex.** O exemplar tem `"http://localhost:11434/v1"` e uma
  * `provenance` com URL. Um `replace(/\/\/.*$/gm, '')` decapitaria as duas —
@@ -36,13 +39,18 @@
  *   `○ não verificado`. O B1 reintroduzido pela correção do B1.
  * @param {{ unterminated?: string|null }} [options.report]
  *   Se um objeto for passado, recebe `unterminated` = `'block-comment'`,
- *   `'string'`, `'verbatim-string'`, `'raw-string'` ou `null`. É o canal de
+ *   `'string'`, `'verbatim-string'`, `'raw-string'`, `'template'` ou `null`. É o canal de
  *   diagnóstico que `jsoncToJson` usa para ficar tão estrito quanto o leitor
  *   de produção, sem que este lexer precise lançar (ele também varre `.cs`,
  *   onde um comentário aberto é problema do arquivo, não da varredura).
+ * @param {boolean} [options.js=false]
+ *   Lê também template literal e regex literal de TS/JS. Opt-in porque só
+ *   quem varre `.ts`/`.js` precisa: sem template, `https://${h}` vira
+ *   comentário; sem regex, uma crase dentro de `/[`']/` abre um template que
+ *   engole o resto do arquivo.
  * @returns {string} texto do MESMO comprimento
  */
-export function stripComments(text, { blankStrings = false, report = null } = {}) {
+export function stripComments(text, { blankStrings = false, report = null, js = false } = {}) {
   const out = text.split('');
   const blank = (from, to) => {
     for (let k = from; k < to && k < out.length; k++) {
@@ -73,6 +81,19 @@ export function stripComments(text, { blankStrings = false, report = null } = {}
       continue;
     }
 
+    if (js && c === '`') {
+      const end = templateEnd(text, i);
+      if (end === -1) flag('template');
+      const stop = end === -1 ? text.length : end;
+      if (blankStrings) blank(i + 1, end === -1 ? stop : stop - 1);
+      i = stop;
+      continue;
+    }
+    if (js && c === '/' && next !== '>' && regexMayStart(out, i)) {
+      const end = regexEnd(text, i);
+      if (end !== -1) { i = end; continue; }
+    }
+
     // Raw string literal do C#: """ ... """ — delimitadores de 3 aspas.
     if (c === '"' && next === '"' && text[i + 2] === '"') {
       const end = text.indexOf('"""', i + 3);
@@ -137,6 +158,82 @@ export function stripComments(text, { blankStrings = false, report = null } = {}
   return out.join('');
 }
 
+/** Índice logo após a crase que fecha o template aberto em `start`, ou -1. */
+function templateEnd(text, start) {
+  let j = start + 1;
+  while (j < text.length) {
+    if (text[j] === '\\') { j += 2; continue; }
+    if (text[j] === '`') return j + 1;
+    if (text[j] === '$' && text[j + 1] === '{') { j = holeEnd(text, j + 2); continue; }
+    j += 1;
+  }
+  return -1;
+}
+
+const REGEX_AFTER_WORD = new Set([
+  'return', 'typeof', 'case', 'do', 'else', 'in', 'of', 'new', 'delete', 'void',
+  'throw', 'instanceof', 'yield', 'await',
+]);
+
+/**
+ * Uma `/` abre regex, e não divisão, quando o que vem antes não é um valor: o
+ * mesmo critério de contexto dos tokenizers de JS. `out` já tem os comentários
+ * apagados, então o caractere anterior é código. Sem `<`: em TSX, `</b>` é tag.
+ */
+function regexMayStart(out, i) {
+  let k = i - 1;
+  while (k >= 0 && /\s/.test(out[k])) k--;
+  if (k < 0) return true;
+  if ('(,=:[!&|?{};+-*%>~^'.includes(out[k])) return true;
+  if (!/[A-Za-z_$]/.test(out[k])) return false;
+  let w = k;
+  while (w > 0 && /[\w$]/.test(out[w - 1])) w--;
+  return REGEX_AFTER_WORD.has(out.slice(w, k + 1).join(''));
+}
+
+/** Índice logo após a `/` (e as flags) que fecha a regex aberta em `start`, ou -1 se a linha acaba antes. */
+function regexEnd(text, start) {
+  let inClass = false;
+  for (let j = start + 1; j < text.length; j++) {
+    const c = text[j];
+    if (c === '\n') return -1;
+    if (c === '\\') { j++; continue; }
+    if (c === '[') inClass = true;
+    else if (c === ']') inClass = false;
+    else if (c === '/' && !inClass) {
+      let k = j + 1;
+      while (k < text.length && /[a-z]/i.test(text[k])) k++;
+      return k;
+    }
+  }
+  return -1;
+}
+
+/** Índice logo após o `}` que fecha um `${`: o código do buraco aninha chaves, strings e templates. */
+function holeEnd(text, start) {
+  let depth = 1;
+  let j = start;
+  while (j < text.length) {
+    const c = text[j];
+    if (c === '`') {
+      const end = templateEnd(text, j);
+      if (end === -1) return text.length;
+      j = end;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      j += 1;
+      while (j < text.length && text[j] !== c && text[j] !== '\n') j += text[j] === '\\' ? 2 : 1;
+      j += 1;
+      continue;
+    }
+    if (c === '{') depth += 1;
+    else if (c === '}' && --depth === 0) return j + 1;
+    j += 1;
+  }
+  return text.length;
+}
+
 /**
  * Converte JSONC em JSON: apaga comentários e vírgulas sobrando antes de `}`/`]`.
  *

package/src/lib/evaluator-report.js

@@ -93,6 +93,12 @@ const MUTATION_SECTION_RE = /^##\s+Muta[çc][õo]es\s*$/m;
  */
 const MEDIA_SECTION_RE = /^##\s+M[íi]dia\s+gerada\s*$/m;
 
+/**
+ * A seção em que o avaliador confere o checklist de tela do mockup contra a
+ * tela entregue (`morph-review` §4). Mesma disciplina: exige `##`.
+ */
+const SCREEN_CHECKLIST_SECTION_RE = /^##\s+Checklist\s+de\s+tela\s*$/gim;
+
 /**
  * As chaves reconhecidas de `**Proof-Scores:**`, uma por rubrica de prova.
  * Chave fora desta lista é IGNORADA (não vira score, não vira erro): o relatório
@@ -287,6 +293,25 @@ export function evaluatorProofState(cwd, featureName) {
   };
 }
 
+/**
+ * A seção `## Checklist de tela` do relatório, com o corpo da ÚLTIMA ocorrência
+ * — append-only outra vez: numa reavaliação a conferência nova vai para o fim.
+ * O corpo vai cru para `checklistCoverage` (`src/lib/specs/screen-checklist.js`),
+ * dono único do parser de linha do checklist.
+ *
+ * @returns {{ section: boolean, body: string }} arquivo ausente ou sem a seção:
+ *   `{ section: false, body: '' }`. Nunca lança.
+ */
+export function evaluatorScreenChecklist(cwd, featureName) {
+  const text = readReport(cwd, featureName);
+  const matches = text === null ? [] : [...text.matchAll(SCREEN_CHECKLIST_SECTION_RE)];
+  if (matches.length === 0) return { section: false, body: '' };
+  const last = matches[matches.length - 1];
+  const rest = text.slice(last.index + last[0].length);
+  const next = rest.search(/^#{1,2}\s/m);
+  return { section: true, body: next === -1 ? rest : rest.slice(0, next) };
+}
+
 /**
  * O menor Proof-Score das provas de EVIDÊNCIA — o que impõe o teto em
  * `test-coverage`.

package/src/lib/generators/handoff-generator.js

@@ -16,9 +16,9 @@
  * degrades that section, never the document.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'fs';
-import { join, resolve } from 'path';
-import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { ensureCommonExclude } from '../../../framework/hooks/shared/git-exclude.js';
 import { derivePhaseForFeature, getPendingGates } from '../../../framework/hooks/shared/state-reader.js';
 
 const PHASE_DIRS = {
@@ -236,21 +236,7 @@ const HANDOFF_EXCLUDE_PATTERN = '/.morph/**/handoff.md';
  * untracked is noise, never data loss.
  */
 function ensureHandoffExcluded(cwd) {
-  try {
-    const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
-    if (!common) return;
-    const infoDir = join(resolve(cwd, common), 'info');
-    const excludePath = join(infoDir, 'exclude');
-    const current = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
-    const present = new Set(current.split(/\r?\n/).map((l) => l.trim()));
-    if (present.has(HANDOFF_EXCLUDE_PATTERN)) return;
-    mkdirSync(infoDir, { recursive: true });
-    appendFileSync(excludePath, [
-      current && !current.endsWith('\n') ? '\n' : '',
-      present.has(HANDOFF_EXCLUDE_MARKER) ? '' : `${HANDOFF_EXCLUDE_MARKER}\n`,
-      `${HANDOFF_EXCLUDE_PATTERN}\n`,
-    ].join(''));
-  } catch { /* fail-open */ }
+  ensureCommonExclude(cwd, [HANDOFF_EXCLUDE_PATTERN], HANDOFF_EXCLUDE_MARKER);
 }
 
 /**

package/src/lib/git/default-branch.js

@@ -260,3 +260,55 @@ export function changedPathsAgainst(baseRef, cwd = process.cwd()) {
 
   return [...new Set([...tracked, ...listUntrackedFiles(cwd)])].sort();
 }
+
+/**
+ * The lines this working tree ADDED against `baseRef`, per file: the new-side
+ * line numbers of `git diff -U0`, plus every brand-new untracked file whole
+ * (the same probe as {@link changedPathsAgainst}).
+ *
+ * Measured from the merge-base, not the tip: a default branch that moved on
+ * after the feature branched must not lend its edits to the feature. `-M`
+ * keeps a moved file from reading as added. `--relative` gives paths relative
+ * to `cwd` and drops what lies outside it, the same base as the untracked
+ * listing: a project in a subfolder of the repo reads its own files.
+ *
+ * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
+ * @param {string} [cwd]
+ * @returns {Map<string, number[]|null>|null} path → added line numbers, or
+ *   `null` for a whole untracked file. `null` (not an empty map) when it cannot
+ *   tell: falsy or unresolvable ref, not a repo, diff failed.
+ */
+export function addedLinesAgainst(baseRef, cwd = process.cwd()) {
+  if (!baseRef) return null;
+  const git = (args) => execFileSync('git', args, { cwd, stdio: 'pipe', maxBuffer: 256 * 1024 * 1024 }).toString();
+
+  let diff;
+  try {
+    let base = baseRef;
+    try { base = git(['merge-base', 'HEAD', baseRef]).trim() || baseRef; } catch { /* diff against the ref itself */ }
+    diff = git(['-c', 'core.quotepath=off', 'diff', '-U0', '--no-color', '--no-ext-diff', '-M', '--relative',
+      '--src-prefix=a/', '--dst-prefix=b/', base]);
+  } catch {
+    return null;
+  }
+
+  const added = new Map();
+  let current = null;
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ ')) {
+      const target = line.slice(4).trim().replace(/^"|"$/g, '');
+      current = target.startsWith('b/') ? target.slice(2) : null;
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (!hunk || !current) continue;
+    const start = Number(hunk[1]);
+    const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
+    if (count === 0) continue;
+    const lines = added.get(current) ?? [];
+    for (let n = start; n < start + count; n++) lines.push(n);
+    added.set(current, lines);
+  }
+  for (const path of listUntrackedFiles(cwd)) added.set(path, null);
+  return added;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+
+/** 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
+ */
+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.
+    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])
+      .toString().split('\0').filter(Boolean).sort();
+    for (const rel of untracked) {
+      // Size and mtime stand in for content: hashing every untracked file of
+      // a large tree would cost more than the run the warning tries to save.
+      let stamp = 'gone';
+      try {
+        const st = statSync(join(projectPath, rel));
+        stamp = `${st.size}\0${st.mtimeMs}`;
+      } catch { /* deleted since the listing */ }
+      hash.update(`${rel}\0${stamp}\0`);
+    }
+    const config = join(projectPath, '.morph', 'config', 'config.json');
+    hash.update('\0config\0');
+    if (existsSync(config)) hash.update(readFileSync(config));
+    return hash.digest('hex');
+  } catch {
+    return null;
+  }
+}

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)',
     );
   }