forjajs 1.1.3 → 1.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,452 @@
1
+ /**
2
+ * lib/core/release.mjs — o gate do tarball.
3
+ *
4
+ * Guarda a fronteira que `health.mjs` não vê: **o repositório mente sobre o pacote**. No repo tudo
5
+ * resolve — `node_modules` tem as devDeps, todo arquivo está presente, o `cwd` é a raiz. Nada disso
6
+ * vale para quem roda `npm i -g forjajs`. Essa fronteira já cedeu três vezes (SPEC-010):
7
+ *
8
+ * ADR-0021 `better-sqlite3` como devDependency → dez comandos com ERR_MODULE_NOT_FOUND na
9
+ * instalação limpa. O `forja` sem argumentos funcionava, o que mascarava a quebra.
10
+ * v1.1.1 `otplib` e `qrcode` publicados sem jamais existirem no git — `npm publish` empacota o
11
+ * disco, não o commit.
12
+ * v1.1.3 `docs/dashboard.md` e o script publicados sem a pasta `dashboard/`.
13
+ *
14
+ * O princípio que organiza tudo aqui: **grep não prova ausência; instalação prova.** Por isso o
15
+ * gate empacota e instala de verdade, e por isso ele é lento — e tudo bem ser lento, porque roda
16
+ * antes de publicar, não a cada commit.
17
+ *
18
+ * O runner é o de `checks.mjs`, o mesmo do doctor. Uma máquina, duas fronteiras.
19
+ */
20
+
21
+ import { execFileSync } from 'node:child_process';
22
+ import fs from 'node:fs';
23
+ import os from 'node:os';
24
+ import path from 'node:path';
25
+ import { fileURLToPath } from 'node:url';
26
+
27
+ import { runChecks as run, worstStatus, stripTemplateLiterals } from './checks.mjs';
28
+ import { COMMANDS } from './registry.mjs';
29
+
30
+ export { worstStatus };
31
+
32
+ const __filename = fileURLToPath(import.meta.url);
33
+ const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
34
+
35
+ /** Assinaturas de tarball quebrado. Exit code não serve — ver `smokeCommands`. */
36
+ const LOADER_ERRORS = /ERR_MODULE_NOT_FOUND|ERR_DLOPEN_FAILED|Cannot find module|ERR_PACKAGE_PATH_NOT_EXPORTED/;
37
+
38
+ function git(args, cwd = repoRoot) {
39
+ return execFileSync('git', args, { cwd, encoding: 'utf8' });
40
+ }
41
+
42
+ /**
43
+ * Empacota o repo e instala o tarball num diretório temporário isolado.
44
+ *
45
+ * Isolamento importa: um gate que enxerga o `node_modules` do repo mente verde. É justamente o
46
+ * `NODE_PATH` herdado e o `node_modules` vizinho que fariam um `import` quebrado resolver mesmo
47
+ * assim — e a quebra só apareceria na máquina do usuário.
48
+ *
49
+ * Limpa o temporário **sempre**, inclusive quando o callback lança.
50
+ *
51
+ * @param {(ctx: { pkgDir: string, installDir: string }) => Promise<T>|T} fn
52
+ * @returns {Promise<T>}
53
+ */
54
+ export async function withCleanInstall(fn, { root = repoRoot } = {}) {
55
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-release-'));
56
+
57
+ // Isolamento de verdade — e ele vaza por onde não se espera.
58
+ //
59
+ // `NODE_PATH` é o óbvio. O traiçoeiro é o `npm_config_*`: quando o gate roda de dentro de um
60
+ // script npm (e o `prepublishOnly` é exatamente isso), o npm injeta dezenas dessas variáveis no
61
+ // ambiente. Elas carregam o `local_prefix` do repo e, sob `npm publish --dry-run`, um
62
+ // `npm_config_dry_run=true` que faz o `npm install` interno não instalar nada.
63
+ //
64
+ // Sem esta limpeza, o gate passa localmente e quebra justamente no `prepublishOnly` — o único
65
+ // lugar onde ele precisa funcionar.
66
+ const env = { ...process.env };
67
+ delete env.NODE_PATH;
68
+ for (const key of Object.keys(env)) {
69
+ if (key.startsWith('npm_')) delete env[key];
70
+ }
71
+
72
+ const npm = (args, cwd) => {
73
+ try {
74
+ return execFileSync('npm', args, { cwd, encoding: 'utf8', env, stdio: 'pipe' });
75
+ } catch (err) {
76
+ // Engolir o stderr aqui cega o diagnóstico exatamente quando ele importa.
77
+ const saida = `${err.stdout || ''}${err.stderr || ''}`.trim();
78
+ throw new Error(`npm ${args[0]} falhou em ${cwd}:\n${saida || err.message}`);
79
+ }
80
+ };
81
+
82
+ try {
83
+ const tgz = npm(['pack', '--silent', '--pack-destination', dir], root)
84
+ .trim()
85
+ .split('\n')
86
+ .pop();
87
+
88
+ npm(['init', '-y'], dir);
89
+ npm(['install', path.join(dir, tgz)], dir);
90
+
91
+ const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
92
+ const pkgDir = path.join(dir, 'node_modules', pkg.name);
93
+
94
+ return await fn({ pkgDir, installDir: dir });
95
+ } finally {
96
+ fs.rmSync(dir, { recursive: true, force: true });
97
+ }
98
+ }
99
+
100
+ // ---------------------------------------------------------------------------
101
+ // Checks
102
+ // ---------------------------------------------------------------------------
103
+
104
+ /**
105
+ * A falha da v1.1.1, e a única que nenhuma instalação pega: `npm publish` empacota o **disco**, não
106
+ * o commit. Um `npm install` casual entre a auditoria e o publish reescreve o `package.json`, e foi
107
+ * assim que `otplib` e `qrcode` chegaram ao npm sem jamais existirem no git.
108
+ *
109
+ * Severidade depende do modo: sob `--publish` é fatal; em dev é aviso — um gate que reprova todo
110
+ * desenvolvimento local é um gate que se contorna (a lição que o CI nos deu na SPEC-009).
111
+ */
112
+ const treeClean = {
113
+ id: 'tree-clean',
114
+ title: 'árvore limpa (o tarball é o commit)',
115
+ severity: 'critical',
116
+ probe(env) {
117
+ let dirty;
118
+ try {
119
+ dirty = git(['status', '--short'], env.root).trim();
120
+ } catch {
121
+ return { status: 'skipped', detail: 'fora de um repositório git', fix: null };
122
+ }
123
+
124
+ if (!dirty) return { status: 'ok', detail: 'nada não commitado', fix: null };
125
+
126
+ const n = dirty.split('\n').length;
127
+ const detalhe = `${n} arquivo(s) não commitado(s) — o tarball não corresponde a nenhum commit`;
128
+
129
+ return env.publish
130
+ ? { status: 'fail', detail: `${detalhe}. npm publish empacota o disco, não o commit`, fix: 'git commit' }
131
+ : { status: 'warn', detail: `${detalhe}. Ok para smoke; não para publicar`, fix: null };
132
+ },
133
+ };
134
+
135
+ /** Se o pacote não instala, todo o resto é irrelevante — daí todos dependerem deste. */
136
+ const install = {
137
+ id: 'install',
138
+ title: 'o pacote instala do zero',
139
+ severity: 'critical',
140
+ probe(env) {
141
+ return env.pkgDir && env.fs.existsSync(env.pkgDir)
142
+ ? { status: 'ok', detail: `instalado em ${path.basename(env.installDir)}`, fix: null }
143
+ : { status: 'fail', detail: 'o tarball não instalou', fix: 'npm pack && npm i <tgz> — investigue o erro' };
144
+ },
145
+ };
146
+
147
+ /**
148
+ * Todo comando anunciado pelo registry precisa existir no tarball. É o bug da v1.1.3, generalizado:
149
+ * `npm run dashboard` era publicado, a pasta `dashboard/` não.
150
+ */
151
+ const registryScripts = {
152
+ id: 'registry-scripts',
153
+ title: 'todo comando do registry existe no tarball',
154
+ severity: 'critical',
155
+ dependsOn: 'install',
156
+ probe(env) {
157
+ const faltando = [];
158
+ let total = 0;
159
+
160
+ for (const [name, def] of Object.entries(env.registry)) {
161
+ const rel = def.node || def.script;
162
+ if (!rel) continue;
163
+ total += 1;
164
+ if (!env.fs.existsSync(path.join(env.pkgDir, rel))) faltando.push(`${name} → ${rel}`);
165
+ }
166
+
167
+ if (faltando.length) {
168
+ return {
169
+ status: 'fail',
170
+ detail: `${faltando.length} comando(s) sem script no tarball: ${faltando.join(', ')}`,
171
+ fix: 'adicione o path ao files[] do package.json',
172
+ };
173
+ }
174
+
175
+ return { status: 'ok', detail: `${total}/${total} comandos com script presente`, fix: null };
176
+ },
177
+ };
178
+
179
+ /**
180
+ * O **código executável** do pacote — `bin/`, `lib/`, `scripts/`. Nada mais.
181
+ *
182
+ * `boilerplates/` também é publicado e também é `.js`, mas é **conteúdo**: templates copiados para
183
+ * o projeto gerado. O `next.config.js` de um boilerplate importa `next` — que é dependência do
184
+ * projeto do usuário, não do Forja. Varrer essas pastas faz o gate exigir `npm i -S next` no
185
+ * framework, o que é absurdo (observado na primeira execução real do gate).
186
+ *
187
+ * Mesmo princípio de `stripTemplateLiterals`, um nível acima: o que o Forja *escreve* não é o que
188
+ * o Forja *executa*.
189
+ */
190
+ const CODE_DIRS = ['bin', 'lib', 'scripts'];
191
+
192
+ function publishedSources(env) {
193
+ const out = [];
194
+
195
+ for (const dir of CODE_DIRS) {
196
+ const full = path.join(env.pkgDir, dir);
197
+ if (env.fs.existsSync(full)) walkDir(env, full, out);
198
+ }
199
+
200
+ return out;
201
+ }
202
+
203
+ function walkDir(env, dir, out) {
204
+ let entries;
205
+ try {
206
+ entries = env.fs.readdirSync(dir);
207
+ } catch {
208
+ return;
209
+ }
210
+ for (const entry of entries) {
211
+ const p = path.join(dir, entry);
212
+ let st;
213
+ try {
214
+ st = env.fs.statSync(p);
215
+ } catch {
216
+ continue;
217
+ }
218
+ if (st.isDirectory()) {
219
+ if (entry !== 'node_modules') walkDir(env, p, out);
220
+ } else if (/\.(mjs|js)$/.test(entry)) {
221
+ out.push(p);
222
+ }
223
+ }
224
+ }
225
+
226
+ const IMPORT_RE = /(?:^|\s)(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]|(?:^|\s)import\s*['"]([^'"]+)['"]/gm;
227
+
228
+ function importsOf(env, file) {
229
+ const src = stripTemplateLiterals(env.fs.readFileSync(file, 'utf8'));
230
+ const out = [];
231
+ for (const m of src.matchAll(IMPORT_RE)) out.push(m[1] || m[2]);
232
+ return out;
233
+ }
234
+
235
+ /** Pacote npm (não builtin, não relativo). `@scope/x/sub` → `@scope/x`. */
236
+ function packageName(specifier) {
237
+ if (!specifier || specifier.startsWith('.') || specifier.startsWith('/')) return null;
238
+ if (specifier.startsWith('node:')) return null;
239
+ const parts = specifier.split('/');
240
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
241
+ }
242
+
243
+ /** Import relativo que não resolve dentro do tarball = arquivo fora do `files[]` (bug da v1.1.3). */
244
+ const importsResolve = {
245
+ id: 'imports-resolve',
246
+ title: 'imports relativos resolvem dentro do tarball',
247
+ severity: 'critical',
248
+ dependsOn: 'install',
249
+ probe(env) {
250
+ const quebrados = [];
251
+
252
+ for (const file of publishedSources(env)) {
253
+ for (const spec of importsOf(env, file)) {
254
+ if (!spec?.startsWith('.')) continue;
255
+ const alvo = path.resolve(path.dirname(file), spec);
256
+ const existe = env.fs.existsSync(alvo)
257
+ || ['.js', '.mjs', '.json'].some((ext) => env.fs.existsSync(alvo + ext));
258
+ if (!existe) quebrados.push(`${path.relative(env.pkgDir, file)} → ${spec}`);
259
+ }
260
+ }
261
+
262
+ if (quebrados.length) {
263
+ return {
264
+ status: 'fail',
265
+ detail: `${quebrados.length} import(s) sem destino no tarball: ${quebrados.slice(0, 3).join('; ')}`,
266
+ fix: 'adicione o arquivo ao files[] do package.json',
267
+ };
268
+ }
269
+
270
+ return { status: 'ok', detail: 'todo import relativo resolve', fix: null };
271
+ },
272
+ };
273
+
274
+ /** O bug do ADR-0021 §2: importado por script publicado, mas declarado como devDependency. */
275
+ const depsDeclared = {
276
+ id: 'deps-declared',
277
+ title: 'todo import externo está em dependencies',
278
+ severity: 'critical',
279
+ dependsOn: 'install',
280
+ probe(env) {
281
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
282
+ const deps = new Set(Object.keys(pkg.dependencies || {}));
283
+ const faltando = new Map();
284
+
285
+ for (const file of publishedSources(env)) {
286
+ for (const spec of importsOf(env, file)) {
287
+ const nome = packageName(spec);
288
+ if (!nome || deps.has(nome)) continue;
289
+ faltando.set(nome, path.relative(env.pkgDir, file));
290
+ }
291
+ }
292
+
293
+ if (faltando.size) {
294
+ const lista = [...faltando].map(([n, f]) => `${n} (${f})`).join(', ');
295
+ return {
296
+ status: 'fail',
297
+ detail: `importado pelo pacote mas não declarado em dependencies: ${lista}`,
298
+ fix: `npm i -S ${[...faltando.keys()].join(' ')}`,
299
+ };
300
+ }
301
+
302
+ return { status: 'ok', detail: `${deps.size} dependência(s), todas importadas por alguém`, fix: null };
303
+ },
304
+ };
305
+
306
+ /** Peso morto viaja no tarball de todo usuário. Incomoda; não quebra — por isso `warn` (D7). */
307
+ const depsUnused = {
308
+ id: 'deps-unused',
309
+ title: 'nenhuma dependency é peso morto',
310
+ severity: 'warn',
311
+ dependsOn: 'install',
312
+ probe(env) {
313
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
314
+ const deps = Object.keys(pkg.dependencies || {});
315
+ const usados = new Set();
316
+
317
+ for (const file of publishedSources(env)) {
318
+ for (const spec of importsOf(env, file)) {
319
+ const nome = packageName(spec);
320
+ if (nome) usados.add(nome);
321
+ }
322
+ }
323
+
324
+ const ociosos = deps.filter((d) => !usados.has(d));
325
+ if (ociosos.length) {
326
+ return {
327
+ status: 'warn',
328
+ detail: `declarada(s) e nunca importada(s): ${ociosos.join(', ')} — todo usuário baixa isso`,
329
+ fix: `npm rm ${ociosos.join(' ')}`,
330
+ };
331
+ }
332
+
333
+ return { status: 'ok', detail: 'nenhuma dependência ociosa', fix: null };
334
+ },
335
+ };
336
+
337
+ /**
338
+ * O check mais importante, e o mais fácil de errar.
339
+ *
340
+ * **Executar, não listar.** O `forja` sem argumentos passa mesmo com tudo quebrado — o help não
341
+ * carrega os scripts. Foi assim que a quebra do ADR-0021 §2 se escondeu: o help funcionava, e dez
342
+ * comandos estavam mortos.
343
+ *
344
+ * **Reprovar por stderr, nunca por exit code.** Numa instalação limpa não há workspace nem
345
+ * `universal.db`; `query:universal` sai com código ≠ 0 *legitimamente*, e isso é o pacote
346
+ * funcionando. O que denuncia tarball quebrado é a assinatura do carregamento. Reprovar por exit
347
+ * code reprovaria um pacote saudável — a mesma armadilha do `memory-db` na SPEC-009, um nível
348
+ * acima.
349
+ */
350
+ const smokeCommands = {
351
+ id: 'smoke-commands',
352
+ title: 'os comandos executam de verdade',
353
+ severity: 'critical',
354
+ dependsOn: 'install',
355
+ probe(env) {
356
+ const bin = path.join(env.pkgDir, 'bin', 'forja.mjs');
357
+ const quebrados = [];
358
+
359
+ for (const args of env.smokeCommands) {
360
+ const res = env.spawn(process.execPath, [bin, ...args], { cwd: env.installDir });
361
+ const saida = `${res.stdout || ''}${res.stderr || ''}`;
362
+ if (LOADER_ERRORS.test(saida)) {
363
+ const causa = saida.match(LOADER_ERRORS)[0];
364
+ quebrados.push(`${args[0] || '(help)'}: ${causa}`);
365
+ }
366
+ }
367
+
368
+ if (quebrados.length) {
369
+ return {
370
+ status: 'fail',
371
+ detail: `comando(s) não carregam na instalação limpa: ${quebrados.join('; ')}`,
372
+ fix: 'verifique files[] e dependencies — o repo resolve, o tarball não',
373
+ };
374
+ }
375
+
376
+ return {
377
+ status: 'ok',
378
+ detail: `${env.smokeCommands.length} comando(s) executam sem erro de carregamento`,
379
+ fix: null,
380
+ };
381
+ },
382
+ };
383
+
384
+ /** @type {import('./checks.mjs').Check[]} */
385
+ export const RELEASE_CHECKS = [
386
+ treeClean,
387
+ install,
388
+ registryScripts,
389
+ smokeCommands,
390
+ importsResolve,
391
+ depsDeclared,
392
+ depsUnused,
393
+ ];
394
+
395
+ /** Comandos sem efeito colateral. `tools:doctor` e `code:status` só leem; o help não prova nada sozinho. */
396
+ const DEFAULT_SMOKE = [[], ['tools:doctor'], ['code:status'], ['query:universal', 'teste']];
397
+
398
+ export function defaultEnv(overrides = {}) {
399
+ return {
400
+ root: repoRoot,
401
+ fs,
402
+ registry: COMMANDS,
403
+ smokeCommands: DEFAULT_SMOKE,
404
+ publish: false,
405
+ spawn: (cmd, args, opts) => {
406
+ try {
407
+ return {
408
+ stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', ...opts }),
409
+ stderr: '',
410
+ };
411
+ } catch (err) {
412
+ return { stdout: err.stdout || '', stderr: err.stderr || String(err) };
413
+ }
414
+ },
415
+ ...overrides,
416
+ };
417
+ }
418
+
419
+ /**
420
+ * Roda o gate completo: empacota, instala isolado, checa, limpa.
421
+ *
422
+ * A aprovação é **perecível** — vale para o disco naquele instante. Por isso a árvore é reconferida
423
+ * ao final: um `npm install` entre o check e o publish invalida tudo, e foi exatamente essa a causa
424
+ * da v1.1.1.
425
+ */
426
+ export async function runReleaseChecks({ publish = false, env: overrides = {} } = {}) {
427
+ const base = defaultEnv({ publish, ...overrides });
428
+
429
+ const arvoreAntes = git(['status', '--short'], base.root);
430
+
431
+ const results = await withCleanInstall(
432
+ ({ pkgDir, installDir }) => run({
433
+ checks: RELEASE_CHECKS,
434
+ env: { ...base, pkgDir, installDir },
435
+ }),
436
+ { root: base.root }
437
+ );
438
+
439
+ const arvoreDepois = git(['status', '--short'], base.root);
440
+ if (arvoreAntes !== arvoreDepois) {
441
+ results.push({
442
+ id: 'tree-stable',
443
+ title: 'a árvore não mudou durante a auditoria',
444
+ severity: 'critical',
445
+ status: 'fail',
446
+ detail: 'o disco mudou enquanto o gate rodava — este parecer está vencido',
447
+ fix: 'rode o gate de novo com a árvore parada',
448
+ });
449
+ }
450
+
451
+ return results;
452
+ }
@@ -1,16 +1,22 @@
1
1
  # Sprint Atual
