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.
@@ -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,96 +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`. Quatro 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
- 3. **Dependência declarada e nunca importada** — não quebra nada, mas todo mundo que
21
- instala baixa peso morto.
22
- 4. **Árvore suja no momento do publish** — `npm publish` empacota o **disco**, não o commit.
23
- Qualquer arquivo alterado e não commitado entra no tarball, e o que foi publicado deixa
24
- de corresponder à tag de release.
25
-
26
- Grep e leitura de código não provam ausência das três primeiras. Instalação prova.
27
- A quarta nenhuma instalação pega: só o `git status` pega, e só se rodado no instante certo.
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**.
28
18
 
29
19
  ## Procedimento
30
20
 
31
- 0. **Exija árvore limpa, antes de tudo.** Se houver qualquer modificação não commitada,
32
- reprove imediatamente e pare — não adianta auditar um tarball que não é o que será
33
- publicado.
34
-
35
- ```bash
36
- git status --short # qualquer saída = reprovado
37
- git describe --tags --exact-match # HEAD deve estar na tag de release
38
- ```
39
-
40
- Um `npm install` casual entre a auditoria e o `npm publish` já basta para reescrever o
41
- `package.json` do disco. Foi assim que `otplib` e `qrcode` entraram na v1.1.1 publicada
42
- sem jamais existirem no git (ADR-0021).
43
-
44
- 1. **Empacote e instale de verdade**, num diretório temporário fora do repo:
45
-
46
- ```bash
47
- npm pack --pack-destination /tmp/forja-audit
48
- cd /tmp/forja-audit && npm init -y && npm i ./forjajs-<versão>.tgz
49
- ```
50
-
51
- 2. **Exercite cada comando do registry**, não só o help. O help não carrega os scripts —
52
- passa mesmo com tudo quebrado. Enumere os comandos e rode os que não têm efeito
53
- colateral (leitura, status, query):
21
+ ```bash
22
+ npm run release:check -- --publish
23
+ ```
54
24
 
55
- ```bash
56
- npx forja # lista os comandos
57
- npx forja query:universal teste
58
- npx forja code:status
59
- npx forja tools:doctor
60
- ```
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:
61
27
 
62
- Um `ERR_MODULE_NOT_FOUND` aqui é reprovação imediata.
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)* |
63
37
 
64
- 3. **Cruze imports contra `files[]`.** Para cada binário em `bin/`, siga os imports
65
- transitivamente e confirme que todo path resolvido cai sob um prefixo listado em
66
- `files[]`. Reporte os que não caem.
38
+ `exit 0` = aprovado. `exit 1` = reprovado, com o motivo e a correção em cada linha.
67
39
 
68
- 4. **Confira a fronteira deps/devDeps, nos dois sentidos.** Todo pacote importado por código
69
- sob `files[]` precisa estar em `dependencies`; `devDependencies` só pode ser importado por
70
- `test/` e por scripts não publicados. E toda entrada de `dependencies` precisa ser
71
- importada por alguém — declarada e nunca usada é peso morto no tarball de todo usuário.
40
+ ## Seu julgamento, que o gate não faz
72
41
 
73
- ```bash
74
- # para cada dep declarada, prove que alguém a importa
75
- node -e "console.log(Object.keys(require('./package.json').dependencies||{}).join('\n'))" |
76
- while read dep; do
77
- grep -rqE "from '$dep'|require\('$dep'\)" bin/ lib/ scripts/ ||
78
- echo "REPROVADO: '$dep' está em dependencies e ninguém a importa"
79
- done
80
- ```
42
+ O gate diz **o que** quebrou. Você diz **o que fazer com isso**:
81
43
 
82
- 5. **Reconfirme a árvore limpa ao final.** A auditoria só vale para o disco no instante em
83
- que rodou. Se algo mudou desde o passo 0, o resultado está vencido: recomece.
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.
84
53
 
85
54
  ## Regras
86
55
 
87
- - Output estruturado: ✓ aprovado / ✗ reprovado, com motivos numerados.
88
- - Nunca rode `npm publish`. Você audita; publicar é decisão do usuário.
89
- - Nunca aprove com base em leitura de código. Se você não instalou o tarball e rodou
90
- um comando real, você não sabe — diga que não sabe.
91
- - Sua aprovação é **perecível**: vale para aquele disco, naquele instante. Ao aprovar,
92
- diga explicitamente que qualquer `npm install`, `npm uninstall` ou edição posterior
93
- invalida o parecer e exige nova auditoria.
94
- - Limpe `/tmp/forja-audit` ao final.
95
- - Se reprovar, aponte a linha exata: o import ofensor, a entrada faltante no `files[]`,
96
- ou o arquivo sujo no `git status`.
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,90 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.1.5] — 2026-07-14 — O comando é forja
8
+
9
+ A documentação pública ainda falava a língua interna do repo: `npm run x -- args` onde o usuário
10
+ do pacote tem `forja x args`. Esta versão alinha o que o README promete com o que o binário faz.
11
+
12
+ ### Corrigido
13
+
14
+ - **README inteiro migrado para `forja` como forma canônica** — os scripts npm continuam
15
+ existindo como aliases do repo clonado, mas deixam de ser a vitrine.
16
+ - **Exemplos do "60 segundos" estavam quebrados**: `forja gsd:handoff -- plan …` passa o `--`
17
+ cru para o script (o core não filtra separador) e o comando falha. O `--` só era necessário
18
+ na forma `npm run`; removido dos exemplos diretos.
19
+ - **Comando errado na lista de essenciais**: validar projeto do workspace é
20
+ `workspace:project:check <nome>`, não `project:check <nome>` (que é o standards check do framework).
21
+ - **Links mortos**: `projects/ai-engineering-from-scratch-main/` não existe no repo;
22
+ `docs/capacidades-externas.md` agora aponta para as fontes upstream (ADR-0016) e a
23
+ reinstalação segue a prescrição do `tools:doctor` (`npm i -g @codegraph/cli`) em vez do
24
+ symlink manual antigo.
25
+ - **`package-lock.json` preso em 1.1.3** desde o bump da 1.1.4; sincronizado.
26
+
27
+ ### Adicionado
28
+
29
+ - Seção "Comandos essenciais" do README ampliada com o que já existia no registry mas não
30
+ aparecia: `gsd:plan`/`gsd:check`, `code:check`/`code:impact`, `memory:compress`,
31
+ `tools:doctor`, `release:check --publish`.
32
+ - `allowScripts` no `package.json`: instalações com política allow-scripts ativa deixam de
33
+ bloquear silenciosamente o prebuild do `better-sqlite3` — exatamente o modo de falha que
34
+ matava a memória (ADR-0023).
35
+
36
+ ---
37
+
38
+ ## [1.1.4] — 2026-07-14 — Os gates
39
+
40
+ Duas fronteiras do framework funcionavam por disciplina, e a disciplina falhou nas duas. Esta versão
41
+ as fecha com gates executáveis — e, pela primeira vez, com **prova**: os bugs históricos foram
42
+ reintroduzidos um a um, e o gate reprovou cada um deles.
43
+
44
+ > "Uma regra que depende de memória não é uma regra; é uma sugestão." — ADR-0021
45
+
46
+ ### O que muda para quem usa
47
+
48
+ - **`npm publish` está bloqueado** se a instalação limpa não funcionar (`prepublishOnly` → ADR-0024).
49
+ - **`tools:doctor` reprova** (exit 1) quando o núcleo está quebrado — antes ele auditava só
50
+ ferramentas opcionais e saía com 0 mesmo com a memória morta (ADR-0023).
51
+ - Quando algo quebra, a saída traz **o comando que corrige**, não um stack trace.
52
+
53
+ ### Adicionado
54
+
55
+ - **`lib/core/health.mjs`** — saúde do núcleo como dados: ABI do `better-sqlite3`, memória, índice,
56
+ workspace, `engines`, deps de runtime, `.mcp.json`. Fonte única do `tools:doctor` e do hook
57
+ `SessionStart` (ADR-0023).
58
+ - **`lib/core/release.mjs` + `release:check`** — o gate do tarball. Empacota, instala num diretório
59
+ isolado e **executa** os comandos. Grep não prova ausência; instalação prova (ADR-0024).
60
+ - **`lib/core/checks.mjs`** — runner compartilhado. Uma máquina, dois catálogos: um guarda o repo,
61
+ outro guarda o pacote publicado.
62
+ - **CI**: `tools:doctor` na matriz de Nodes e `release:check` em job próprio. A evidência do release
63
+ passa a viver no log do CI, não na memória de quem publica.
64
+ - `spec:new` mantém a allow-list do `.gitignore` — toda spec nova do framework nascia invisível ao git.
65
+
66
+ ### Corrigido
67
+
68
+ - **A memória morria em silêncio.** Com o `better-sqlite3` compilado contra outra major do Node,
69
+ `query:universal`, `sync:universal`, `context:smart`, `agent:route` e `memory:compress` ficavam
70
+ todos inoperantes — e o `SessionStart` prescrevia `npm install`, que **não** recompila binário
71
+ nativo. A correção é `npm rebuild better-sqlite3`, e agora é isso que o framework diz.
72
+ - **`docs/token-optimization.md` mandava rodar quatro comandos inexistentes** (`context:build`,
73
+ `memory:db:reindex`, `memory:db:stats`, `cache:clear`) e linkava um `DEPLOYMENT.md` que nunca
74
+ existiu. É o documento que ensina a economia de tokens (ADR-0009) — um agente obediente executava
75
+ fantasmas.
76
+ - **O Governance não conhecia os gates**: descrevia o `tools:doctor` pela definição anterior ao
77
+ ADR-0023 e ignorava o `release:check`.
78
+ - `runtime-deps` passava por sorte: os geradores emitem `import … from '@nestjs/common'` dentro de
79
+ template literal, e o parser contava como dependência do framework.
80
+
81
+ ### Evidência
82
+
83
+ | Bug histórico | Reintroduzido → |
84
+ |---|---|
85
+ | `better-sqlite3` como `devDependency` (ADR-0021) | reprovado por **dois** checks independentes |
86
+ | `dashboard/` fora do `files[]` (v1.1.3) | reprovado: 4 comandos mortos, 19 imports sem destino |
87
+ | `otplib`/`qrcode` publicados sem existir no git (v1.1.1) | reprovado sob `--publish`; `npm publish` aborta |
88
+
89
+ **88 testes** (eram 28). ADR-0023 e ADR-0024. SPEC-009 e SPEC-010.
90
+
7
91
  ## [1.1.3] — 2026-07-09 — Dashboard congelado
8
92
 
9
93
  SPEC-002 (`specs/agent-dashboard/`) passa a `abandoned`. O código permanece em `dashboard/`,
package/README.md CHANGED
@@ -51,15 +51,15 @@ principal força de trabalho — e precisa da disciplina de um time grande sem t
51
51
  $ forja spec:new pagamentos-pix
52
52
  ✓ Spec criada: specs/pagamentos-pix/spec.md # nada vira código sem isso
53
53
 
54
- $ forja gsd:handoff -- plan pagamentos-pix
54
+ $ forja gsd:handoff plan pagamentos-pix
55
55
  Handoff registrado: product → sdd-architect # 7 campos, auditável (ADR-0005)
56
56
 
57
- $ forja code:impact -- processPayment
57
+ $ forja code:impact processPayment
58
58
  Mapa de impacto: processPayment (profundidade 2) # blast radius ANTES de editar
59
59
  --- Chamadores diretos ---
60
60
  BillingController.charge · RetryWorker.run
61
61
 
62
- $ forja gsd:check -- pagamentos-pix
62
+ $ forja gsd:check pagamentos-pix
63
63
  OK GSD runbook OK Spec directory
64
64
  OK SDD spec check OK Codegraph
65
65
  Resultado: gates básicos prontos. # governança executável, não checklist
@@ -90,31 +90,30 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
90
90
  # Instalar (o pacote é forjajs; o comando é forja)
91
91
  npm install -g forjajs
92
92
  forja # help agrupado por domínio
93
- ```
94
-
95
- Ou clonando o repo:
96
93
 
