forjajs 1.1.2 → 1.1.4
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.
- package/.claude/agents/governance.md +33 -10
- package/.claude/agents/release-auditor.md +44 -45
- package/CHANGELOG.md +74 -0
- package/DOC-MAP.md +2 -2
- package/README.md +2 -2
- package/docs/agent-harnesses.md +30 -3
- package/docs/token-optimization.md +28 -20
- package/lib/core/checks.mjs +138 -0
- package/lib/core/health.mjs +475 -0
- package/lib/core/registry.mjs +6 -1
- package/lib/core/release.mjs +452 -0
- package/memory/40-delivery/current-sprint.md +13 -7
- package/memory/90-decisions/0021-guardrails-de-harness.md +5 -1
- package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -0
- package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -0
- package/memory/90-decisions/0024-gate-do-tarball.md +103 -0
- package/package.json +7 -7
- package/prompts/governance-agent.md +2 -1
- package/scripts/hook-session-start.mjs +29 -39
- package/scripts/release-check.mjs +56 -0
- package/scripts/spec-cli.mjs +80 -13
- package/scripts/tools-doctor.mjs +65 -10
- package/specs/coerencia-do-sistema/spec.md +122 -0
- package/specs/doctor-do-nucleo/plan.md +165 -0
- package/specs/doctor-do-nucleo/spec.md +139 -0
- package/specs/doctor-do-nucleo/tasks.md +172 -0
- package/specs/reestruturacao-forja-v2/plan.md +1 -1
- package/specs/reestruturacao-forja-v2/spec.md +16 -12
- package/specs/reestruturacao-forja-v2/tasks.md +1 -1
- package/specs/release-gate/plan.md +174 -0
- package/specs/release-gate/spec.md +122 -0
- package/specs/release-gate/tasks.md +183 -0
- package/docs/dashboard.md +0 -102
- package/specs/agent-dashboard/plan.md +0 -165
- package/specs/agent-dashboard/spec.md +0 -89
- package/specs/agent-dashboard/tasks.md +0 -168
package/scripts/tools-doctor.mjs
CHANGED
|
@@ -1,16 +1,27 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
|
-
* tools-doctor — raio-x das ferramentas de processo (ADR-0018).
|
|
3
|
+
* tools-doctor — raio-x do núcleo (SPEC-009) e das ferramentas de processo (ADR-0018).
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* Duas seções, dois contratos distintos:
|
|
6
|
+
*
|
|
7
|
+
* Núcleo O que impede o framework de trabalhar. Falha crítica → exit 1.
|
|
8
|
+
* Ferramentas Binários opcionais que potencializam o harness. Ausência nunca trava.
|
|
9
|
+
*
|
|
10
|
+
* A separação é o ponto. Este comando auditava só as ferramentas — sobre as quais ele mesmo
|
|
11
|
+
* dizia "o fluxo nunca trava por elas" — e era cego para tudo que trava. Quando o better-sqlite3
|
|
12
|
+
* ficou com ABI de outra major do Node e a memória universal morreu inteira, o doctor reportou
|
|
13
|
+
* "2/5 ferramentas disponíveis" e saiu com 0.
|
|
14
|
+
*
|
|
15
|
+
* Diagnostica e prescreve; não conserta. Rodar `npm rebuild` sem consentimento é a classe de
|
|
16
|
+
* risco oposta à que este comando existe para fechar.
|
|
8
17
|
*
|
|
9
18
|
* Uso: node scripts/tools-doctor.mjs
|
|
10
19
|
*/
|
|
11
20
|
|
|
12
21
|
import { spawnSync } from 'node:child_process';
|
|
13
22
|
|
|
23
|
+
import { runChecks, worstStatus } from '../lib/core/health.mjs';
|
|
24
|
+
|
|
14
25
|
const TOOLS = [
|
|
15
26
|
{
|
|
16
27
|
name: 'codegraph',
|
|
@@ -56,22 +67,66 @@ function detect(cmd, args) {
|
|
|
56
67
|
return { ok: true, version };
|
|
57
68
|
}
|
|
58
69
|
|
|
59
|
-
|
|
60
|
-
|
|
70
|
+
const TAG = {
|
|
71
|
+
ok: 'OK ',
|
|
72
|
+
warn: 'AVISO',
|
|
73
|
+
fail: 'FALHA',
|
|
74
|
+
skipped: '— ',
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
function printCore(results) {
|
|
78
|
+
console.log('Núcleo — o que impede o framework de trabalhar (SPEC-009)\n');
|
|
79
|
+
|
|
80
|
+
for (const r of results) {
|
|
81
|
+
console.log(`${TAG[r.status]} ${r.id.padEnd(13)} ${r.detail}`);
|
|
82
|
+
if (r.fix) console.log(` corrigir: ${r.fix}`);
|
|
83
|
+
console.log('');
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function printTools() {
|
|
88
|
+
console.log('Ferramentas de processo — opcionais (ADR-0018)\n');
|
|
89
|
+
|
|
61
90
|
let installed = 0;
|
|
62
91
|
for (const tool of TOOLS) {
|
|
63
92
|
const [cmd, args] = tool.probe;
|
|
64
93
|
const { ok, version } = detect(cmd, args);
|
|
65
94
|
if (ok) installed += 1;
|
|
66
|
-
|
|
67
|
-
console.log(`${tag} ${tool.name.padEnd(13)} ${ok ? version : '(ausente)'}`);
|
|
95
|
+
console.log(`${ok ? TAG.ok : 'FALTA'} ${tool.name.padEnd(13)} ${ok ? version : '(ausente)'}`);
|
|
68
96
|
console.log(` papel: ${tool.role}`);
|
|
69
97
|
console.log(` gate: ${tool.gate}`);
|
|
70
98
|
if (!ok) console.log(` instalar: ${tool.install}`);
|
|
71
99
|
console.log('');
|
|
72
100
|
}
|
|
73
|
-
|
|
74
|
-
console.log(
|
|
101
|
+
|
|
102
|
+
console.log(`${installed}/${TOOLS.length} ferramentas disponíveis.`);
|
|
103
|
+
console.log('Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.\n');
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
async function main() {
|
|
107
|
+
console.log('\nForja doctor\n');
|
|
108
|
+
|
|
109
|
+
const core = await runChecks();
|
|
110
|
+
printCore(core);
|
|
111
|
+
printTools();
|
|
112
|
+
|
|
113
|
+
// Só o núcleo decide o exit code. Ferramenta ausente nunca reprova — o contrato do ADR-0018
|
|
114
|
+
// é preservado à risca.
|
|
115
|
+
const verdict = worstStatus(core);
|
|
116
|
+
|
|
117
|
+
if (verdict === 'fail') {
|
|
118
|
+
const raiz = core.filter((r) => r.status === 'fail' && r.severity === 'critical');
|
|
119
|
+
console.log(`Núcleo quebrado — ${raiz.length} ${raiz.length === 1 ? 'falha' : 'falhas'} crítica(s).`);
|
|
120
|
+
for (const r of raiz) console.log(` ${r.id}: ${r.fix || 'sem correção automática'}`);
|
|
121
|
+
process.exit(1);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
if (verdict === 'warn') {
|
|
125
|
+
console.log('Núcleo operante, com ressalvas. Nada trava o fluxo.');
|
|
126
|
+
return;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
console.log('Núcleo saudável.');
|
|
75
130
|
}
|
|
76
131
|
|
|
77
132
|
main();
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Spec: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-011
|
|
4
|
+
- **Status**: review
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-07-14
|
|
7
|
+
- **Sprint alvo**: S?
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
**Nenhum step do sistema pode ser obscuro.** O Forja é operado por agentes que leem a documentação
|
|
13
|
+
e executam o que ela manda. Quando a doc e o código divergem, o agente não erra por burrice — erra
|
|
14
|
+
por obediência.
|
|
15
|
+
|
|
16
|
+
Em 2026-07-14, uma auditoria manual encontrou:
|
|
17
|
+
|
|
18
|
+
| O que | Onde | Consequência |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `context:build`, `memory:db:reindex`, `memory:db:stats`, `cache:clear` — **quatro comandos que não existem em lugar nenhum** | `docs/token-optimization.md` | É o documento que ensina a **economia de tokens** (ADR-0009), o mecanismo central do framework. Um agente obediente executa comandos fantasma |
|
|
21
|
+
| Link para `docs/DEPLOYMENT.md`, que nunca existiu | idem | — |
|
|
22
|
+
| `tools:doctor` descrito como *"saber quais gates opcionais estão disponíveis"* | `.claude/agents/governance.md`, `prompts/governance-agent.md` | É a definição de **antes** do ADR-0023. O papel que reprova merges não sabia que o gate reprova |
|
|
23
|
+
| `release:check` desconhecido pelo Governance | idem | Criamos o gate do tarball e não contamos a quem deveria usá-lo |
|
|
24
|
+
| 2 comandos do registry **nunca mencionados** em doc, prompt, agente ou ADR | `workspace:project:check`, `memory:extract` | Existem e ninguém sabe para quê. Capacidade obscura é capacidade morta |
|
|
25
|
+
|
|
26
|
+
Nada disso quebrou um teste. Nada apareceu no `git status`. É a classe que o ADR-0021 nomeia —
|
|
27
|
+
*erra sem avisar* — aplicada à **camada de instrução**: o sistema descreve a si mesmo de forma
|
|
28
|
+
incorreta, e quem age sobre essa descrição produz trabalho errado com aparência de trabalho certo.
|
|
29
|
+
|
|
30
|
+
Os ADRs 0023 e 0024 fecharam essa classe no núcleo e no tarball. Falta a fronteira onde ela é mais
|
|
31
|
+
barata de introduzir e mais cara de perceber: **a palavra escrita.** Toda vez que um comando é
|
|
32
|
+
renomeado, um gate muda de contrato ou uma capacidade nasce, a documentação pode silenciosamente
|
|
33
|
+
passar a mentir — e hoje nada percebe.
|
|
34
|
+
|
|
35
|
+
## 2. Proposta de valor
|
|
36
|
+
|
|
37
|
+
**O sistema é obrigado a explicar a si mesmo, e a explicação é verificada.** Comando citado existe;
|
|
38
|
+
comando que existe é citado; gate que reprova diz como corrigir. Divergência entre o que o Forja
|
|
39
|
+
faz e o que ele diz que faz passa a reprovar o gate — em vez de virar armadilha para o próximo
|
|
40
|
+
agente.
|
|
41
|
+
|
|
42
|
+
## 3. User stories
|
|
43
|
+
|
|
44
|
+
- **Como** agente lendo a documentação, **quero** que todo comando citado exista de verdade,
|
|
45
|
+
**para que** eu não execute um fantasma e conclua que o ambiente está quebrado.
|
|
46
|
+
- **Como** operador, **quero** que toda capacidade do registry esteja explicada em algum lugar,
|
|
47
|
+
**para que** eu não descubra por acaso que o framework já fazia o que fui construir à mão.
|
|
48
|
+
- **Como** governança, **quero** que a mudança de contrato de um gate **quebre** a doc que o
|
|
49
|
+
descreve errado, **para que** o `tools:doctor` não fique mais um dia sendo apresentado como
|
|
50
|
+
"inventário de ferramentas opcionais" depois de virar gate.
|
|
51
|
+
- **Como** quem mantém o framework, **quero** que renomear um comando seja um ato **detectável**,
|
|
52
|
+
**para que** a renomeação não deixe um rastro de documentação morta.
|
|
53
|
+
|
|
54
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
55
|
+
|
|
56
|
+
- [ ] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
|
|
57
|
+
`forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
|
|
58
|
+
`README.md` existe no registry (ADR-0020).
|
|
59
|
+
- [ ] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
|
|
60
|
+
afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
|
|
61
|
+
dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
|
|
62
|
+
`.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
|
|
63
|
+
- [ ] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
|
|
64
|
+
mencionado em pelo menos um `.md` versionado. Hoje 2 de 42 não são.
|
|
65
|
+
- [ ] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
|
|
66
|
+
versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
|
|
67
|
+
- [ ] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
|
|
68
|
+
doctor na matriz (ADR-0024).
|
|
69
|
+
- [ ] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
|
|
70
|
+
agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
|
|
71
|
+
gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
|
|
72
|
+
- [ ] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
|
|
73
|
+
está errado" sem dizer onde é só mais um step obscuro.
|
|
74
|
+
- [ ] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
|
|
75
|
+
- [ ] AC-9: ADR-0025 registrando a decisão.
|
|
76
|
+
- [ ] AC-10: Os 2 comandos órfãos (`workspace:project:check`, `memory:extract`) são documentados —
|
|
77
|
+
ou removidos do registry, se não servirem mais. Capacidade obscura é capacidade morta.
|
|
78
|
+
|
|
79
|
+
## 5. Escopo
|
|
80
|
+
|
|
81
|
+
**Dentro**:
|
|
82
|
+
- `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
|
|
83
|
+
- `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
|
|
84
|
+
- Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
|
|
85
|
+
- Documentar os 2 comandos órfãos.
|
|
86
|
+
- ADR-0025 + testes.
|
|
87
|
+
|
|
88
|
+
**Fora** (explícito):
|
|
89
|
+
- **Lint de prosa** (estilo, ortografia, tamanho de linha). Isto é `markdownlint`, já previsto no
|
|
90
|
+
ADR-0018 como ferramenta opcional. Aqui só verificamos o que é **verificável contra o código**.
|
|
91
|
+
- Validar links **externos** (http). Rede no gate é flakiness garantida.
|
|
92
|
+
- Gerar documentação automaticamente a partir do registry. Doc gerada por máquina não explica o
|
|
93
|
+
*porquê*, e o porquê é a parte que importa — o gate cobra que exista, não escreve por você.
|
|
94
|
+
- Traduzir os docs em inglês (`token-optimization.md` está em inglês; outros em português). É dívida
|
|
95
|
+
real, mas é outra spec.
|
|
96
|
+
|
|
97
|
+
## 6. NFRs / restrições
|
|
98
|
+
|
|
99
|
+
- **Performance**: os três checks são `scope: repo` e só leem `.md` — ficam fora do `SessionStart`
|
|
100
|
+
(que roda `scope: runtime`). O doctor completo continua < 2s.
|
|
101
|
+
- **Zero falso positivo crítico**: o AC-2 é a prova de fogo. A auditoria manual acusou 11 comandos,
|
|
102
|
+
e 7 eram legítimos. Um `docs-commands` ingênuo teria "corrigido" a documentação de onboarding
|
|
103
|
+
inteira — pior que não ter check nenhum.
|
|
104
|
+
- **Compatibilidade**: aditivo. Nenhum comando existente muda de contrato.
|
|
105
|
+
|
|
106
|
+
## 7. Riscos e mitigação
|
|
107
|
+
|
|
108
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
109
|
+
|---|---|---|---|
|
|
110
|
+
| Falso positivo com comandos do projeto gerado | **A** | A | AC-2: allowlist **derivada** dos geradores, nunca manual. Já observado: 7 de 11 |
|
|
111
|
+
| Regex casa comando dentro de bloco de exemplo hipotético | M | M | Só `npm run x` / `forja x` em bloco de código. Prosa não conta |
|
|
112
|
+
| `commands-documented` vira ruído a cada comando novo | M | B | É `warn`. E documentar comando novo é o comportamento desejado |
|
|
113
|
+
| O gate engessa a doc e desestimula escrever | B | M | Ele só cobra referências a **código**; prosa é livre |
|
|
114
|
+
|
|
115
|
+
## 8. Métricas de sucesso
|
|
116
|
+
|
|
117
|
+
- **Zero** comandos fantasma na documentação, verificado a cada CI — em vez de a cada auditoria
|
|
118
|
+
manual que alguém lembrar de fazer.
|
|
119
|
+
- Renomear um comando passa a **quebrar o CI** enquanto a doc não acompanhar. Hoje renomear é grátis
|
|
120
|
+
e a doc apodrece calada.
|
|
121
|
+
- Os 42 comandos do registry passam a ter, cada um, ao menos um lugar onde o sistema explica o que
|
|
122
|
+
ele faz. Nenhum step obscuro.
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Plan: doctor-do-nucleo
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Criado em**: 2026-07-13
|
|
6
|
+
|
|
7
|
+
> Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
|
|
8
|
+
|
|
9
|
+
## 1. Abordagem técnica
|
|
10
|
+
|
|
11
|
+
**Extend, não rewrite.** O `tools-doctor.mjs` já tem a forma certa — uma lista declarativa
|
|
12
|
+
(`TOOLS[]`) percorrida por um runner burro. Erramos no *conteúdo* da lista, não na estrutura.
|
|
13
|
+
|
|
14
|
+
Extraímos os checks para `lib/core/health.mjs` como **dados** (`CHECKS[]`), com um runner que os
|
|
15
|
+
executa e devolve resultados estruturados. O `tools-doctor` vira uma das três superfícies de
|
|
16
|
+
apresentação; `SessionStart` vira outra. Nenhuma superfície tem heurística própria — é justamente
|
|
17
|
+
isso que permitiu, hoje, uma delas prescrever a correção errada sozinha.
|
|
18
|
+
|
|
19
|
+
A mudança central de comportamento é **parar de colapsar causas distintas num booleano**. Hoje
|
|
20
|
+
`hook-session-start.mjs:38-45` faz `catch { return null }`, engolindo *sem `node_modules`*,
|
|
21
|
+
*ABI incompatível* e *banco ausente* no mesmo `null` — e a linha 91 prescreve a correção de apenas
|
|
22
|
+
uma das três. Cada probe passa a **classificar a causa** e devolver a correção dela.
|
|
23
|
+
|
|
24
|
+
## 2. Módulos afetados
|
|
25
|
+
|
|
26
|
+
| Caminho | Mudança | Risco |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| `lib/core/health.mjs` | **criar** — `CHECKS[]` + runner. Fonte única de verdade | M |
|
|
29
|
+
| `scripts/tools-doctor.mjs` | editar — consome a lib; ganha seção Núcleo + exit code | M |
|
|
30
|
+
| `scripts/hook-session-start.mjs` | editar — remove heurística própria (`resolveDbPath`, `staleIndex`) e a prescrição errada | A |
|
|
31
|
+
| `lib/core/registry.mjs` | editar — `desc` do `tools:doctor` reflete o novo papel | B |
|
|
32
|
+
| `scripts/spec-cli.mjs` | editar — `spec:new` mantém a allow-list do `.gitignore` (AC-11) | B |
|
|
33
|
+
| `test/health.test.js` | **criar** — cada check nos dois estados | B |
|
|
34
|
+
| `memory/90-decisions/0023-doctor-como-gate-do-nucleo.md` | **criar** — ADR | B |
|
|
35
|
+
| `CLAUDE.md`, `docs/` | editar — `tools:doctor` deixa de ser "raio-x de ferramentas" | B |
|
|
36
|
+
|
|
37
|
+
Risco alto no hook: ele roda em **toda** sessão e o ADR-0021 já o marcou como "nunca pode derrubar
|
|
38
|
+
a sessão". Qualquer regressão ali é sentida imediatamente e em todo lugar.
|
|
39
|
+
|
|
40
|
+
## 3. Diagrama de fluxo
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
tools:doctor ────┐
|
|
44
|
+
SessionStart ────┼──► lib/core/health.mjs :: runChecks({ scope })
|
|
45
|
+
release-auditor ─┘ │
|
|
46
|
+
▼
|
|
47
|
+
┌──────────────── CHECKS[] (declarativo) ────────────────┐
|
|
48
|
+
│ id severity scope dependsOn │
|
|
49
|
+
│ native-abi critical runtime — │
|
|
50
|
+
│ memory-db critical runtime native-abi │
|
|
51
|
+
│ memory-fresh warn runtime memory-db │
|
|
52
|
+
│ workspace warn runtime — │
|
|
53
|
+
│ node-engines warn runtime — │
|
|
54
|
+
│ runtime-deps critical repo — │
|
|
55
|
+
│ mcp-json critical repo — │
|
|
56
|
+
└────────────────────────────────────────────────────────┘
|
|
57
|
+
│
|
|
58
|
+
Result[] { id, status, detail, fix, severity }
|
|
59
|
+
│
|
|
60
|
+
┌───────────────────┴───────────────────┐
|
|
61
|
+
▼ ▼
|
|
62
|
+
doctor: 2 seções + exit(1) se hook: só scope=runtime,
|
|
63
|
+
algum critical falhou sempre exit(0), warn no contexto
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**Cascata (`dependsOn`)** é o que evita o pior modo de falha de um diagnóstico: com o ABI quebrado,
|
|
67
|
+
`memory-db` e `memory-fresh` também falhariam, e o operador veria **três** erros sem saber qual é a
|
|
68
|
+
raiz. Um check cujo `dependsOn` falhou é reportado como `skipped`, não como `fail`. Uma causa, uma
|
|
69
|
+
linha vermelha, uma correção.
|
|
70
|
+
|
|
71
|
+
## 4. Contratos (API/CLI/Schema)
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
// lib/core/health.mjs
|
|
75
|
+
|
|
76
|
+
/** @typedef {'critical'|'warn'} Severity */
|
|
77
|
+
/** @typedef {'runtime'|'repo'} Scope */
|
|
78
|
+
/** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
|
|
79
|
+
/** @typedef {{ id, title, severity: Severity, scope: Scope, dependsOn?: string, probe }} Check */
|
|
80
|
+
/** @typedef {{ id, title, severity, status: Status, detail: string, fix: string|null }} Result */
|
|
81
|
+
|
|
82
|
+
export const CHECKS;
|
|
83
|
+
|
|
84
|
+
/** Executa os checks. `scope: 'runtime'` roda só os baratos e portáveis (hook). */
|
|
85
|
+
export async function runChecks(opts); // { scope = 'all', env } -> Promise<Result[]>
|
|
86
|
+
|
|
87
|
+
/** 'fail' se algum critical falhou; senão 'warn' se houver warn; senão 'ok'. */
|
|
88
|
+
export function worstStatus(results); // -> 'ok' | 'warn' | 'fail'
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
O `probe` recebe um **ambiente injetável** (`env = { root, importModule, fs, workspace }`) e devolve
|
|
92
|
+
`{ status, detail, fix }`. Nunca lança: o runner o envolve em try/catch e converte exceção
|
|
93
|
+
inesperada em `fail` — um check que estoura ao diagnosticar é pior que check nenhum (NFR).
|
|
94
|
+
|
|
95
|
+
**CLI** — `tools:doctor` mantém nome e entrada no registry (ADR-0020). Muda o contrato de saída:
|
|
96
|
+
|
|
97
|
+
| Situação | Antes | Depois |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| Tudo são | `exit 0` | `exit 0` |
|
|
100
|
+
| Ferramenta opcional ausente | `exit 0` | `exit 0` *(ADR-0018 preservado)* |
|
|
101
|
+
| Índice defasado / workspace ausente | — | `exit 0` + aviso |
|
|
102
|
+
| **Núcleo quebrado** | `exit 0` | **`exit 1`** + correção |
|
|
103
|
+
|
|
104
|
+
## 5. Decisões e alternativas
|
|
105
|
+
|
|
106
|
+
**D1: Checks como dados, não como funções que imprimem.** Permite três superfícies com uma lógica
|
|
107
|
+
só. Alternativa rejeitada: cada superfície chama helpers e formata do seu jeito — é literalmente o
|
|
108
|
+
que temos hoje, e é a causa da divergência entre o que o doctor diz e o que o hook diz.
|
|
109
|
+
|
|
110
|
+
**D2: Probes classificam a causa; o runner nunca colapsa em booleano.** `ERR_DLOPEN_FAILED` →
|
|
111
|
+
`npm rebuild better-sqlite3`. `ERR_MODULE_NOT_FOUND` → `npm install`. Banco ausente →
|
|
112
|
+
`npm run sync:universal`. Alternativa rejeitada: manter `catch → null` e só melhorar o texto da
|
|
113
|
+
mensagem — daria uma prescrição *genérica*, e o problema de hoje foi precisamente uma prescrição
|
|
114
|
+
genérica aplicada a um caso específico.
|
|
115
|
+
|
|
116
|
+
**D3: `scope: repo | runtime`.** `runtime-deps` e `mcp-json` são checks de **regressão do
|
|
117
|
+
repositório** — não fazem sentido numa instalação `npm i -g forjajs`, onde não há `devDependencies`
|
|
118
|
+
instaladas nem `.mcp.json` versionado. Rodá-los fora do repo produziria falso positivo crítico no
|
|
119
|
+
ambiente do usuário final. Detecção: presença de `.git` + `package.json` com `name: forjajs`.
|
|
120
|
+
|
|
121
|
+
**D4: Só `critical` trava.** `workspace` ausente e `node-engines` abaixo do declarado entram como
|
|
122
|
+
`warn`, não `fail` — o framework funciona sem workspace (só `project:new` não). Um gate que reprova
|
|
123
|
+
o que não impede trabalho é um gate que se aprende a ignorar (risco nº 1 da spec).
|
|
124
|
+
|
|
125
|
+
**D5: Injeção de dependência no probe (`env`).** Testar ABI quebrada exigiria mockar o loader de
|
|
126
|
+
módulos do Node. Com `env.importModule` injetável, o teste passa uma função que lança
|
|
127
|
+
`ERR_DLOPEN_FAILED` e verifica a prescrição — sem mock de módulo, sem corromper `node_modules`.
|
|
128
|
+
|
|
129
|
+
**D6: Doctor diagnostica, não conserta.** Sem `--fix`. Rodar `npm rebuild` sem consentimento é a
|
|
130
|
+
classe de risco oposta à que estamos consertando (spec §5, fora de escopo).
|
|
131
|
+
|
|
132
|
+
D1, D3 e a mudança de contrato de exit code são estruturais → **ADR-0023**
|
|
133
|
+
(`memory/90-decisions/0023-doctor-como-gate-do-nucleo.md`), referenciando ADR-0018 (que ele estende)
|
|
134
|
+
e ADR-0021 (a classe de falha que ele fecha).
|
|
135
|
+
|
|
136
|
+
## 6. Dependências
|
|
137
|
+
|
|
138
|
+
- **Specs**: nenhuma. Fecha a classe do ADR-0021; não depende de spec aberta.
|
|
139
|
+
- **Pacotes npm**: **nenhum novo.** Tudo com `node:fs`, `node:path` e o `better-sqlite3` que já é
|
|
140
|
+
`dependency`. Adicionar dependência a um módulo cujo propósito é funcionar quando as dependências
|
|
141
|
+
quebram seria autodestrutivo.
|
|
142
|
+
- **Migrações**: nenhuma. Nada de schema, nada de dado.
|
|
143
|
+
|
|
144
|
+
## 7. Rollout
|
|
145
|
+
|
|
146
|
+
- [ ] Feature flag necessária? **Não.** A mudança é aditiva, exceto pelo exit code — que só passa a
|
|
147
|
+
falhar em ambiente que **já está** quebrado.
|
|
148
|
+
- [ ] Migração de dados existentes? **Não.**
|
|
149
|
+
- [x] Doc/persona impactada? `CLAUDE.md` (tabela de comandos) e `docs/` onde `tools:doctor` é
|
|
150
|
+
descrito como "raio-x de ferramentas". Persona **qa/governança** ganha gate novo.
|
|
151
|
+
- [ ] **Ordem de merge**: `lib/core/health.mjs` + testes primeiro (nada consome ainda), depois as
|
|
152
|
+
superfícies. O hook por último — é o de maior risco e o único que roda sempre.
|
|
153
|
+
- [ ] Validar com `npm run tools:doctor` num Node de major diferente (o cenário de hoje) **antes**
|
|
154
|
+
de fechar. Um doctor de ABI que nunca viu um ABI quebrado não está testado, está escrito.
|
|
155
|
+
|
|
156
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
157
|
+
|
|
158
|
+
- **O hook fica lento ou instável.** Ele roda em toda sessão e não pode derrubá-la (ADR-0021). Se
|
|
159
|
+
`runChecks({ scope: 'runtime' })` não couber com folga no timeout de 5s, o hook volta a ter
|
|
160
|
+
caminho próprio (mínimo, ainda consumindo a lib) em vez de arrastarmos o custo para toda sessão.
|
|
161
|
+
- **`runtime-deps` vira ruído.** Se o parser estático de imports gerar falso positivo crítico mais
|
|
162
|
+
de uma vez, ele é rebaixado a `warn` — a spec já prevê isso no risco, e um crítico que mente é
|
|
163
|
+
pior que um warning honesto.
|
|
164
|
+
- **O operador passa a rodar `tools:doctor` já sabendo o resultado.** Se o gate vira ritual, erramos
|
|
165
|
+
a calibragem de severidade e voltamos a D4.
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Spec: doctor-do-nucleo
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-009
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-07-13
|
|
7
|
+
- **Sprint alvo**: S?
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0018](../../memory/90-decisions/0018-ferramentas-de-processo.md) (tools:doctor), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails de harness), [ADR-0019](../../memory/90-decisions/0019-workspace-separado.md) (workspace), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
O `tools:doctor` audita cinco ferramentas **externas e opcionais** e conclui com a própria
|
|
13
|
+
ressalva: *"ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas."*
|
|
14
|
+
Ele diagnostica exatamente aquilo que não é crítico, e é cego para tudo que é.
|
|
15
|
+
|
|
16
|
+
Em 2026-07-13, com `better-sqlite3` compilado contra o ABI do Node 24 num runtime Node 26,
|
|
17
|
+
a memória universal — a aposta nº 1 da visão, *"memória que sobrevive"* — estava **morta**:
|
|
18
|
+
`query:universal`, `sync:universal`, `context:smart`, `agent:route`, `memory:compress` e
|
|
19
|
+
`project:dashboard` todos inoperantes. O framework reagiu assim:
|
|
20
|
+
|
|
21
|
+
| Superfície | O que fez | O que deveria ter feito |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| `tools:doctor` | Reportou `2/5 ferramentas disponíveis`, tudo aparentemente normal | Falhar apontando o ABI quebrado |
|
|
24
|
+
| `SessionStart` | Detectou, mas prescreveu `npm install` + `sync:universal` | Prescrever `npm rebuild better-sqlite3` |
|
|
25
|
+
| `npm test` | Stack trace de `ERR_DLOPEN_FAILED` | — (aceitável, mas sem orientação) |
|
|
26
|
+
|
|
27
|
+
A prescrição errada é o pior dos três. `npm install` **não** recompila binário nativo quando o
|
|
28
|
+
lock já bate; quem seguisse a instrução do próprio framework não consertaria nada e concluiria
|
|
29
|
+
que o problema era outro.
|
|
30
|
+
|
|
31
|
+
Esta é a **quinta ocorrência** da classe de falha que o ADR-0021 nomeia — *"erram sem avisar…
|
|
32
|
+
produzem trabalho errado com aparência de trabalho certo"*. As quatro anteriores receberam
|
|
33
|
+
correções pontuais. Falta o gate genérico: **nada valida o núcleo do framework**, e dois dos
|
|
34
|
+
quatro casos já corrigidos (`.mcp.json` com path absoluto; `better-sqlite3` fora de
|
|
35
|
+
`dependencies`) podem reincidir sem que nenhum teste ou gate perceba.
|
|
36
|
+
|
|
37
|
+
## 2. Proposta de valor
|
|
38
|
+
|
|
39
|
+
Uma única fonte de verdade sobre a saúde do núcleo, consumida por todas as superfícies de
|
|
40
|
+
diagnóstico: **toda quebra do núcleo é detectada na primeira vez que o operador toca o
|
|
41
|
+
framework, com o comando de correção correto ao lado.**
|
|
42
|
+
|
|
43
|
+
## 3. User stories
|
|
44
|
+
|
|
45
|
+
- **Como** operador, **quero** que `tools:doctor` falhe quando o núcleo está quebrado,
|
|
46
|
+
**para que** eu não descubra por um stack trace de `dlopen` trinta minutos depois.
|
|
47
|
+
- **Como** operador que trocou de versão do Node, **quero** a prescrição certa
|
|
48
|
+
(`npm rebuild better-sqlite3`), **para que** eu não perca tempo seguindo um conselho errado
|
|
49
|
+
do próprio framework.
|
|
50
|
+
- **Como** agente iniciando sessão, **quero** saber que a memória está defasada ou morta antes
|
|
51
|
+
de confiar num `query:universal`, **para que** eu não construa raciocínio sobre contexto vazio.
|
|
52
|
+
- **Como** governança, **quero** um gate que reprove um release em que os invariantes do
|
|
53
|
+
ADR-0021 regrediram, **para que** as correções pontuais não se percam com o tempo.
|
|
54
|
+
- **Como** autor de uma spec do framework, **quero** que ela seja versionada por padrão,
|
|
55
|
+
**para que** eu não a perca sem aviso — hoje o `.gitignore` a descarta calado.
|
|
56
|
+
|
|
57
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
58
|
+
|
|
59
|
+
- [x] AC-1: Existe `lib/core/health.mjs` exportando os checks de núcleo como dados
|
|
60
|
+
(`{ id, severity, probe, fix }`), sem I/O de apresentação.
|
|
61
|
+
- [x] AC-2: `tools:doctor` reporta **duas seções** — Núcleo e Ferramentas — e sai com código
|
|
62
|
+
**≠ 0** se e somente se algum check `critical` do núcleo falhar. Ausência de ferramenta
|
|
63
|
+
opcional continua sendo `exit 0` (contrato do ADR-0018 preservado).
|
|
64
|
+
- [x] AC-3: Check de **ABI nativa**: com `better-sqlite3` compilado para outro `NODE_MODULE_VERSION`,
|
|
65
|
+
o doctor falha com a mensagem apontando `npm rebuild better-sqlite3`. Testável simulando
|
|
66
|
+
o `ERR_DLOPEN_FAILED`.
|
|
67
|
+
- [x] AC-4: Check de **memória**: distingue os três estados — banco ausente, banco inacessível,
|
|
68
|
+
banco defasado (`memory/` alterado depois do último sync) — cada um com sua correção.
|
|
69
|
+
- [x] AC-5: Check de **workspace**: `lib/workspace.mjs` resolve para diretório existente; se não,
|
|
70
|
+
prescreve `npm run workspace:init`.
|
|
71
|
+
- [x] AC-6: Check de **deps de runtime** (regressão do ADR-0021 §2): todo módulo importado
|
|
72
|
+
estaticamente por scripts sob `files[]` está em `dependencies`, não em `devDependencies`.
|
|
73
|
+
- [x] AC-7: Check de **`.mcp.json`** (regressão do ADR-0021 §1): nenhum path absoluto versionado.
|
|
74
|
+
- [x] AC-8: O hook `SessionStart` consome `lib/core/health.mjs` — **zero heurística própria** — e
|
|
75
|
+
a prescrição errada atual (`npm install`) deixa de existir no código.
|
|
76
|
+
- [x] AC-9: Testes cobrindo cada check nos dois estados (são e quebrado), com a suíte verde.
|
|
77
|
+
- [x] AC-10: ADR registrando a decisão (doctor como gate do núcleo vs. relatório de ferramentas).
|
|
78
|
+
- [x] AC-11: `spec:new` **mantém a allow-list do `.gitignore` sozinho** ao criar uma spec do
|
|
79
|
+
framework. Criar uma spec e rodar `git status` passa a mostrá-la, sem passo manual.
|
|
80
|
+
*(Emenda de 2026-07-13 — ver §5.)*
|
|
81
|
+
|
|
82
|
+
## 5. Escopo
|
|
83
|
+
|
|
84
|
+
**Dentro**:
|
|
85
|
+
- `lib/core/health.mjs` — os checks como dados, reutilizáveis.
|
|
86
|
+
- `scripts/tools-doctor.mjs` — passa a consumir a lib; ganha seção de núcleo e exit code.
|
|
87
|
+
- `scripts/hook-session-start.mjs` (ou equivalente) — passa a consumir a lib.
|
|
88
|
+
- Os sete checks: ABI nativa, banco presente, banco fresco, workspace resolvido, deps de runtime,
|
|
89
|
+
`.mcp.json` limpo, Node vs. `engines`.
|
|
90
|
+
- `scripts/spec-cli.mjs` — allow-list do `.gitignore` mantida pelo harness (AC-11).
|
|
91
|
+
- ADR + testes.
|
|
92
|
+
|
|
93
|
+
> **Emenda (2026-07-13).** Ao escrever o plano, descobrimos que o `.gitignore` ignora `/specs/*` e
|
|
94
|
+
> mantém uma allow-list manual: **toda spec nova do framework nasce invisível ao git**. O `spec:new`
|
|
95
|
+
> cria, o `spec:check` aprova, e o git descarta calado — aconteceu com esta própria spec. É a mesma
|
|
96
|
+
> classe de falha do ADR-0021, dentro da ferramenta que estamos consertando.
|
|
97
|
+
>
|
|
98
|
+
> Rejeitamos resolver isso com um *check* no doctor (`spec-allowlist` → warn): trocaria uma falha
|
|
99
|
+
> silenciosa por um lembrete recorrente que se aprende a ignorar. Seguimos o próprio ADR-0021 —
|
|
100
|
+
> *"mover a aplicação das regras do texto para o harness"* — e fazemos o `spec:new` manter a lista.
|
|
101
|
+
> A classe de erro deixa de existir em vez de ser reportada.
|
|
102
|
+
|
|
103
|
+
**Fora** (explícito, evita scope creep):
|
|
104
|
+
- **Autocorreção.** O doctor diagnostica e prescreve; não executa `npm rebuild` sozinho.
|
|
105
|
+
Rodar comandos de build sem consentimento é a classe de risco oposta.
|
|
106
|
+
- Novos gates de qualidade de código (lint, cobertura) — não é sobre isso.
|
|
107
|
+
- Alterar o conjunto das cinco ferramentas opcionais do ADR-0018.
|
|
108
|
+
- Reindexação automática da memória (`sync:universal` permanece explícito).
|
|
109
|
+
|
|
110
|
+
## 6. NFRs / restrições
|
|
111
|
+
|
|
112
|
+
- **Performance**: o doctor completo roda em < 2s. O `SessionStart` não pode ficar perceptivelmente
|
|
113
|
+
mais lento — os checks caros (deps, `.mcp.json`) só entram no doctor, não no hook.
|
|
114
|
+
- **Resiliência**: todo acesso a SQLite permanece *lazy* (ADR-0021). O doctor precisa funcionar
|
|
115
|
+
**sem `node_modules`** — é justamente aí que ele mais importa. Um check que estoura ao
|
|
116
|
+
diagnosticar é pior que check nenhum.
|
|
117
|
+
- **Contrato**: `exit 0` continua significando "posso trabalhar". Ferramenta opcional ausente
|
|
118
|
+
nunca trava; núcleo quebrado sempre trava.
|
|
119
|
+
- **Compatibilidade**: o comando `tools:doctor` mantém nome, entrada no registry (ADR-0020) e
|
|
120
|
+
saída legível.
|
|
121
|
+
|
|
122
|
+
## 7. Riscos e mitigação
|
|
123
|
+
|
|
124
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
125
|
+
|---|---|---|---|
|
|
126
|
+
| Doctor vira gate ruidoso e o operador aprende a ignorá-lo | M | A | Só `critical` trava. Warning (índice defasado) informa sem falhar |
|
|
127
|
+
| Check de deps de runtime dá falso positivo (import dinâmico, opcional) | M | M | Parser estático conservador: na dúvida, warning e não erro |
|
|
128
|
+
| Detecção de ABI depende de string de erro do Node | M | M | Casar por `err.code === 'ERR_DLOPEN_FAILED'`, não por mensagem |
|
|
129
|
+
| Doctor duplica o que o `release-auditor` já faz | B | B | Agente simula tarball (pré-publicação); doctor valida o repo vivo. `release-auditor` pode passar a consumir a mesma lib |
|
|
130
|
+
| Escopo escorrega para "doctor conserta tudo" | M | A | Autocorreção está explicitamente fora |
|
|
131
|
+
|
|
132
|
+
## 8. Métricas de sucesso
|
|
133
|
+
|
|
134
|
+
- **Zero** falhas silenciosas da classe ADR-0021 nos 30 dias após o release: toda quebra do núcleo
|
|
135
|
+
aparece no primeiro comando executado, não num sintoma indireto.
|
|
136
|
+
- Tempo entre quebrar o ambiente (ex.: trocar a major do Node) e ter o diagnóstico correto em mãos:
|
|
137
|
+
de *indefinido* (hoje o operador é ativamente mal orientado) para **um comando**.
|
|
138
|
+
- Os quatro invariantes já corrigidos pelo ADR-0021 passam a ter cobertura executável — regressão
|
|
139
|
+
em qualquer um deles reprova o gate em vez de reaparecer em produção.
|