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.
Files changed (36) hide show
  1. package/.claude/agents/governance.md +33 -10
  2. package/.claude/agents/release-auditor.md +44 -45
  3. package/CHANGELOG.md +74 -0
  4. package/DOC-MAP.md +2 -2
  5. package/README.md +2 -2
  6. package/docs/agent-harnesses.md +30 -3
  7. package/docs/token-optimization.md +28 -20
  8. package/lib/core/checks.mjs +138 -0
  9. package/lib/core/health.mjs +475 -0
  10. package/lib/core/registry.mjs +6 -1
  11. package/lib/core/release.mjs +452 -0
  12. package/memory/40-delivery/current-sprint.md +13 -7
  13. package/memory/90-decisions/0021-guardrails-de-harness.md +5 -1
  14. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -0
  15. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -0
  16. package/memory/90-decisions/0024-gate-do-tarball.md +103 -0
  17. package/package.json +7 -7
  18. package/prompts/governance-agent.md +2 -1
  19. package/scripts/hook-session-start.mjs +29 -39
  20. package/scripts/release-check.mjs +56 -0
  21. package/scripts/spec-cli.mjs +80 -13
  22. package/scripts/tools-doctor.mjs +65 -10
  23. package/specs/coerencia-do-sistema/spec.md +122 -0
  24. package/specs/doctor-do-nucleo/plan.md +165 -0
  25. package/specs/doctor-do-nucleo/spec.md +139 -0
  26. package/specs/doctor-do-nucleo/tasks.md +172 -0
  27. package/specs/reestruturacao-forja-v2/plan.md +1 -1
  28. package/specs/reestruturacao-forja-v2/spec.md +16 -12
  29. package/specs/reestruturacao-forja-v2/tasks.md +1 -1
  30. package/specs/release-gate/plan.md +174 -0
  31. package/specs/release-gate/spec.md +122 -0
  32. package/specs/release-gate/tasks.md +183 -0
  33. package/docs/dashboard.md +0 -102
  34. package/specs/agent-dashboard/plan.md +0 -165
  35. package/specs/agent-dashboard/spec.md +0 -89
  36. package/specs/agent-dashboard/tasks.md +0 -168
@@ -1,25 +1,48 @@
1
1
  ---
2
2
  name: governance
3
- description: Use ANTES de aprovar merge ou release. Roda project:check, valida que toda mudança estrutural tem ADR, audita handoffs por completude (7 campos), confere standards 12-Factor, LGPD/GDPR e segurança. Reprova com lista clara do que falta.
3
+ description: Use ANTES de aprovar merge ou release. Roda os gates (tools:doctor, project:check, code:check e — antes de publicar — release:check), valida que toda mudança estrutural tem ADR, audita handoffs por completude (7 campos), confere standards 12-Factor, LGPD/GDPR e segurança. Reprova com lista clara do que falta.
4
4
  tools: Read, Bash, Grep
5
5
  ---
6
6
 
7
7
  Você é o **Governance Agent** (Compliance & Standards). Linter humano do framework.
8
8
 
9
+ Um princípio antes de tudo: **regra que depende de memória não é regra, é sugestão** (ADR-0021).
10
+ Sempre que puder trocar seu julgamento por um gate executável, troque — e quando um gate existir,
11
+ rode-o em vez de inspecionar o código à mão. Você audita o que o gate não sabe julgar.
12
+
13
+ ## Gates (rode, não leia)
14
+
15
+ 1. `npm run tools:doctor` — **gate do núcleo** (ADR-0023). Sai com `exit 1` se o que impede o
16
+ framework de trabalhar está quebrado: ABI do `better-sqlite3`, memória, deps de runtime,
17
+ `.mcp.json`. Não é mais um inventário de ferramentas opcionais — **reprova de verdade**. Um
18
+ ambiente que falha aqui torna qualquer outra auditoria não-confiável: bloqueia.
19
+ 2. `npm run project:check` — standards. Reporte falhas.
20
+ 3. `npm run code:check` — o índice codegraph deve pertencer a este worktree e estar em dia
21
+ (ADR-0017). Índice de outro worktree torna a auditoria de código ficção: bloqueia.
22
+ 4. `npm run release:check -- --publish` — **antes de publicar no npm** (ADR-0024). Empacota,
23
+ instala limpo e prova que o pacote funciona na máquina de quem instala. Três releases quebraram
24
+ nessa fronteira antes de o gate existir. Se este reprova, **não se publica** — sem exceção.
25
+ 5. `gitleaks detect --no-banner` — se disponível (ADR-0018).
26
+
9
27
  ## Responsabilidades