97
- ```bash
98
94
  # Preparar o workspace de produção (canto fixo dos projetos)
99
- npm run workspace:init
95
+ forja workspace:init
100
96
 
101
97
  # Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
102
- npm run project:new meu-projeto -- --ai claude,copilot
98
+ forja project:new meu-projeto --ai claude,copilot
103
99
 
104
100
  # Entrar no ciclo SDD/GSD da primeira feature
105
- npm run spec:new -- minha-feature
106
- npm run spec:plan -- minha-feature
107
- npm run spec:tasks -- minha-feature
108
- npm run spec:check -- minha-feature
101
+ forja spec:new minha-feature
102
+ forja spec:plan minha-feature
103
+ forja spec:tasks minha-feature
104
+ forja spec:check minha-feature
109
105
  ```
110
106
 
107
+ > Clonou o repo em vez de instalar? Os mesmos comandos rodam como
108
+ > `node bin/forja.mjs <comando>` — os scripts npm são apenas aliases finos do core.
109
+
111
110
  Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
112
111
 
113
112
  ## Como funciona — o processo
114
113
 
115
114
  ```
116
115
  💡 Demanda
117
- ├─ projeto NÃO existe ─► init:project + boilerplate + harness (desenha o time)
116
+ ├─ projeto NÃO existe ─► project:new + boilerplate + harness (desenha o time)
118
117
  └─ projeto JÁ existe ──► overlay --only-memory + codegraph init (entende o código)
119
118
  │
120
119
  ▼
@@ -137,9 +136,9 @@ Mapa completo do ciclo: [`docs/fluxo.md`](docs/fluxo.md).
137
136
 
138
137
  | Capacidade | Papel | Como usar |
139
138
  |---|---|---|
140
- | **codegraph** | análise de código (MCP local) | `npm run code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
139
+ | **codegraph** | análise de código (MCP local) | `forja code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
141
140
  | **harness** | desenho de times de agentes (plugin) | na sessão Claude Code: _"build a harness for this project"_ → gera `.claude/agents` + `.claude/skills` |
142
- | **ai-engineering** | base de conhecimento (referência) | `projects/ai-engineering-from-scratch-main/` (ROADMAP, phases, glossary) |
141
+ | **ai-engineering** | base de conhecimento (referência) | ver [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
143
142
 
144
143
  Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
145
144
 
@@ -148,43 +147,49 @@ Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-ext
148
147
  Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):
149
148
 
150
149
  ```bash
