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.
- package/.claude/agents/governance.md +33 -10
- package/.claude/agents/release-auditor.md +44 -77
- package/CHANGELOG.md +84 -0
- package/README.md +40 -35
- package/docs/agent-harnesses.md +30 -3
- package/docs/capacidades-externas.md +44 -28
- 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/0023-doctor-como-gate-do-nucleo.md +114 -0
- package/memory/90-decisions/0024-gate-do-tarball.md +103 -0
- package/package.json +7 -1
- 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 +75 -11
- 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/release-gate/plan.md +174 -0
- package/specs/release-gate/spec.md +122 -0
- package/specs/release-gate/tasks.md +183 -0
|
@@ -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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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 (
|
|
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.
|
|
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
|
-
|
|
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
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
|
|
56
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
83
|
-
|
|
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
|
-
-
|
|
88
|
-
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
95
|
+
forja workspace:init
|
|
100
96
|
|
|
101
97
|
# Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
|
|
102
|
-
|
|
98
|
+
forja project:new meu-projeto --ai claude,copilot
|
|
103
99
|
|
|
104
100
|
# Entrar no ciclo SDD/GSD da primeira feature
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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 ─►
|
|
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) | `
|
|
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) | `
|
|
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
|
-
|
|
152
|
-
|
|
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
|
|
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
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
-
|
|
169
|
+
forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
|
|
171
170
|
|
|
172
171
|
# Sprint & handoffs (GSD)
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
178
|
-
|
|
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
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
package/docs/agent-harnesses.md
CHANGED
|
@@ -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
|
-
##
|
|
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
|
|
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
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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`)
|
|
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
|
|
26
|
+
**CLI (via core `forja`):**
|
|
19
27
|
```bash
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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/` (
|
|
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
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
`
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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.
|