10
- 1. Rodar `npm run project:check` e reportar falhas
11
- 2. Rodar `npm run code:check` — índice codegraph deve pertencer a este worktree e estar em dia (ADR-0017). Índice de outro worktree torna qualquer auditoria de código não-confiável: bloqueia
12
- 3. Rodar `npm run tools:doctor` para saber quais gates opcionais estão disponíveis (gitleaks, ast-grep, lefthook). Se `gitleaks` existir, rode `gitleaks detect --no-banner` antes de aprovar (ADR-0018)
13
- 4. Para cada feature em `implementing`: confere se há `spec.md` + `plan.md` + ADRs referenciadas no plan realmente existem
14
- 5. Auditar handoffs em `universal.db.handoffs` — campos faltando? destino inválido?
15
- 6. Verificar 12-Factor compliance: env vars, logs estruturados, processos stateless
16
- 7. Verificar LGPD/GDPR: dados pessoais com base legal, retenção definida, consent registrado
17
- 8. Bloquear merge se houver:
28
+
29
+ 1. Rodar os gates acima e reportar cada reprovação com a correção que ele mesmo prescreve
30
+ 2. Para cada feature em `implementing`: conferir se há `spec.md` + `plan.md` e se as ADRs
31
+ referenciadas no plan realmente existem
32
+ 3. Auditar handoffs em `universal.db.handoffs` — campos faltando? destino inválido?
33
+ 4. Verificar 12-Factor: env vars, logs estruturados, processos stateless
34
+ 5. Verificar LGPD/GDPR: dados pessoais com base legal, retenção definida, consent registrado
35
+ 6. Bloquear merge se houver:
36
+ - Gate do núcleo reprovado (`tools:doctor` com exit ≠ 0)
18
37
  - Código tocando padrões sem ADR
19
38
  - Spec em `implementing` sem AC checados
20
39
  - Handoff incompleto (7 campos da ADR-0005)
21
- - Secret hardcoded (busca por padrões em `git diff`; gitleaks se disponível)
40
+ - Secret hardcoded (padrões no `git diff`; gitleaks se disponível)
22
41
  - Índice codegraph de outro worktree (`code:check` reprovado)
42
+ 7. Bloquear **release** se houver:
43
+ - `release:check --publish` reprovado
44
+ - Árvore suja: `npm publish` empacota o **disco**, não o commit (foi assim que `otplib` e
45
+ `qrcode` foram publicados sem jamais existirem no git)
23
46
 
24
47
  ## Regras
25
48
  - Output sempre estruturado: ✓ aprovado / ✗ bloqueado com motivos numerados
@@ -1,64 +1,63 @@
1
1
  ---
2
2
  name: release-auditor
3
- description: Use ANTES de publicar no npm. Simula uma instalação limpa do tarball e valida que o files[] do package.json cobre tudo que os binários importam. Pega quebras que só apareceriam na máquina do usuário.
3
+ description: Use ANTES de publicar no npm. Roda o gate `release:check --publish`, interpreta o resultado e dá o parecer. Pega quebras que só apareceriam na máquina de quem instala.
4
4
  tools: Read, Bash, Grep
5
5
  ---
6
6
 
7
- Você é o **Release Auditor**. O Forja é publicado como `forjajs` no npm. Seu trabalho é
8
- responder a uma única pergunta com evidência: **o pacote funciona na máquina de quem
9
- instala?**
7
+ Você é o **Release Auditor**. O Forja é publicado como `forjajs` no npm. Seu trabalho é responder a
8
+ uma única pergunta com evidência: **o pacote funciona na máquina de quem instala?**
10
9
 
11
- O repositório mente sobre isso. No repo, tudo resolve: `node_modules` existe com devDeps,
12
- todos os arquivos estão presentes, o `cwd` é a raiz do projeto. Nada disso vale para quem
13
- roda `npm i -g forjajs`. Duas classes de bug vivem exatamente nessa lacuna e só aparecem
14
- em produção:
10
+ O repositório mente sobre isso. No repo tudo resolve: `node_modules` existe com devDeps, todos os
11
+ arquivos estão presentes, o `cwd` é a raiz. Nada disso vale para quem roda `npm i -g forjajs`. Essa
12
+ fronteira já cedeu três vezes — `better-sqlite3` como devDependency (ADR-0021), `otplib`/`qrcode`
13
+ publicados sem existirem no git (v1.1.1), `dashboard/` fora do `files[]` (v1.1.3).
15
14
 
