@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

package/framework/templates/feature/decisions.md

@@ -1,122 +1,124 @@
-# Architecture Decision Records - {{titleCase FEATURE_NAME}}
-
-## ADR-001: {Decision Title}
-
-**Date:** {{DATE}}
-**Status:** Proposed | Accepted | Deprecated | Superseded
-**Deciders:** MORPH Agents, Developer
-
-### Context
-
-{Describe the context and problem that led to this decision}
-
-### Decision
-
-{Describe the decision made}
-
-### Consequences
-
-**Pros:**
-- {Positive consequence 1}
-- {Positive consequence 2}
-
-**Cons:**
-- {Negative consequence 1}
-
-**Risks:**
-- {Identified risk}
-
-### Alternatives Considered
-
-#### Option A: {Name}
-- Pros: {advantages}
-- Cons: {disadvantages}
-- **Rejected because:** {reason}
-
-#### Option B: {Name}
-- Pros: {advantages}
-- Cons: {disadvantages}
-- **Rejected because:** {reason}
-
----
-
-{{#if (eq STACK "nextjs-neon")}}
-## ADR-002: Database Access Strategy
-
-**Date:** {{DATE}}
-**Status:** Accepted
-
-### Context
-
-Need to decide how the .NET API accesses Neon PostgreSQL.
-
-### Decision
-
-Use Dapper with Npgsql for direct SQL queries. No EF Core.
-
-### Consequences
-
-**Pros:**
-- Full control over SQL queries
-- Better performance (no ORM overhead)
-- Direct access to PostgreSQL features (jsonb, pgvector, functions)
-- RLS policies apply naturally through connection
-
-**Cons:**
-- No automatic migrations (use Neon CLI / dotnet ef instead)
-- Manual SQL query writing
-- No change tracking
-
----
-
-## ADR-003: Auth Strategy
-
-**Date:** {{DATE}}
-**Status:** Accepted
-
-### Context
-
-Need authentication for both Next.js frontend and .NET API.
-
-### Decision
-
-Use Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
-
-### Consequences
-
-**Pros:**
-- Auth data in same database — no external provider, no sync delays
-- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
-- Built-in social login, email/password via @neondatabase/auth SDK
-- Branch isolation — each Neon branch gets isolated auth data
-- No webhooks needed — query neon_auth schema directly
-
-**Cons:**
-- Neon Auth is currently in Beta
-- JWT must be forwarded to .NET API for backend auth
-{{/if}}
-
----
-
-## Template for New ADRs
-
-```markdown
-## ADR-XXX: {Title}
-
-**Date:**
-**Status:** Proposed | Accepted | Deprecated | Superseded
-
-### Context
-{Why is this decision needed?}
-
-### Decision
-{What was decided?}
-
-### Consequences
-**Pros:** {list}
-**Cons:** {list}
-```
-
----
-
-*Generated by MORPH Framework*
+# Architecture Decision Records - {{titleCase FEATURE_NAME}}
+
+## ADR-001: {Decision Title}
+
+**Date:** {{DATE}}
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Deciders:** MORPH Agents, Developer
+**Alcance:** feature
+
+### Context
+
+{Describe the context and problem that led to this decision}
+
+### Decision
+
+{Describe the decision made}
+
+### Consequences
+
+**Pros:**
+- {Positive consequence 1}
+- {Positive consequence 2}
+
+**Cons:**
+- {Negative consequence 1}
+
+**Risks:**
+- {Identified risk}
+
+### Alternatives Considered
+
+#### Option A: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+#### Option B: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+---
+
+{{#if (eq STACK "nextjs-neon")}}
+## ADR-002: Database Access Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need to decide how the .NET API accesses Neon PostgreSQL.
+
+### Decision
+
+Use Dapper with Npgsql for direct SQL queries. No EF Core.
+
+### Consequences
+
+**Pros:**
+- Full control over SQL queries
+- Better performance (no ORM overhead)
+- Direct access to PostgreSQL features (jsonb, pgvector, functions)
+- RLS policies apply naturally through connection
+
+**Cons:**
+- No automatic migrations (use Neon CLI / dotnet ef instead)
+- Manual SQL query writing
+- No change tracking
+
+---
+
+## ADR-003: Auth Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need authentication for both Next.js frontend and .NET API.
+
+### Decision
+
+Use Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
+
+### Consequences
+
+**Pros:**
+- Auth data in same database — no external provider, no sync delays
+- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
+- Built-in social login, email/password via @neondatabase/auth SDK
+- Branch isolation — each Neon branch gets isolated auth data
+- No webhooks needed — query neon_auth schema directly
+
+**Cons:**
+- Neon Auth is currently in Beta
+- JWT must be forwarded to .NET API for backend auth
+{{/if}}
+
+---
+
+## Template for New ADRs
+
+```markdown
+## ADR-XXX: {Title}
+
+**Date:**
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Alcance:** feature | projeto — `projeto` when the rule holds beyond this feature: `morph-spec finish` copies it to `.morph/specs/adrs/`, the folder brainstorming and plan read instead of archived decisions.md
+
+### Context
+{Why is this decision needed?}
+
+### Decision
+{What was decided?}
+
+### Consequences
+**Pros:** {list}
+**Cons:** {list}
+```
+
+---
+
+*Generated by MORPH Framework*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.37.0",
+  "version": "8.38.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/graph/affected.js

@@ -9,7 +9,7 @@
  * @module graph-affected
  */
 import chalk from 'chalk';
-import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
+import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
 import { buildIndex, resolveLabel, affected } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob — o grafo é um subconjunto estrito do grep, então cair para grep não perde recall.';
@@ -79,11 +79,12 @@ export async function graphAffectedCommand(symbol, options = {}) {
   console.log(chalk.green(`\n✅ ${symbol} — ${consumers.length} consumidor(es)`));
   console.log(chalk.gray(`   declarado em ${resolved.node.source_file}`));
   if (freshness.state === 'stale') {
-    console.log(chalk.yellow('   ⚠ grafo stale (o rebuild do hook é assíncrono) — confirme no código antes de agir'));
+    console.log(chalk.yellow(`   ⚠ grafo stale, confirme no código antes de agir — ${describeStale(projectPath, freshness)}`));
   }
   for (const c of consumers) {
     const loc = c.source_location ? `:${c.source_location}` : '';
-    console.log(`   ${chalk.cyan(c.relation.padEnd(14))} ${c.source_file}${loc}  ${chalk.gray(c.label)}`);
+    const test = c.test ? chalk.gray(' [teste]') : '';
+    console.log(`   ${chalk.cyan(c.relation.padEnd(14))} ${c.source_file}${loc}  ${chalk.gray(c.label)}${test}`);
   }
   console.log('');
 }

package/src/commands/graph/build.js

@@ -7,12 +7,20 @@
  * @module graph-build
  */
 import chalk from 'chalk';
-import { spawnSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { GRAPHIFY_BIN, GRAPHIFY_VERSION, detectGraphifyVersion } from '../../lib/graph/graphify-runtime.js';
+import { GRAPHIFY_PACKAGE, GRAPHIFY_VERSION } from '../../lib/graph/graphify-runtime.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
-import { writeGraphifyignore } from '../../lib/graph/graphifyignore.js';
+import {
+  buildGraphifyignore, writeGraphifyignore, describeOutdatedIgnore,
+} from '../../lib/graph/graphifyignore.js';
+import {
+  acquireRefreshLock, isPrimaryTree, readRefreshLock, releaseRefreshLock, resolveGraphify, runGraphify,
+} from '../../../framework/hooks/shared/graph-refresh.js';
+import { isSecondaryWorktree } from '../../../framework/hooks/shared/git-paths.js';
+import {
+  TEMP_IGNORE_MARKER, ignoreRulesHash, ignoreTextOf, isTemporaryIgnore, readHead, recordRefreshRun,
+} from '../../../framework/hooks/shared/graph-freshness.js';
 import { resolveGraphPath } from '../../lib/graph/graph-loader.js';
 
 function readProjectTags(projectPath) {
@@ -25,6 +33,44 @@ function readProjectTags(projectPath) {
   }
 }
 
+/**
+ * O `.graphifyignore` com que o graphify vai rodar.
+ *
+ * Na raiz: escrito ou migrado (writeGraphifyignore). Numa worktree o arquivo é
+ * do checkout e nunca é reescrito — seria uma mudança na branch da feature.
+ * Ausente ali (a raiz ainda não o versionou), as regras — as da raiz
+ * (`ignoreTextOf`), ou as geradas — entram só durante a rodada e saem depois
+ * (`cleanup`): um `?? .graphifyignore` deixado na worktree faz o `finish` e
+ * o `worktree remove --if-clean` recusarem com worktree-dirty (medido), e pôr
+ * o arquivo no exclude do common dir esconderia também o da raiz. O arquivo leva
+ * `TEMP_IGNORE_MARKER` na 1ª linha: se este processo morrer antes do
+ * `cleanup`, a sobra é reconhecida pelo conteúdo — a próxima rodada a reusa e o
+ * `finish` a apaga (`dropLeftoverIgnore`). O graphify não herda o da raiz: o
+ * ignore dele para na raiz de VCS mais próxima, que numa worktree é ela mesma
+ * (detect.py `_load_graphifyignore`).
+ *
+ * @param {string} projectPath
+ * @param {string[]} tags
+ * @returns {{written: boolean, migrated?: boolean, outdated?: object, temporary?: boolean, path: string, cleanup: () => void}}
+ */
+function prepareIgnore(projectPath, tags) {
+  const none = () => {};
+  if (!isSecondaryWorktree(projectPath)) return { ...writeGraphifyignore(projectPath, tags), cleanup: none };
+  const path = join(projectPath, '.graphifyignore');
+  if (existsSync(path) && !isTemporaryIgnore(readFileSync(path, 'utf-8'))) {
+    const preview = writeGraphifyignore(projectPath, tags, { fx: { writeFile: none } });
+    return { written: false, path, ...(preview.outdated ? { outdated: preview.outdated } : {}), cleanup: none };
+  }
+  const content = ignoreTextOf(projectPath) ?? buildGraphifyignore(tags);
+  writeFileSync(path, `${TEMP_IGNORE_MARKER}\n${content.replace(/^/, '')}`, 'utf-8');
+  return {
+    written: false,
+    temporary: true,
+    path,
+    cleanup: () => { try { unlinkSync(path); } catch { /* já saiu */ } },
+  };
+}
+
 /**
  * @param {{path?: string, json?: boolean, refresh?: boolean}} [options]
  */
@@ -32,8 +78,10 @@ export async function graphBuildCommand(options = {}) {
   const projectPath = options.path || process.cwd();
   const refresh = options.refresh === true;
 
-  if (!detectGraphifyVersion()) {
-    const hint = `graphify não está no PATH. Instale com: uv tool install ${'graphifyy'}==${GRAPHIFY_VERSION}`;
+  // O mesmo resolvedor do refresh em background: no win32 um shim `.cmd` só
+  // é achado pelo shell, e os dois caminhos precisam ver o mesmo binário.
+  if (!resolveGraphify(process.env)) {
+    const hint = `graphify não está no PATH. Instale com: uv tool install ${GRAPHIFY_PACKAGE}==${GRAPHIFY_VERSION}`;
     const payload = { ok: false, reason: 'graphify-unavailable', hint };
     if (options.json) {
       console.log(JSON.stringify(payload, null, 2));
@@ -47,7 +95,33 @@ export async function graphBuildCommand(options = {}) {
 
   // O ignore precisa existir ANTES da extração, senão o grafo nasce com o
   // ruído que a ADR-004 existe para tirar.
-  writeGraphifyignore(projectPath, readProjectTags(projectPath));
+  const ignore = prepareIgnore(projectPath, readProjectTags(projectPath));
+  if (ignore.outdated && !options.json) {
+    console.error(chalk.yellow(`\n⚠ ${describeOutdatedIgnore(ignore.outdated)}`));
+  }
+
+  // Na árvore principal o refresh em background (framework/hooks/shared/
+  // graph-refresh.js) escreve o mesmo graph.json: dois graphify ao mesmo tempo
+  // disputam o arquivo e todos os núcleos. Numa worktree ninguém mais escreve
+  // o graph.json dela — o background só toca a raiz —, e esperar o lock da
+  // raiz ali prometeria "o grafo chega ao HEAD" sobre um refresh que nunca a
+  // alcança. Sem git não há lock, e o comando segue sozinho.
+  const primary = isPrimaryTree(projectPath);
+  const lock = primary ? acquireRefreshLock(projectPath) : null;
+  const running = primary && !lock ? readRefreshLock(projectPath) : null;
+  if (running?.live) {
+    ignore.cleanup();
+    const since = new Date(running.since).toLocaleTimeString();
+    if (options.json) {
+      console.log(JSON.stringify({
+        ok: true, running: true, since: running.since, pid: running.pid, mode: refresh ? 'refresh' : 'build',
+      }, null, 2));
+    } else {
+      console.log(chalk.yellow(`\n⟳ Refresh em background já em andamento desde ${since} (pid ${running.pid}).`));
+      console.log(chalk.gray('   O grafo chega ao HEAD quando ele terminar — confira com: morph-spec graph status\n'));
+    }
+    return;
+  }
 
   const args = refresh
     ? ['update', projectPath]
@@ -56,19 +130,33 @@ export async function graphBuildCommand(options = {}) {
   // Capturamos o output em vez de herdar o terminal porque precisamos
   // inspecioná-lo: o graphify sai 1 tanto quando quebra quanto quando não há
   // código para indexar, e essas duas coisas não podem virar a mesma mensagem.
-  const run = spawnSync(GRAPHIFY_BIN, args, {
-    cwd: projectPath,
-    encoding: 'utf-8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
+  // HEAD e regras lidos ANTES: são o que o graphify leu.
+  const head = readHead(projectPath);
+  const ignoreHash = ignoreRulesHash(projectPath);
+  let run;
+  let empty = false;
+  try {
+    run = runGraphify(projectPath, args, { timeout: null });
+    // Projeto sem código é o estado normal logo depois de um `init`, não uma
+    // falha: o graphify diz "found 0 code" / "graph is empty", sai 1 e não
+    // escreve graph.json. Tratar isso como erro faria todo init greenfield
+    // terminar em vermelho.
+    empty = run.status !== 0 && (/found 0 code/i.test(run.output) || /graph is empty/i.test(run.output));
+    // O registro é o que torna "untouched" em dia: sem ele, um refresh que não
+    // mudou a topologia deixa o carimbo no commit antigo e o grafo parece
+    // velho para sempre (framework/hooks/shared/graph-freshness.js).
+    if (!empty) {
+      recordRefreshRun(projectPath, {
+        head, exit: run.status ?? null, ignoreHash, unavailable: Boolean(run.unavailable),
+      });
+    }
+  } finally {
+    releaseRefreshLock(lock);
+    ignore.cleanup();
+  }
 
-  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+  const { output } = run;
   const ok = run.status === 0;
-  // Projeto sem código é o estado normal logo depois de um `init`, não uma
-  // falha: o graphify diz "found 0 code" / "graph is empty", sai 1 e não
-  // escreve graph.json. Tratar isso como erro faria todo init greenfield
-  // terminar em vermelho.
-  const empty = !ok && (/found 0 code/i.test(output) || /graph is empty/i.test(output));
 
   if (options.json) {
     console.log(JSON.stringify({
@@ -77,6 +165,9 @@ export async function graphBuildCommand(options = {}) {
       mode: refresh ? 'refresh' : 'build',
       path: resolveGraphPath(projectPath),
       exitCode: run.status,
+      ...(ignore.migrated ? { ignoreMigrated: true } : {}),
+      ...(ignore.outdated ? { ignoreOutdated: ignore.outdated } : {}),
+      ...(ignore.temporary ? { ignoreTemporary: true } : {}),
     }, null, 2));
   } else {
     if (!empty && output.trim()) process.stdout.write(`${output.trimEnd()}\n`);

package/src/commands/graph/explain.js

@@ -11,8 +11,8 @@
  * @module graph-explain
  */
 import chalk from 'chalk';
-import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
-import { buildIndex, resolveLabel, neighborhood } from '../../lib/graph/sanitize.js';
+import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
+import { buildIndex, resolveLabel, neighborhood, isTestPath } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob.';
 
@@ -62,6 +62,7 @@ export async function graphExplainCommand(symbol, options = {}) {
       label: node.label,
       source_file: node.source_file,
       source_location: node.source_location ?? '',
+      test: isTestPath(node.source_file),
     },
     incoming,
     outgoing,
@@ -74,16 +75,18 @@ export async function graphExplainCommand(symbol, options = {}) {
   }
 
   const nodeLoc = node.source_location ? `:${node.source_location}` : '';
-  console.log(chalk.green(`\n${node.label}`) + chalk.gray(`  ${node.source_file}${nodeLoc}`));
+  const testTag = payload.node.test ? chalk.gray('  [teste]') : '';
+  console.log(chalk.green(`\n${node.label}`) + chalk.gray(`  ${node.source_file}${nodeLoc}`) + testTag);
   if (freshness.state === 'stale') {
-    console.log(chalk.yellow('  ⚠ grafo stale — o rebuild do hook é assíncrono'));
+    console.log(chalk.yellow(`  ⚠ grafo stale — ${describeStale(projectPath, freshness)}`));
   }
 
   console.log(chalk.bold('\n  quem depende dele:'));
   for (const e of incoming) {
     const loc = e.source_location ? `:${e.source_location}` : '';
     const via = e.via === 'direct' ? '' : chalk.gray(` [${e.via}]`);
-    console.log(`   ${chalk.cyan(e.relation.padEnd(14))} ${e.source_file}${loc}${via}`);
+    const test = e.test ? chalk.gray(' [teste]') : '';
+    console.log(`   ${chalk.cyan(e.relation.padEnd(14))} ${e.source_file}${loc}${via}${test}`);
   }
   if (incoming.length === 0) console.log(chalk.gray('   (nenhum)'));
 

package/src/commands/graph/status.js

@@ -8,8 +8,10 @@
  * @module graph-status
  */
 import chalk from 'chalk';
-import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
-import { buildIndex, classifyLabel } from '../../lib/graph/sanitize.js';
+import {
+  loadGraph, getFreshness, describeStale, refreshState, staleCause,
+} from '../../lib/graph/graph-loader.js';
+import { buildIndex, classifyLabel, isTestPath } from '../../lib/graph/sanitize.js';
 import { GRAPHIFY_VERSION, detectGraphifyVersion } from '../../lib/graph/graphify-runtime.js';
 
 function summarizeSanitize(index) {
@@ -52,13 +54,16 @@ export async function graphStatusCommand(options = {}) {
 
   const { graph } = loaded;
   const freshness = getFreshness(projectPath, graph);
-  const sanitize = summarizeSanitize(buildIndex(graph));
+  const index = buildIndex(graph);
+  const sanitize = { ...summarizeSanitize(index), recoveredDispatch: index.recovered.length };
   const payload = {
     available: true,
     path: loaded.path,
     nodes: graph.nodes.length,
+    testNodes: graph.nodes.filter((n) => isTestPath(n.source_file)).length,
     links: graph.links.length,
     freshness,
+    refresh: refreshState(projectPath),
     version,
     sanitize,
   };
@@ -72,10 +77,8 @@ export async function graphStatusCommand(options = {}) {
   console.log(chalk.gray(`   ${loaded.path}`));
 
   if (freshness.state === 'stale') {
-    // O hook post-commit rebuilda em BACKGROUND: logo após um commit o grafo
-    // ainda é o do commit anterior.
-    console.log(chalk.yellow(`   ⚠ stale — construído em ${freshness.builtAtCommit.slice(0, 8)}, HEAD é ${freshness.headCommit.slice(0, 8)}`));
-    console.log(chalk.gray('     Atualize com: morph-spec graph refresh'));
+    console.log(chalk.yellow(`   ⚠ stale — ${staleCause(freshness)}`));
+    console.log(chalk.gray(`     ${describeStale(projectPath, freshness)}`));
   } else if (freshness.state === 'fresh') {
     console.log(chalk.gray(`   fresco (${freshness.headCommit.slice(0, 8)})`));
   } else {
@@ -88,6 +91,9 @@ export async function graphStatusCommand(options = {}) {
     console.log(chalk.yellow(`   ⚠ graphify ${installed} instalado; ${GRAPHIFY_VERSION} é a versão pinada e medida`));
   }
 
-  console.log(chalk.gray(`   saneamento: ${sanitize.coalescible} coalescível · ${sanitize.external} externo · ${sanitize.ambiguous} ambíguo`));
+  console.log(chalk.gray(`   saneamento: ${sanitize.coalescible} coalescível · ${sanitize.external} externo · ${sanitize.ambiguous} ambíguo · ${sanitize.recoveredDispatch} dispatch recuperado`));
+  if (payload.testNodes) {
+    console.log(chalk.gray(`   ${payload.testNodes} nós de teste (dublês, fixtures, helpers) — achados pelo explain, fora dos god nodes`));
+  }
   console.log('');
 }