2
2
 
3
3
  ## Projeto
4
- framework-root
4
+ framework-root (o repo do Forja — produtos vivem no workspace, ADR-0019)
5
5
 
6
6
  ## Objetivos
7
- - Completar itens P0/P1 do backlog com handoffs GSD registrados.
7
+ - Fechar a classe de falha "erra sem avisar" (ADR-0021) com gates executáveis, não correções pontuais.
8
8
 
9
9
  ## Itens da Sprint
10
- - [ ] P0: Inventario multiempresa + CRUD de ativos (RICE 24.0)
11
- - [ ] P0: Monitoramento de disponibilidade + status (RICE 15.8)
12
- - [ ] P1: Alertas (regras + notificacao) (RICE 14.0)
13
- - [ ] P1: Storage/NAS (capacidade/uso) (RICE 3.0)
10
+ - [x] SPEC-009 — Doctor do núcleo (`specs/doctor-do-nucleo/`, ADR-0023)
11
+ `tools:doctor` deixa de auditar só ferramentas opcionais e passa a ser gate do núcleo:
12
+ ABI nativa, memória, workspace, deps de runtime, `.mcp.json`. Exit 1 no que trava o fluxo.
13
+ - [x] `spec:new` mantém a allow-list do `.gitignore` — spec nova do framework nascia invisível ao git.
14
+
15
+ ## Próximos candidatos (sem spec ainda)
16
+ - `release-auditor` consumindo `lib/core/health.mjs` em vez de heurística própria — é a terceira
17
+ superfície prevista no ADR-0023 e a única que ainda não migrou.
18
+ - Checks de núcleo no CI (`tools:doctor` como step), fechando o ciclo: hoje o CI roda os testes,
19
+ mas não o gate.
14
20
 