16
- 1. **Arquivo fora do `files[]`** — o `package.json` lista os paths publicados à mão. Um
17
- `import` para um arquivo não listado quebra só depois do publish.
18
- 2. **Dependência de runtime declarada como `devDependency`** — não é instalada pelo
19
- usuário. O comando estoura com `ERR_MODULE_NOT_FOUND`.
20
-
21
- Grep e leitura de código não provam ausência dessas falhas. Instalação prova.
15
+ **O procedimento virou código.** Desde o ADR-0024, o que você fazia à mão vive em
16
+ `lib/core/release.mjs` e roda por um comando. Código não esquece um passo; você esquece. Seu papel
17
+ mudou: você não reimplementa a auditoria — você a **executa e julga**.
22
18
 
23
19
  ## Procedimento
24
20
 
25
- 1. **Empacote e instale de verdade**, num diretório temporário fora do repo:
26
-
27
- ```bash
28
- npm pack --pack-destination /tmp/forja-audit
29
- cd /tmp/forja-audit && npm init -y && npm i ./forjajs-<versão>.tgz
30
- ```
21
+ ```bash
22
+ npm run release:check -- --publish
23
+ ```
31
24
 
32
- 2. **Exercite cada comando do registry**, não só o help. O help não carrega os scripts —
33
- passa mesmo com tudo quebrado. Enumere os comandos e rode os que não têm efeito
34
- colateral (leitura, status, query):
25
+ Isso empacota, instala num diretório isolado (sem `NODE_PATH`, sem o `node_modules` do repo),
26
+ executa os comandos de verdade e reprova em qualquer um destes:
35
27
 
36
- ```bash
37
- npx forja # lista os comandos
38
- npx forja query:universal teste
39
- npx forja code:status
40
- npx forja tools:doctor
41
- ```
28
+ | Check | O que prova |
29
+ |---|---|
30
+ | `tree-clean` | O tarball é o commit. `npm publish` empacota o **disco**, não o git |
31
+ | `install` | O pacote instala do zero |
32
+ | `registry-scripts` | Todo comando anunciado tem script no tarball |
33
+ | `smoke-commands` | Os comandos **executam** — o help passa mesmo com tudo quebrado |
34
+ | `imports-resolve` | Todo import relativo resolve dentro do pacote |
35
+ | `deps-declared` | Nada importado ficou fora de `dependencies` |
36
+ | `deps-unused` | Nenhuma dependency é peso morto *(aviso)* |
42
37
 
43
- Um `ERR_MODULE_NOT_FOUND` aqui é reprovação imediata.
38
+ `exit 0` = aprovado. `exit 1` = reprovado, com o motivo e a correção em cada linha.
44
39
 
45
- 3. **Cruze imports contra `files[]`.** Para cada binário em `bin/`, siga os imports
46
- transitivamente e confirme que todo path resolvido cai sob um prefixo listado em
47
- `files[]`. Reporte os que não caem.
40
+ ## Seu julgamento, que o gate não faz
48
41
 
49
- 4. **Confira a fronteira deps/devDeps.** Todo pacote importado por código sob `files[]`
50
- precisa estar em `dependencies`. `devDependencies` só pode ser importado por `test/`
51
- e por scripts que não são publicados.
42
+ O gate diz **o que** quebrou. Você diz **o que fazer com isso**:
52
43
 
53
- ```bash
54
- grep -rn "from 'better-sqlite3'\|require('better-sqlite3')" bin/ lib/ scripts/
55
- ```
44
+ - **Leia a saída inteira antes de opinar.** Uma causa costuma produzir várias linhas; a cascata do
45
+ runner já marca as consequências como `não verificado`, então persiga a raiz, não o eco.
46
+ - **Avisos não reprovam, mas informam.** `deps-unused` num release público é peso que todo usuário
47
+ baixa. Vale corrigir antes de publicar, mesmo sem travar.
48
+ - **Diga o que o gate não cobre.** Ele não testa os projetos *gerados* pelos boilerplates, não
49
+ valida proveniência de pacote e não julga se a versão do `package.json` faz sentido para o que
50
+ mudou. Se algo disso importa nesta release, diga.
51
+ - **Nunca aprove com base em leitura de código.** Se o gate não rodou, você não sabe — e a resposta
52
+ certa é dizer que não sabe.
56
53
 
57
54
  ## Regras
58
55
 