151
- node bin/forja.mjs # help agrupado por domínio
152
- node bin/forja.mjs <comando> # ou, com o pacote linkado: forja <comando>
150
+ forja # help agrupado por domínio
151
+ forja <comando> [args] # no repo clonado: node bin/forja.mjs <comando>
153
152
  ```
154
153
 
155
154
  O core aplica **gates** antes de executar (ex.: comandos de produto falham cedo sem
156
155
  workspace) e grava **auditoria** de cada execução (comando, args, exit code, duração)
157
156
  em `<workspace>/.context/forja-runs.jsonl` — a trilha que a governança usa no review.
158
- Os scripts npm abaixo são aliases finos que roteiam pelo core.
157
+ Os scripts npm do repo são aliases finos que roteiam pelo core.
159
158
 
160
159
  ## Comandos essenciais
161
160
 
162
161
  ```bash
163
162
  # Workspace & projetos
164
- npm run workspace:init # cria ~/forja-workspace
165
- npm run project:new <nome> -- --ai claude,copilot # cria projeto no workspace
166
- npm run project:list # lista projetos do workspace
167
- npm run project:check <nome> # valida padrões no projeto
163
+ forja workspace:init # cria ~/forja-workspace
164
+ forja project:new <nome> --ai claude,copilot # cria projeto no workspace
165
+ forja project:list # lista projetos do workspace
166
+ forja workspace:project:check <nome> # valida padrões num projeto do workspace
168
167
 