15
21
  ## Ritual CLI
16
22
  - Planejar: npm run gsd:plan -- <slug> "<objetivo>"
@@ -18,4 +24,4 @@ framework-root
18
24
  - Handoff plan: npm run gsd:handoff -- plan <slug>
19
25
  - Handoff implement: npm run gsd:handoff -- implement <slug>
20
26
  - Validar: npm run gsd:check -- <slug>
21
- - Governanca: npm run project:check
27
+ - Governança: npm run project:check && npm run tools:doctor
@@ -0,0 +1,114 @@
1
+ # ADR-0023: Doctor como gate do núcleo, não relatório de ferramentas
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-13
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: harness, governance, memory, hooks, diagnostics
7
+
8
+ ## Contexto
9
+
10
+ O ADR-0021 nomeou uma classe de falha do framework: erros que **erram sem avisar** — nenhum teste
11
+ quebra, nada aparece no `git status`, e o resultado é trabalho errado com aparência de trabalho
12
+ certo. Quatro casos foram corrigidos individualmente.
13
+
14
+ Em 2026-07-13 apareceu o quinto, e ele revelou por que corrigir caso a caso não fecha a classe.
15
+
16
+ Com o `better-sqlite3` compilado contra o ABI do Node 24 num runtime Node 26, a memória universal
17
+ morreu inteira: `query:universal`, `sync:universal`, `context:smart`, `agent:route`,
18
+ `memory:compress` e `project:dashboard`, todos inoperantes. A aposta nº 1 da visão — *"memória que
19
+ sobrevive"* — simplesmente não existia. As três superfícies de diagnóstico reagiram assim:
20
+
21
+ | Superfície | O que fez |
22
+ |---|---|
23
+ | `tools:doctor` | Reportou `2/5 ferramentas disponíveis` e saiu com **exit 0** |
24
+ | `SessionStart` | Detectou, mas prescreveu `npm install` — que **não** recompila binário nativo |
25
+ | `npm test` | Stack trace cru de `ERR_DLOPEN_FAILED` |
26
+
27
+ A correção real era `npm rebuild better-sqlite3`.
28
+
29
+ Dois problemas estruturais, não um bug:
30
+
31
+ 1. **O doctor auditava o que não importa.** Ele checava cinco ferramentas *opcionais*, sobre as
32
+ quais ele mesmo declarava: *"o fluxo nunca trava por elas"*. Era cego para tudo que trava. Um
33
+ raio-x que só olha o que não pode quebrar.
34
+ 2. **Cada superfície tinha heurística própria.** O hook resolvia a saúde da memória com um
35
+ `catch { return null }` que colapsava *sem `node_modules`*, *ABI incompatível* e *banco ausente*
36
+ no mesmo `null` — e então prescrevia a correção de apenas uma das três. Um operador seguindo a
37
+ instrução do próprio framework não consertaria nada, e concluiria que o problema era outro.
38
+ Uma prescrição errada é pior que silêncio: consome o tempo do operador e ainda desvia a
39
+ investigação.
40
+
41
+ ## Decisão
42
+
43
+ **O doctor passa a ser o gate do núcleo. As três superfícies passam a ler a mesma fonte.**
44
+
45
+ - **`lib/core/health.mjs`** — os checks viram **dados** (`CHECKS[]`), com um runner que os executa
46
+ e devolve resultados estruturados. `tools:doctor`, `SessionStart` e (futuramente) o
47
+ `release-auditor` são apenas apresentação. Nenhuma superfície volta a ter heurística local.
48
+ - **Probes classificam a causa; o runner nunca colapsa em booleano.** `ERR_DLOPEN_FAILED` →
49
+ `npm rebuild better-sqlite3`. `ERR_MODULE_NOT_FOUND` → `npm install`. Banco ausente →
50
+ `npm run sync:universal`. Causas distintas, correções distintas.
51
+ - **Cascata via `dependsOn`.** Um check cuja dependência falhou é `skipped`, não `fail`. Com o ABI
52
+ quebrado, os checks de memória não têm o que observar; reportá-los como falha multiplicaria uma
53
+ causa em três linhas vermelhas e esconderia a raiz. **Uma causa, uma linha vermelha.**
54
+ - **Dois contratos de exit code.** Núcleo crítico quebrado → `exit 1`. Ferramenta opcional ausente
55
+ → `exit 0`, preservando o ADR-0018 à risca. Só `critical` trava: `workspace` ausente e Node fora
56
+ do `engines` são avisos, porque não impedem trabalho.
57
+ - **Ausente ≠ quebrado.** Num clone novo — ou num CI — a memória simplesmente nunca foi indexada.
58
+ Isso é o ponto de partida de qualquer instalação, não uma falha, e um comando resolve. `memory-db`
59
+ distingue *não indexado* (aviso) de *existe mas não abre* (crítico). A primeira versão tratava os
60
+ dois como crítico e o CI reprovou de imediato: um gate que reprova todo mundo no primeiro dia é um
61
+ gate em que ninguém confia.
62
+ - **`scope: repo | runtime`.** `runtime-deps` e `mcp-json` — que convertem em gate executável dois
63
+ invariantes que o ADR-0021 corrigiu à mão — só rodam dentro do repo do framework. Numa instalação
64
+ `npm i -g forjajs` não há `devDependencies` nem `.mcp.json`, e rodá-los produziria falso positivo
65
+ crítico na máquina do usuário final.
66
+ - **`spec:new` mantém a allow-list do `.gitignore`.** Descoberto durante a implementação: `/specs/*`
67
+ é ignorado e as specs do framework entram por lista manual, então **toda spec nova nascia
68
+ invisível ao git** — inclusive a desta ADR. Aplicando o princípio do próprio ADR-0021 ("mover a
69
+ aplicação das regras do texto para o harness"), o comando passa a manter a lista.
70
+
71
+ ## Alternativas consideradas
72
+
73
+ - **Melhorar só a mensagem do hook** — rejeitada: produziria uma prescrição *genérica*, e o
74
+ problema foi exatamente uma prescrição genérica aplicada a um caso específico. A causa era o
75
+ `catch` que apagava a informação, não o texto.
76
+ - **Doctor com `--fix` que roda `npm rebuild` sozinho** — rejeitada: executar comandos de build sem
77
+ consentimento é a classe de risco oposta à que este ADR fecha. O doctor diagnostica e prescreve.
78
+ - **Fazer o índice defasado reprovar (`critical`)** — rejeitada: um gate que trava por aquilo que
79
+ não impede trabalho é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
80
+ - **Check `spec-allowlist` avisando que a spec está fora do `.gitignore`** — rejeitada em favor de
81
+ o `spec:new` manter a lista: trocaria uma falha silenciosa por um lembrete recorrente. Eliminar a
82
+ classe de erro é melhor que reportá-la.
83
+ - **Um novo comando (`core:doctor`) separado** — rejeitada: dois doctores é como se chega a duas
84
+ verdades divergentes sobre o mesmo sistema, que é precisamente o defeito que este ADR corrige.
85
+
86
+ ## Consequências
87
+
88
+ **Positivas**:
89
+ - A quebra do núcleo aparece no **primeiro** comando executado, com a correção certa ao lado — não
90
+ num sintoma indireto trinta minutos depois.
91
+ - Os invariantes do ADR-0021 ganham cobertura executável. Regressão em `.mcp.json` ou nas deps de
92
+ runtime passa a reprovar o gate, em vez de reaparecer em produção.
93
+ - Uma só definição de "saudável". O hook e o doctor não podem mais divergir, porque leem a mesma
94
+ lista.
95
+ - Check novo = entrada nova em `CHECKS[]`, e as três superfícies o ganham de graça.
96
+
97
+ **Negativas / Trade-offs**:
98
+ - `tools:doctor` pode agora **reprovar** (exit 1). Um ambiente já quebrado passa a falhar
99
+ explicitamente onde antes passava calado — é o objetivo, mas muda o contrato de quem o usasse em
100
+ script.
101
+ - `runtime-deps` usa parser estático conservador: import dinâmico não conta. Trocamos cobertura por
102
+ ausência de falso positivo, deliberadamente — um crítico que mente é pior que um warning honesto.
103
+ - O `SessionStart` ganhou uma dependência a mais no caminho quente. Mitigado por rodar só
104
+ `scope: 'runtime'` e nunca lançar: se a própria lib de health não carregar, o hook segue com o
105
+ resto do briefing.
106
+
107
+ ## Rastreamento
108
+
109
+ - Implementação: `lib/core/health.mjs`, `scripts/tools-doctor.mjs`, `scripts/hook-session-start.mjs`,
110
+ `scripts/spec-cli.mjs`, `test/health.test.js`
111
+ - Spec: `specs/doctor-do-nucleo/` (SPEC-009)
112
+ - ADRs relacionadas: ADR-0018 (ferramentas de processo — estendido), ADR-0021 (guardrails de
113
+ harness — a classe de falha que este fecha), ADR-0020 (core/registry), ADR-0009 (economia de
114
+ tokens: `query:universal` é o primeiro passo, e índice defasado o corrompe em silêncio)