59
- - Output estruturado: ✓ aprovado / ✗ reprovado, com motivos numerados.
60
- - Nunca rode `npm publish`. Você audita; publicar é decisão do usuário.
61
- - Nunca aprove com base em leitura de código. Se você não instalou o tarball e rodou
62
- um comando real, você não sabe — diga que não sabe.
63
- - Limpe `/tmp/forja-audit` ao final.
64
- - Se reprovar, aponte a linha exata: o import ofensor ou a entrada faltante no `files[]`.
56
+ - **Nunca rode `npm publish`.** Você audita; publicar é decisão do usuário.
57
+ - **Sua aprovação é perecível.** Vale para aquele disco, naquele instante. Ao aprovar, diga
58
+ explicitamente: qualquer `npm install`, `npm uninstall` ou edição posterior invalida o parecer e
59
+ exige nova auditoria. Foi exatamente assim que a v1.1.1 quebrou.
60
+ - **Se reprovar, aponte a linha exata** — o import ofensor, a entrada faltante no `files[]`, o
61
+ arquivo sujo no `git status`. O gate já te dá isso pronto; repasse sem diluir.
62
+ - Se o gate acusar algo que você tem **certeza** de ser falso positivo, não contorne: reporte, e
63
+ trate como bug do gate. Um gate em que se aprende a não confiar não protege de nada.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,80 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.1.4] — 2026-07-14 — Os gates
8
+
9
+ Duas fronteiras do framework funcionavam por disciplina, e a disciplina falhou nas duas. Esta versão
10
+ as fecha com gates executáveis — e, pela primeira vez, com **prova**: os bugs históricos foram
11
+ reintroduzidos um a um, e o gate reprovou cada um deles.
12
+
13
+ > "Uma regra que depende de memória não é uma regra; é uma sugestão." — ADR-0021
14
+
15
+ ### O que muda para quem usa
16
+
17
+ - **`npm publish` está bloqueado** se a instalação limpa não funcionar (`prepublishOnly` → ADR-0024).
18
+ - **`tools:doctor` reprova** (exit 1) quando o núcleo está quebrado — antes ele auditava só
19
+ ferramentas opcionais e saía com 0 mesmo com a memória morta (ADR-0023).
20
+ - Quando algo quebra, a saída traz **o comando que corrige**, não um stack trace.
21
+
22
+ ### Adicionado
23
+
24
+ - **`lib/core/health.mjs`** — saúde do núcleo como dados: ABI do `better-sqlite3`, memória, índice,
25
+ workspace, `engines`, deps de runtime, `.mcp.json`. Fonte única do `tools:doctor` e do hook
26
+ `SessionStart` (ADR-0023).
27
+ - **`lib/core/release.mjs` + `release:check`** — o gate do tarball. Empacota, instala num diretório
28
+ isolado e **executa** os comandos. Grep não prova ausência; instalação prova (ADR-0024).
29
+ - **`lib/core/checks.mjs`** — runner compartilhado. Uma máquina, dois catálogos: um guarda o repo,
30
+ outro guarda o pacote publicado.
31
+ - **CI**: `tools:doctor` na matriz de Nodes e `release:check` em job próprio. A evidência do release
32
+ passa a viver no log do CI, não na memória de quem publica.
33
+ - `spec:new` mantém a allow-list do `.gitignore` — toda spec nova do framework nascia invisível ao git.
34
+
35
+ ### Corrigido
36
+
37
+ - **A memória morria em silêncio.** Com o `better-sqlite3` compilado contra outra major do Node,
38
+ `query:universal`, `sync:universal`, `context:smart`, `agent:route` e `memory:compress` ficavam
39
+ todos inoperantes — e o `SessionStart` prescrevia `npm install`, que **não** recompila binário
40
+ nativo. A correção é `npm rebuild better-sqlite3`, e agora é isso que o framework diz.
41
+ - **`docs/token-optimization.md` mandava rodar quatro comandos inexistentes** (`context:build`,
42
+ `memory:db:reindex`, `memory:db:stats`, `cache:clear`) e linkava um `DEPLOYMENT.md` que nunca
43
+ existiu. É o documento que ensina a economia de tokens (ADR-0009) — um agente obediente executava
44
+ fantasmas.
45
+ - **O Governance não conhecia os gates**: descrevia o `tools:doctor` pela definição anterior ao
46
+ ADR-0023 e ignorava o `release:check`.
47
+ - `runtime-deps` passava por sorte: os geradores emitem `import … from '@nestjs/common'` dentro de
48
+ template literal, e o parser contava como dependência do framework.
49
+
50
+ ### Evidência
51
+
52
+ | Bug histórico | Reintroduzido → |
53
+ |---|---|
54
+ | `better-sqlite3` como `devDependency` (ADR-0021) | reprovado por **dois** checks independentes |
55
+ | `dashboard/` fora do `files[]` (v1.1.3) | reprovado: 4 comandos mortos, 19 imports sem destino |
56
+ | `otplib`/`qrcode` publicados sem existir no git (v1.1.1) | reprovado sob `--publish`; `npm publish` aborta |
57
+
58
+ **88 testes** (eram 28). ADR-0023 e ADR-0024. SPEC-009 e SPEC-010.
59
+
60
+ ## [1.1.3] — 2026-07-09 — Dashboard congelado
61
+
62
+ SPEC-002 (`specs/agent-dashboard/`) passa a `abandoned`. O código permanece em `dashboard/`,
63
+ versionado e com os 68 testes verdes, mas deixa de ser superfície pública. Ver
64
+ ADR-0022 (`memory/90-decisions/0022-congelar-dashboard-web.md`) para rationale e condições de retomada.
65
+
66
+ ### Corrigido
67
+ - **Bug de release**: `docs/dashboard.md` e o script `npm run dashboard` eram publicados no npm,
68
+ mas a pasta `dashboard/` nunca esteve no `files[]`. Quem instalava o pacote recebia a documentação
69
+ e o comando, sem o código. Ambos saíram do tarball.
70
+ - `README.md` descrevia o dashboard como "visão opcional read-only"; ele expõe rotas que executam
71
+ processos (`POST /api/workflow/:project/run/:role`). Descrição corrigida.
72
+ - `scripts/spec-cli.mjs` — `abandoned` é status válido, mas o `check` o rejeitava como incoerente
73
+ quando havia `plan.md`/`tasks.md`, derrubando o gate com exit 1. Agora é tratado como terminal,
74
+ junto de `done`.
75
+
76
+ ### Removido
77
+ - Scripts `dashboard`, `dashboard:dev`, `dashboard:install`, `dashboard:web:dev` e
78
+ `dashboard:web:build` do `package.json` do root.
79
+ - `docs/dashboard.md` e `specs/agent-dashboard/` do `files[]` do pacote npm.
80
+
7
81
  ## [Unreleased] — Workspace separado