169
168
  # Pipeline SDD
170
- npm run spec:new|plan|tasks|check -- <slug>
169
+ forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
171
170
 
172
171
  # Sprint & handoffs (GSD)
173
- npm run sprint:start | sprint:status | sprint:complete
174
- npm run gsd:handoff -- <intent> <slug> # handoff entre papéis (ADR-0005)
172
+ forja sprint:start # também: sprint:status · sprint:complete
173
+ forja gsd:plan <slug> # runbook GSD em .context/
174
+ forja gsd:handoff <intent> <slug> # handoff entre papéis (ADR-0005)
175
+ forja gsd:check <slug> # gates básicos do runbook
175
176
 
176
177
  # Análise de código (codegraph)
177
- npm run code:index | code:sync | code:status
178
- npm run code:query "<termo>"
178
+ forja code:check # índice confiável (worktree + freshness)
179
+ forja code:impact <símbolo> # chamadores + blast radius antes de editar
180
+ forja code:query "<termo>" # também: code:index · code:sync · code:status
179
181
 
180
182
  # Memória & contexto (workspace)
181
- npm run sync:universal # reindexa SQLite FTS5 do workspace
182
- npm run query:universal "<query>"
183
- npm run context:smart # smart-context
184
-
185
- # Qualidade & visão
186
- npm run project:check # standards do framework
187
- npm run project:dashboard # relatório estático de status
183
+ forja sync:universal # reindexa SQLite FTS5 do workspace
184
+ forja query:universal "<query>" # busca FTS5
185
+ forja context:smart # smart-context (3 modos, ADR-0003)
186
+ forja memory:compress # arquiva runs antigos + VACUUM
187
+
188
+ # Qualidade & release
189
+ forja project:check # standards do framework (pre-commit)
190
+ forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
191
+ forja release:check --publish # gate do tarball antes de publicar
192
+ forja project:dashboard # relatório estático de status
188
193
  ```
189
194
 
190
195
  ## 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` |