8
82
 
9
83
  SPEC-028 (`specs/reestruturacao-forja-v2/`): separação do framework Forja do workspace de produção.
package/DOC-MAP.md CHANGED
@@ -27,7 +27,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
27
27
  - `docs/examples.md` — snippets prontos
28
28
  - `docs/dev-workflow.md`
29
29
  - `docs/init-project.md` — como gerar novo projeto
30
- - `docs/dashboard.md` — painel web local (`npm run dashboard`)
30
+ - `docs/dashboard.md` — painel web local (**congelado**, ver ADR-0021; não distribuído no pacote npm)
31
31
 
32
32
  ### QA
33
33
  - `docs/personas/qa/README.md`
@@ -56,7 +56,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
56
56
  | Publicação npm | `docs/publishing.md` |
57
57
  | Estrutura gerada | `docs/structure.md` |
58
58
  | Exemplos de código | `docs/examples.md` |
59
- | Dashboard web | `docs/dashboard.md` |
59
+ | Dashboard web (congelado) | `docs/dashboard.md` |
60
60
 
61
61
  ---
62
62
 
package/README.md CHANGED
@@ -28,7 +28,7 @@ A **Forja** é o estúdio em volta da IA. Ela coordena **6 papéis de agentes**
28
28
  **Spec-Driven (SDD)** + **Get-Stuff-Done (GSD)**, mantém uma **memória hierárquica**
29
29
  indexada em SQLite que sobrevive entre sessões, e amarra tudo num **core CLI único com
30
30
  gates e trilha de auditoria** (`forja`, ADR-0020). Multi-IA por design (Claude, Copilot,
31
- Gemini, Codex) — o dashboard web é apenas uma visão opcional read-only.
31
+ Gemini, Codex). A operação é inteiramente via CLI.
32
32
 
33
33
  **Para quem**: o dev solo ou time pequeno que opera múltiplos produtos com IA como
34
34
  principal força de trabalho — e precisa da disciplina de um time grande sem ter esse time.
@@ -184,7 +184,7 @@ npm run context:smart # smart-context
184
184
 
185
185
  # Qualidade & visão
186
186
  npm run project:check # standards do framework
187
- npm run dashboard # front opcional (http://127.0.0.1:7777)
187
+ npm run project:dashboard # relatório estático de status
188
188
  ```
189
189
 
190
190
  ## Separação framework × workspace
@@ -84,14 +84,41 @@ Regras operacionais:
84
84
  - **Gate de Governanca**: `code:check` reprova (bloqueante) se o indice pertence a outro worktree; e nao-bloqueante se o codegraph simplesmente nao esta instalado.
85
85
  - `gsd:check` ja inclui o gate codegraph automaticamente.
86
86
 
87
- ## Tools Doctor (ferramentas de processo)
88
-
89
- `tools:doctor` (ADR-0018) e o raio-x das ferramentas opcionais que potencializam o processo. Detecta sem impor:
87
+ ## Doctor (nucleo + ferramentas de processo)
90
88
 
91
89
  ```bash
92
90
  npm run tools:doctor
93
91
  ```
94
92
 
93
+ Duas secoes, dois contratos:
94
+
95
+ ### Nucleo — o que impede o framework de trabalhar (ADR-0023)
96
+
97
+ Falha critica aqui **reprova com exit 1**. Cada falha vem com o comando que a corrige.
98
+
99
+ | Check | O que verifica | Severidade |
100
+ |---|---|---|
101
+ | `native-abi` | better-sqlite3 carrega no Node em uso | critica |
102
+ | `memory-db` | `universal.db` abre | critica se corrompido; **aviso** se so nao foi indexado |
103
+ | `memory-fresh` | indice em dia com `memory/` | aviso |
104
+ | `workspace` | workspace resolvido (e por qual origem) | aviso |
105
+ | `node-engines` | Node dentro do `engines` declarado | aviso |
106
+ | `runtime-deps` | script publicado nao importa devDependency (ADR-0021) | critica |
107
+ | `mcp-json` | `.mcp.json` sem path absoluto versionado (ADR-0021) | critica |
108
+
109
+ O caso que motivou o gate: com o `better-sqlite3` compilado para outra major do Node, a memoria
110
+ universal morre inteira — e o doctor antigo reportava "2/5 ferramentas disponiveis", exit 0. A
111
+ correcao e `npm rebuild better-sqlite3`; `npm install` **nao** recompila binario nativo.
112
+
113
+ O doctor diagnostica e prescreve; nao conserta. Nao existe `--fix`.
114
+
115
+ Os checks `runtime-deps` e `mcp-json` so rodam dentro do repo do framework — numa instalacao
116
+ `npm i -g forjajs` nao ha devDependencies nem `.mcp.json`, e eles dariam falso positivo.
117
+
118
+ ### Ferramentas de processo — opcionais (ADR-0018)
119
+
120
+ Detecta sem impor. Ausencia **nunca** trava o fluxo: apenas desativa o gate correspondente.
121
+
95
122
  | Ferramenta | Papel | Gate |
96
123
  |---|---|---|
97
124
  | codegraph | code intelligence | `code:check` / `code:impact` |
@@ -410,7 +410,7 @@ const context = builder.build('global', 'my-project');
410
410
 
411
411
  ```bash
412
412
  # Developer needs feature context
413
- npm run context:build -- task my-project "payment feature"
413
+ npm run context:smart -- task my-project "payment feature"
414
414
  # Uses cached domain + task-specific files
415
415
  # Result: ~30KB, ~7500 tokens, $0.0075
416
416
  ```
@@ -419,7 +419,7 @@ npm run context:build -- task my-project "payment feature"
419
419
 
420
420
  ```bash
421
421
  # Security agent needs all related context
422
- npm run context:build -- domain my-project
422
+ npm run context:smart -- domain my-project
423
423
  # Adds security rules, ADRs, design docs
424
424
  # Result: ~20KB, ~5000 tokens, $0.005
425
425
  ```
@@ -428,7 +428,7 @@ npm run context:build -- domain my-project
428
428
 
429
429
  ```bash
430
430
  # New dev needs big picture
431
- npm run context:build -- global my-project
431
+ npm run context:smart -- global my-project
432
432
  # Just mission, standards, recent ADRs
433
433
  # Result: ~2KB, ~500 tokens, $0.0005
434
434
  ```
@@ -441,21 +441,22 @@ npm run context:build -- global my-project
441
441
 
442
442
  ```bash
443
443
  # Try smaller mode
444
- npm run context:build -- global # Instead of domain
444
+ npm run context:smart -- global # Instead of domain
445
445
 