@@ -1,38 +1,47 @@
1
1
  # Capacidades externas integradas
2
2
 
3
- Três produtos open-source foram alocados ao `2-projeto-agents` como capacidades de
3
+ Três produtos open-source foram integrados ao framework como capacidades de
4
4
  primeira classe (ver [ADR-0016](../memory/90-decisions/0016-integracao-capacidades-externas.md)).
5
- Antigamente viviam em `projects/`; agora estão no workspace Forja
6
- (`~/forja-workspace`, configurável — ver [ADR-0019](../memory/90-decisions/0019-workspace-separado.md)).
7
- Aqui ficam só a fiação e o modo de uso.
5
+ Os produtos em si **não são versionados neste repo** — são instalados por máquina.
6
+ O que o repo versiona é a **fiação**: `.mcp.json` (servidor MCP do codegraph),
7
+ os comandos `code:*` no registry do core e este guia. O estado da instalação na
8
+ sua máquina é reportado por `forja tools:doctor`.
9
+
10
+ | Capacidade | Eixo | Fonte |
11
+ |---|---|---|
12
+ | **codegraph** | análise de código (MCP + CLI) | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) |
13
+ | **harness** | desenho de times de agentes (plugin Claude Code) | [revfactory/harness](https://github.com/revfactory/harness) |
14
+ | **ai-engineering-from-scratch** | base de conhecimento (referência) | [rohitg00/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) |
8
15
 
9
16
  ## 1. codegraph — análise de código (MCP)
10
17
 
11
18
  Grafo de código semântico, 100% local. Registrado como **servidor MCP** no repo
12
- (`.mcp.json`) e disponível no PATH (`~/.local/bin/codegraph`).
19
+ (`.mcp.json`, comando `codegraph serve --mcp`) — quem clona o repo herda o registro;
20
+ basta ter o binário `codegraph` no PATH.
13
21
 
14
22
  **Ferramentas MCP** (aparecem automaticamente em sessões Claude Code neste repo):
15
23
  - `codegraph_explore` — símbolos relevantes + call paths de uma área, num disparo só.
16
24
  - `codegraph_node` — fonte de um símbolo + trilha de callers/callees, ou leitura de arquivo.
17
25
 
18
- **CLI / npm scripts:**
26
+ **CLI (via core `forja`):**
19
27
  ```bash
20
- npm run code:index # codegraph init — constrói o índice inicial (respeita .gitignore)
21
- npm run code:sync # sincroniza mudanças desde o último índice
22
- npm run code:status # status e estatísticas do índice
23
- npm run code:query "<termo>" # busca símbolos
24
- codegraph explore "<query>" # exploração ad-hoc
25
- codegraph callers <símbolo> # quem chama um símbolo
28
+ forja code:index # codegraph init — constrói o índice inicial (respeita .gitignore)
29
+ forja code:sync # sincroniza mudanças desde o último índice
30
+ forja code:status # status e estatísticas do índice
31
+ forja code:query "<termo>" # busca símbolos
32
+ forja code:check # gate: índice confiável (worktree + freshness, ADR-0017)
33
+ forja code:impact <símbolo> # chamadores + blast radius antes de editar
34
+ codegraph explore "<query>" # exploração ad-hoc direto no binário
35
+ codegraph callers <símbolo> # quem chama um símbolo
26
36
  ```
27
37
 
28
- O índice fica em `.codegraph/` (já coberto por `.gitignore` do projeto, se necessário).
38
+ O índice fica em `.codegraph/` (coberto pelo `.gitignore` do projeto).
29
39
 
30
40
  ## 2. harness — orquestração de times de agentes (plugin)
31
41
 
32
- Plugin do Claude Code (`harness@harness-marketplace`, instalado e habilitado) que
33
- transforma uma descrição de domínio em um time de agentes + skills, a partir de 6
34
- padrões: Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor,
35
- Hierarchical Delegation.
42
+ Plugin do Claude Code (`harness@harness-marketplace`) que transforma uma descrição
43
+ de domínio em um time de agentes + skills, a partir de 6 padrões: Pipeline,
44
+ Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation.
36
45
 
37
46
  **Uso:** numa sessão Claude Code, peça _"build a harness for this project"_ (ou
38
47
  _"configure um harness para X"_) e ele gera `.claude/agents/` e `.claude/skills/`
@@ -46,25 +55,32 @@ claude plugin update harness@harness-marketplace
46
55
  ```
47
56
 
48
57
  Complementa o sistema de orquestração nativo do framework (AGENTS.md, handoffs,
49
- `scripts/agent-router.mjs`): harness ajuda a *desenhar* novos times; o framework
50
- *opera* os handoffs.
58
+ `forja gsd:handoff` / `forja agent:route`): harness ajuda a *desenhar* novos times;
59
+ o framework *opera* os handoffs.
51
60
 
52
61
  ## 3. ai-engineering-from-scratch — base de conhecimento (referência)
53
62
 
54
63
  Currículo de AI engineering: 503 lições, 20 fases, 4 linguagens (Python, TypeScript,
55
64
  Rust, Julia). Material de referência para fundamentar decisões técnicas de IA do
56
- framework. Não há instalação — consultar diretamente:
65
+ framework. Não há instalação nem fiação — consultar direto no repositório upstream:
66
+
67
+ - [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) — índice das 20 fases.
68
+ - `phases/` — lições por fase.
69
+ - `glossary/` — glossário.
57
70
 
58
- - `projects/ai-engineering-from-scratch-main/ROADMAP.md` — índice das 20 fases.
59
- - `projects/ai-engineering-from-scratch-main/phases/` — lições por fase.
60
- - `projects/ai-engineering-from-scratch-main/glossary/` — glossário.
71
+ ## Instalação / reinstalação
61
72
 
62
- ## Reinstalação
73
+ O `forja tools:doctor` diz o que falta e como instalar. Para as capacidades deste guia:
63
74
 
64
- Se `projects/` for limpo, recriar a fiação:
65
75
  ```bash
66
- ln -sf "$PWD/projects/codegraph-linux-x64/bin/codegraph" ~/.local/bin/codegraph
67
- claude mcp add codegraph --scope project -- codegraph serve --mcp
68
- claude plugin marketplace add "$PWD/projects/harness-main"
76
+ # codegraph — binário no PATH (o .mcp.json versionado faz o resto)
77
+ npm i -g @codegraph/cli
78
+
79
+ # harness — clonar o repo e registrar como marketplace local
80
+ git clone https://github.com/revfactory/harness ~/tools/harness
81
+ claude plugin marketplace add ~/tools/harness
69
82
  claude plugin install harness@harness-marketplace
70
83
  ```
84
+
85
+ Depois, confira com `forja tools:doctor` (codegraph) e `claude plugin list` (harness).
86
+ Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.