446
446
  # Or prune manually
447
- node scripts/compress-memory.mjs
447
+ npm run memory:compress
448
448
  npm run memory:vacuum
449
449
  ```
450
450
 
451
- ### FTS5 Queries Slow?
451
+ ### FTS5 Queries Slow or Stale?
452
452
 
453
453
  ```bash
454
- # Rebuild search index
455
- npm run memory:db:reindex
454
+ # Rebuild the index (it is also what fixes a stale index)
455
+ npm run sync:universal
456
456
 
457
- # Check stats
458
- npm run memory:db:stats
457
+ # The doctor tells you when the index is behind memory/ — it is the
458
+ # failure that costs the most and shows the least (ADR-0023).
459
+ npm run tools:doctor
459
460
  ```
460
461
 
461
462
  ### Cache Not Working?
@@ -472,23 +473,30 @@ cat .memoryrc.json | grep cache -A 5
472
473
 
473
474
  ## 📚 Related Commands
474
475
 
476
+ Todos passam pelo core (`bin/forja.mjs`, ADR-0020). Se um comando não está aqui, ele está no
477
+ registry — `node bin/forja.mjs` lista todos.
478
+
475
479
  ```bash
476
- # Build context
477
- npm run context:build -- global my-project
480
+ # Buscar antes de ler: é o primeiro passo da economia de tokens (ADR-0009)
481
+ npm run query:universal "auth"
482
+
483
+ # Montar o pacote de contexto mínimo-suficiente (global | domain | task)
484
+ npm run context:smart -- task my-project "payment feature"
478
485
 
479
- # Compress memory
486
+ # Reindexar a memória — também é o que corrige um índice defasado
487
+ npm run sync:universal
488
+
489
+ # Comprimir memória antiga e recuperar espaço
490
+ npm run memory:compress
480
491
  npm run memory:vacuum
481
492
 
482
- # Benchmark tokens
493
+ # Medir a economia
483
494
  npm run token:benchmark
484
495
 
485
- # Clean cache
486
- npm run cache:clear
487
-
488
- # Query memory
489
- npm run memory:db:query -- "auth"
496
+ # Índice defasado responde sobre memória velha, calado. O doctor avisa (ADR-0023)
497
+ npm run tools:doctor
490
498
  ```
491
499
 
492
500
  ---
493
501
 
494
- **Next**: See [DEPLOYMENT.md](DEPLOYMENT.md) for integration with CI/CD.
502
+ **Próximo**: [`docs/agent-harnesses.md`](agent-harnesses.md) — os gates e as ferramentas de processo.
@@ -0,0 +1,138 @@
1
+ /**
2
+ * lib/core/checks.mjs — o runner de checks. Sem opinião sobre o que se checa.
3
+ *
4
+ * Máquina compartilhada por dois catálogos, cada um guardando uma fronteira:
5
+ *
6
+ * health.mjs o núcleo — o que impede o framework de trabalhar aqui (SPEC-009, ADR-0023)
7
+ * release.mjs o tarball — o que impede o pacote de funcionar na máquina de quem instala (SPEC-010)
8
+ *
9
+ * O runner foi extraído, e não copiado, de propósito: duas máquinas iguais divergem com o tempo, e
10
+ * divergência entre superfícies que deveriam concordar é exatamente o defeito que a SPEC-009
11
+ * existiu para matar (o doctor e o hook diziam coisas diferentes sobre a mesma memória).
12
+ *
13
+ * Dois princípios, que valem para qualquer check novo em qualquer catálogo:
14
+ *
15
+ * 1. **Nunca colapsar causas distintas num booleano.** Um probe classifica a causa e devolve a
16
+ * correção *dela*. O bug que originou tudo isso era um `catch { return null }` que engolia três
17
+ * causas e prescrevia a correção de uma.
18
+ * 2. **Uma causa, uma linha vermelha.** Check cuja dependência falhou é `skipped`, não `fail` —
19
+ * senão uma raiz vira três erros vermelhos e o operador não sabe qual perseguir.
20
+ */
21
+
22
+ /** @typedef {'critical'|'warn'} Severity */
23
+ /** @typedef {'runtime'|'repo'} Scope */
24
+ /** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
25
+
26
+ /**
27
+ * @typedef {object} Check
28
+ * @property {string} id
29
+ * @property {string} title
30
+ * @property {Severity} severity `critical` trava o gate; `warn` informa.
31
+ * @property {Scope=} scope Filtro opcional do runner.
32
+ * @property {string=} dependsOn Id de outro check. Se ele não passar, este vira `skipped`.
33
+ * @property {(env: object) => Promise<Probe>|Probe} probe
34
+ */
35
+
36
+ /**
37
+ * @typedef {object} Probe
38
+ * @property {Status} status
39
+ * @property {string} detail O que foi observado, em uma linha.
40
+ * @property {string|null=} fix Comando exato que corrige. `null` quando não há o que corrigir.
41
+ */
42
+
43
+ /** @typedef {{ id, title, severity: Severity, scope: Scope, status: Status, detail: string, fix: string|null }} Result */
44
+
45
+ const SEVERITY_FALLBACK = 'critical';
46
+
47
+ /**
48
+ * Um probe que estoura é pior que probe nenhum: derrubaria o diagnóstico justamente no ambiente
49
+ * quebrado que ele existe para diagnosticar. O runner blinda cada um e segue para o próximo.
50
+ */
51
+ async function runProbe(check, env) {
52
+ try {
53
+ const probe = await check.probe(env);
54
+ return {
55
+ status: probe.status,
56
+ detail: probe.detail,
57
+ fix: probe.fix ?? null,
58
+ };
59
+ } catch (err) {
60
+ return {
61
+ status: 'fail',
62
+ detail: `probe falhou: ${err?.message || err}`,
63
+ fix: null,
64
+ };
65
+ }
66
+ }
67
+
68
+ /**
69
+ * Executa os checks na ordem declarada.
70
+ *
71
+ * @param {{ checks: Check[], scope?: Scope|'all', env?: object }} opts
72
+ * @returns {Promise<Result[]>}
73
+ */
74
+ export async function runChecks({ checks, scope = 'all', env = {} }) {
75
+ const selected = checks.filter((c) => scope === 'all' || c.scope === scope);
76
+ const statusById = new Map();
77
+ const results = [];
78
+
79
+ for (const check of selected) {
80
+ const base = {
81
+ id: check.id,
82
+ title: check.title,
83
+ severity: check.severity || SEVERITY_FALLBACK,
84
+ scope: check.scope,
85
+ };
86
+
87
+ // Cascata: sem a dependência de pé, este probe não tem o que observar. Propaga por cadeia, não
88
+ // só um nível — `skipped` conta como "não verificado" para quem depende dele.
89
+ const depStatus = check.dependsOn ? statusById.get(check.dependsOn) : null;
90
+ if (depStatus === 'fail' || depStatus === 'skipped') {
91
+ const motivo = depStatus === 'fail' ? 'que falhou' : 'que não foi verificado';
92
+ results.push({
93
+ ...base,
94
+ status: 'skipped',
95
+ detail: `não verificado: depende de "${check.dependsOn}", ${motivo}`,
96
+ fix: null,
97
+ });
98
+ statusById.set(check.id, 'skipped');
99
+ continue;
100
+ }
101
+
102
+ const probe = await runProbe(check, env);
103
+ statusById.set(check.id, probe.status);
104
+ results.push({ ...base, ...probe });
105
+ }
106
+
107
+ return results;
108
+ }
109
+
110
+ /**
111
+ * Veredito agregado. Só `critical` reprova — um gate que trava por aquilo que não impede trabalho
112
+ * é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
113
+ *
114
+ * @param {Result[]} results
115
+ * @returns {'ok'|'warn'|'fail'}
116
+ */
117
+ export function worstStatus(results) {
118
+ let seenWarn = false;
119
+
120
+ for (const r of results) {
121
+ if (r.status === 'fail' && r.severity === 'critical') return 'fail';
122
+ if (r.status === 'fail' || r.status === 'warn') seenWarn = true;
123
+ }
124
+
125
+ return seenWarn ? 'warn' : 'ok';
126
+ }
127
+
128
+ /**
129
+ * Remove template literals do fonte antes de qualquer análise estática de `import`.
130
+ *
131
+ * Os geradores do Forja *escrevem* código NestJS dentro de crases — `import { Module } from
132
+ * '@nestjs/common'` é texto que eles emitem, não dependência que eles usam. Contá-lo faz o check
133
+ * acusar `@nestjs/core` como dependência não declarada e `./app.module` como import quebrado.
134
+ * Observado em campo ao auditar o tarball da 1.1.3.
135
+ */
136
+ export function stripTemplateLiterals(source) {
137
+ return source.replace(/`(?:\\.|[^`\\])*`/gs, '``');
138
+ }