forjajs 5.1.0 → 5.3.0
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/CHANGELOG.md +76 -0
- package/README.md +37 -4
- package/README.pt-BR.md +39 -4
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +349 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +26 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/project-wiring.js +6 -2
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +20 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +99 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +7 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/skills/testing/SKILL.md +1 -1
|
@@ -736,10 +736,11 @@ Nao use design como etapa obrigatoria para:
|
|
|
736
736
|
- Checks.
|
|
737
737
|
- Refatoracoes sem interface.
|
|
738
738
|
|
|
739
|
-
Dashboard:
|
|
739
|
+
Dashboard (dois terminais; tokens em `docs/produto/roteiro-demo.md`):
|
|
740
740
|
|
|
741
741
|
```bash
|
|
742
|
-
npm run dashboard
|
|
742
|
+
npm run dashboard:api # API em 127.0.0.1:3000
|
|
743
|
+
npm run dashboard:dev # app em http://localhost:3001
|
|
743
744
|
```
|
|
744
745
|
|
|
745
746
|
Use somente para consulta visual ou depuracao de telas. Nao trate como fonte primaria de operacao.
|
|
@@ -133,11 +133,13 @@ supervisionada, governança e memória em uma trilha auditável.
|
|
|
133
133
|
|
|
134
134
|
## Estado das superfícies visuais
|
|
135
135
|
|
|
136
|
-
- **Dashboard 2.x:** superfície de supervisão
|
|
137
|
-
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
não dados de demonstração inventados.
|
|
136
|
+
- **Dashboard 2.x (`apps/dashboard`):** superfície de supervisão via API; não é requisito do fluxo
|
|
137
|
+
CLI-first. O dashboard React/Vite legado foi removido (ADR-0087). Em 2026-11-08 o app Next sobe com
|
|
138
|
+
`npm run dashboard:api` (API em `127.0.0.1:3000`) e `npm run dashboard:dev` (app em
|
|
139
|
+
`http://localhost:3001`), com cinco abas: Visão, Rastreio, Custo, Gates e Operação. Um workspace sem
|
|
140
|
+
projetos ou handoffs mostra coleções vazias, não dados de demonstração inventados.
|
|
141
|
+
- O painel só executa capacidades que o servidor declara como leitura sem efeito colateral, e o proxy
|
|
142
|
+
falha fechado: sem `FORJA_DASHBOARD_TOKEN` nenhuma requisição é encaminhada.
|
|
141
143
|
- O dashboard não executa LLMs diretamente: essa ação foi direcionada para `forja llm:run` para manter
|
|
142
144
|
policy, auditoria e privacidade.
|
|
143
145
|
|
|
@@ -17,11 +17,18 @@ app com o mesmo workspace (dois terminais):
|
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
19
|
npm --prefix apps/dashboard install
|
|
20
|
-
FORJA_WORKSPACE=~/forja-demo-workspace npm run dashboard:api # API
|
|
21
|
-
npm run dashboard:dev
|
|
20
|
+
FORJA_WORKSPACE=~/forja-demo-workspace FORJA_AUTH_TOKEN=local-demo npm run dashboard:api # API em 127.0.0.1:3000
|
|
21
|
+
FORJA_API_URL=http://127.0.0.1:3000 FORJA_API_TOKEN=local-demo FORJA_DASHBOARD_TOKEN=demo-local npm run dashboard:dev # app em http://localhost:3001
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
No Windows PowerShell, defina `$env:FORJA_WORKSPACE = "$HOME\forja-demo-workspace"`
|
|
24
|
+
No Windows PowerShell, defina `$env:FORJA_WORKSPACE = "$HOME\forja-demo-workspace"` e
|
|
25
|
+
`$env:FORJA_AUTH_TOKEN = "local-demo"` antes de `npm run dashboard:api`; no segundo terminal,
|
|
26
|
+
`$env:FORJA_API_URL`, `$env:FORJA_API_TOKEN = "local-demo"` e `$env:FORJA_DASHBOARD_TOKEN = "demo-local"`.
|
|
27
|
+
|
|
28
|
+
Ao abrir `http://localhost:3001` o painel pede o `FORJA_DASHBOARD_TOKEN` (`demo-local` acima) e guarda
|
|
29
|
+
um cookie de sessão. Os dois tokens são locais e descartáveis: `FORJA_API_TOKEN` é a credencial do
|
|
30
|
+
proxy para a API, `FORJA_DASHBOARD_TOKEN` é a de quem acessa o painel. Sem o segundo, o proxy recusa
|
|
31
|
+
toda requisição — não existe modo aberto.
|
|
25
32
|
|
|
26
33
|
O dashboard mostra o estado vazio apenas se a API não estiver recebendo a variável `FORJA_WORKSPACE`
|
|
27
34
|
do cenário.
|
|
@@ -32,8 +39,10 @@ do cenário.
|
|
|
32
39
|
estado do projeto, spec aprovada, plano, tarefas e a próxima ação com o comando exato.
|
|
33
40
|
2. `forja project:wire --check`: a IA, os hooks e o MCP estão conectados ao projeto.
|
|
34
41
|
3. `forja context:smart --mode task --task pix`: o pack mínimo da tarefa, com a contagem de tokens.
|
|
35
|
-
4. No dashboard (**Control Plane**): **
|
|
36
|
-
|
|
42
|
+
4. No dashboard (**Forja Control Plane**), cinco abas: **Visão** (próxima ação com o comando copiável,
|
|
43
|
+
sprint, specs e execuções recentes), **Rastreio** (cobertura de critérios de aceite por spec),
|
|
44
|
+
**Custo** (USD acumulado por modelo), **Gates** (veredito do núcleo e ferramentas) e **Operação**
|
|
45
|
+
(**Aprovações**, **GraphLoop** com impacto por nó e **Atividade recente** auditada).
|
|
37
46
|
5. Mostre `forja demo:autonomy` separadamente para a prova de sandbox Git, aprovação e promoção real.
|
|
38
47
|
|
|
39
48
|
## Regras de uso
|
package/docs/quick-reference.md
CHANGED
|
@@ -54,7 +54,6 @@ npm run project:new meu-projeto
|
|
|
54
54
|
# Com flags
|
|
55
55
|
npm run project:new meu-projeto -- --ai claude,copilot
|
|
56
56
|
npm run project:new meu-projeto -- --skip-backend
|
|
57
|
-
npm run project:new meu-projeto -- --verbose
|
|
58
57
|
|
|
59
58
|
# Dentro do projeto: conferir a conexão com a IA
|
|
60
59
|
forja project:wire --check
|
|
@@ -91,8 +90,9 @@ npm run start:prod
|
|
|
91
90
|
# Health check
|
|
92
91
|
curl http://localhost:3000/api/health
|
|
93
92
|
|
|
94
|
-
# Dashboard
|
|
95
|
-
npm run dashboard
|
|
93
|
+
# Dashboard opcional (dois terminais; ver docs/produto/roteiro-demo.md para os tokens)
|
|
94
|
+
npm run dashboard:api # API em 127.0.0.1:3000
|
|
95
|
+
npm run dashboard:dev # app em http://localhost:3001
|
|
96
96
|
```
|
|
97
97
|
|
|
98
98
|
---
|
|
@@ -59,7 +59,7 @@ Caps em `.memoryrc.json::hooks.userPromptCap` (default 4KB). Cache em `/tmp/fram
|
|
|
59
59
|
**Cost**: $0.0001 per request
|
|
60
60
|
|
|
61
61
|
```bash
|
|
62
|
-
|
|
62
|
+
forja context:smart --mode global --project my-project
|
|
63
63
|
```
|
|
64
64
|
|
|
65
65
|
---
|
|
@@ -79,7 +79,7 @@ node lib/context-builder.js global my-project
|
|
|
79
79
|
**Cost**: $0.005 per request
|
|
80
80
|
|
|
81
81
|
```bash
|
|
82
|
-
|
|
82
|
+
forja context:smart --mode domain --project my-project
|
|
83
83
|
```
|
|
84
84
|
|
|
85
85
|
---
|
|
@@ -97,9 +97,12 @@ node lib/context-builder.js domain my-project
|
|
|
97
97
|
**Cost**: $0.008 per request
|
|
98
98
|
|
|
99
99
|
```bash
|
|
100
|
-
|
|
100
|
+
forja context:smart --mode task --task "auth backend" --project my-project
|
|
101
101
|
```
|
|
102
102
|
|
|
103
|
+
Nó longo entra como **trecho casado** (especificado pelo `snippet()` do FTS5), não por inteiro; o rodapé do
|
|
104
|
+
pacote diz quantos nós vieram cortados, e `--full-context` traz a fatia inteira quando o corte atrapalha.
|
|
105
|
+
|
|
103
106
|
---
|
|
104
107
|
|
|
105
108
|
## 🧠 Smart Context - How It Works
|
|
@@ -360,11 +363,12 @@ nodes = nodes.slice(0, maxFiles); // Keep top N
|
|
|
360
363
|
### For Backend Worker
|
|
361
364
|
|
|
362
365
|
```javascript
|
|
363
|
-
import ContextBuilder from '../lib/context-builder.
|
|
366
|
+
import ContextBuilder from '../lib/context-builder.ts';
|
|
364
367
|
|
|
365
368
|
// On task start
|
|
366
369
|
const builder = new ContextBuilder(process.cwd(), dbPath);
|
|
367
|
-
const context = builder.build('task', 'my-project', 'backend auth');
|
|
370
|
+
const context = builder.build('task', 'my-project', 'backend auth'); // nós longos em trecho
|
|
371
|
+
const integral = builder.build('task', 'my-project', 'backend auth', { full: true });
|
|
368
372
|
const stats = builder.stats('task', 'my-project', 'backend auth');
|
|
369
373
|
|
|
370
374
|
console.log(`📊 Using ${stats.tokens} tokens (cost: $${stats.estimatedCost})`);
|
|
@@ -394,7 +398,7 @@ const context = builder.build('global', 'my-project');
|
|
|
394
398
|
## 📋 Pre-Flight Checklist
|
|
395
399
|
|
|
396
400
|
- [ ] `.memoryrc.json` created with token limits
|
|
397
|
-
- [ ] `lib/context-builder.
|
|
401
|
+
- [ ] `lib/context-builder.ts` integrated
|
|
398
402
|
- [ ] `scripts/compress-memory.mjs` tested
|
|
399
403
|
- [ ] Cache directory created: `.context/cache/`
|
|
400
404
|
- [ ] Archive directory created: `.memory/archive/`
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# ADR-0091: Memória de sessão por hooks (Stop, PreCompact, SessionStart)
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-10-21
|
|
5
|
+
- **Autor(es)**: Allan Pablo / Claude
|
|
6
|
+
- **Tags**: hooks, memory, claude-code
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O projeto conectado (ADR-0086) injeta contexto na entrada da sessão e do prompt, mas nada sai da sessão
|
|
11
|
+
para a memória. Na compactação a IA perde quais arquivos editou e qual spec seguia; a sessão seguinte
|
|
12
|
+
não sabe onde a anterior parou. O Claude Code expõe os eventos `Stop` (fim de cada turno), `PreCompact`
|
|
13
|
+
(antes de compactar) e `SessionStart` com `source` (`startup`, `resume`, `clear`, `compact`), todos com
|
|
14
|
+
o caminho do transcript JSONL.
|
|
15
|
+
|
|
16
|
+
## Decisão
|
|
17
|
+
|
|
18
|
+
1. **Um checkpoint determinístico por sessão** em `memory/60-runs/sessions/<data>-<id8>.md`, reescrito
|
|
19
|
+
por `forja hook:session-memory` no `Stop` e no `PreCompact`. Extraído do transcript sem LLM: título
|
|
20
|
+
da sessão, branch, arquivos editados, comandos `forja`, specs tocadas, assuntos de commit.
|
|
21
|
+
2. **Nada de texto livre**: prompts, comandos inteiros e saídas de ferramenta não entram. A memória é
|
|
22
|
+
commitada; um segredo colado no chat não pode ir parar no git.
|
|
23
|
+
3. **O SessionStart fecha o ciclo**: em `compact` devolve o checkpoint da própria sessão; em
|
|
24
|
+
`startup`/`resume`, uma linha sobre a última sessão.
|
|
25
|
+
4. **Só grava quando houve trabalho** (edição, comando forja ou commit), para a pasta não virar log de conversa.
|
|
26
|
+
|
|
27
|
+
## Alternativas consideradas
|
|
28
|
+
|
|
29
|
+
- **Resumo por LLM no PreCompact.** Rejeitada por ora: custa a cada compactação e o hook tem timeout
|
|
30
|
+
curto. O checkpoint determinístico pode alimentar um resumo depois.
|
|
31
|
+
- **Gravar no SQLite em vez de Markdown.** Rejeitada: `memory/` em Markdown já é indexado pelo
|
|
32
|
+
`sync:universal` e legível por qualquer IA; o banco é projeção.
|
|
33
|
+
- **Guardar os prompts (truncados).** Rejeitada pelo risco de segredo no git; o título gerado pelo
|
|
34
|
+
Claude Code descreve o assunto sem copiar o texto.
|
|
35
|
+
|
|
36
|
+
## Consequências
|
|
37
|
+
|
|
38
|
+
- Projetos conectados ganham dois hooks; `project:upgrade --apply` os adiciona a projetos existentes.
|
|
39
|
+
- O parser depende de um formato de transcript que não é contrato público: o que não reconhece é ignorado.
|
|
40
|
+
- Só o Claude Code se beneficia; as outras IAs seguem com o briefing do AGENTS.md.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# ADR-0092: Critérios de aceite ligados a testes pela citação no teste
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-10-21
|
|
5
|
+
- **Autor(es)**: Allan Pablo / Claude
|
|
6
|
+
- **Tags**: sdd, testes, governanca
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
As specs (ADR-0007) definem "pronto" em critérios `AC-N`, mas nada liga um critério ao teste que o
|
|
11
|
+
prova. Por costume, testes já citam `SPEC-029 AC-5` no nome ou num comentário, ou usam `AC-1:` num
|
|
12
|
+
arquivo dedicado a uma spec. Ninguém confere essa ligação.
|
|
13
|
+
|
|
14
|
+
## Decisão
|
|
15
|
+
|
|
16
|
+
1. **A ligação mora no teste**: citar `SPEC-NNN AC-N` (ou `<slug> AC-N`) no nome do teste ou num
|
|
17
|
+
comentário. `AC-N` sozinho vale quando o arquivo cita uma única spec. Não há arquivo de mapeamento
|
|
18
|
+
à parte, que envelheceria separado do teste.
|
|
19
|
+
2. **`forja spec:trace`** lê specs e testes e reporta critérios cobertos, sem teste e citações órfãs.
|
|
20
|
+
É estático: não roda os testes, então serve para qualquer stack.
|
|
21
|
+
3. **Gate opt-in**: `--strict` rejeita (exit 2) specs `approved`/`implementing`/`done` com lacunas.
|
|
22
|
+
Sem a flag, só informa, para não quebrar projetos com specs antigas.
|
|
23
|
+
|
|
24
|
+
## Alternativas consideradas
|
|
25
|
+
|
|
26
|
+
- **Tabela AC → teste dentro da spec.** Rejeitada: duplica a informação e envelhece quando o teste muda de nome.
|
|
27
|
+
- **Rodar os testes e mapear resultados por AC.** Rejeitada por ora: depende do executor de cada stack.
|
|
28
|
+
A citação estática já responde "existe teste?" e "a citação aponta para algo real?".
|
|
29
|
+
- **Gate obrigatório no `spec:check`.** Rejeitada: specs `done` antigas passariam a falhar de uma vez.
|
|
30
|
+
|
|
31
|
+
## Consequências
|
|
32
|
+
|
|
33
|
+
- Citar o critério vira parte de escrever o teste (AGENTS.md e skill `testing` ensinam).
|
|
34
|
+
- Uma citação no texto conta como cobertura, mesmo que o teste seja fraco; a revisão do teste segue humana.
|
|
35
|
+
- Fixtures que contêm citações de exemplo (`'SPEC-001 AC-1: …'` como dado de teste) contariam como
|
|
36
|
+
cobertura de uma spec real; ficam entre `spec-trace:off` e `spec-trace:on`. Achado no próprio Forja:
|
|
37
|
+
a SPEC-001 aparecia com 2/7 critérios cobertos só por fixtures.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# ADR-0093: Avaliações com agentes reais em projeto descartável
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-10-21
|
|
5
|
+
- **Autor(es)**: Allan Pablo / Claude
|
|
6
|
+
- **Tags**: llm, evals, qualidade, security
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Os testes do Forja provam que o projeto gerado tem instruções, skills, hooks e MCP no lugar. Não
|
|
11
|
+
provam que um agente real, lendo isso, segue o método. O `llm:run` roda os agentes somente leitura
|
|
12
|
+
(ADR-0090), o que impede avaliar tarefas que exigem escrever: registrar um ADR, criar uma spec,
|
|
13
|
+
escrever um teste.
|
|
14
|
+
|
|
15
|
+
## Decisão
|
|
16
|
+
|
|
17
|
+
1. **`forja eval:agents` é a única exceção à regra de somente leitura**, e só porque o alvo é
|
|
18
|
+
descartável: workspace e projeto criados num diretório temporário para a execução e apagados no
|
|
19
|
+
fim. Nunca roda no projeto do usuário.
|
|
20
|
+
2. **Escrita confinada pelo próprio agente**: Codex com sandbox `workspace-write` (projeto e workspace
|
|
21
|
+
descartáveis como raízes graváveis); Claude com `acceptEdits` (edições no diretório de trabalho e no
|
|
22
|
+
`--add-dir`), lista fechada de comandos Bash e teto de custo por caso.
|
|
23
|
+
3. **Casos são dados e a correção é determinística**: arquivos, comandos executados, resposta e
|
|
24
|
+
`spec:trace`. Sem juiz LLM, para que o resultado não oscile por causa do corretor.
|
|
25
|
+
4. **Sob demanda, fora do CI**: custa dinheiro e exige credenciais. O histórico em
|
|
26
|
+
`.context/agent-evals.jsonl` permite comparar versões do Forja, agentes e modelos.
|
|
27
|
+
|
|
28
|
+
## Alternativas consideradas
|
|
29
|
+
|
|
30
|
+
- **Avaliar só respostas em modo somente leitura.** Rejeitada: os comportamentos que importam
|
|
31
|
+
(ADR, spec, teste) são escritas.
|
|
32
|
+
- **Juiz LLM para corrigir.** Rejeitada por ora: adiciona custo e uma segunda fonte de variação.
|
|
33
|
+
- **Rodar no CI com credenciais de serviço.** Rejeitada: custo recorrente e segredos no CI para um
|
|
34
|
+
sinal que é útil antes de release, não a cada commit.
|
|
35
|
+
|
|
36
|
+
## Consequências
|
|
37
|
+
|
|
38
|
+
- Mudanças em AGENTS.md, skills e hooks podem ser medidas antes do release.
|
|
39
|
+
- Agentes não são determinísticos; um caso pode oscilar entre execuções, e o histórico mostra isso.
|
|
40
|
+
- O Claude roda com as configurações globais do usuário (não é um ambiente estéril).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forjajs",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.3.0",
|
|
4
4
|
"description": "ForjaJS é uma plataforma local-first para memória, contexto, governança e execução supervisionada de agentes de desenvolvimento",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -90,7 +90,9 @@
|
|
|
90
90
|
"dashboard:start": "npm --prefix apps/dashboard run start",
|
|
91
91
|
"build": "tsc -p tsconfig.build.json && node -e \"for (const f of Object.values(require('./package.json').bin)) require('fs').chmodSync(f, 0o755)\"",
|
|
92
92
|
"types:check": "tsc --noEmit",
|
|
93
|
-
"
|
|
93
|
+
"docs:gen": "node bin/forja.ts docs:gen",
|
|
94
|
+
"test": "node --test --import ./test/isolate-workspace.mjs test/*.test.js",
|
|
95
|
+
"test:coverage": "node bin/forja.ts quality:coverage",
|
|
94
96
|
"demo:autonomy": "node bin/forja.ts demo:autonomy",
|
|
95
97
|
"demo:workspace": "node bin/forja.ts demo:workspace",
|
|
96
98
|
"benchmark:context": "node bin/forja.ts benchmark:context",
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Spec: avaliacoes-de-agentes
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-054
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0090](../../memory/90-decisions/0090-adapters-de-agente-somente-leitura.md) (adapters somente leitura), ADR-0093 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O Forja promete que, num projeto conectado, a IA segue o método: registra ADR em
|
|
12
|
+
`memory/90-decisions/`, cria spec com `forja spec:new`, liga teste a critério, consulta a memória antes
|
|
13
|
+
de responder. Os testes provam que os arquivos (AGENTS.md, skills, hooks, MCP) estão no lugar, mas
|
|
14
|
+
nada prova que um agente de verdade, lendo esses arquivos, faz a coisa certa. Uma mudança no
|
|
15
|
+
AGENTS.md ou numa skill pode piorar o comportamento sem nenhum teste ficar vermelho. O `llm:eval`
|
|
16
|
+
agrega execuções do `llm:run`, que é somente leitura e não tem tarefa nem gabarito. Medição hoje:
|
|
17
|
+
nenhuma.
|
|
18
|
+
|
|
19
|
+
## 2. Proposta de valor
|
|
20
|
+
`forja eval:agents` roda uma suíte fixa de tarefas com um agente real (Claude Code ou Codex) num
|
|
21
|
+
projeto Forja descartável e corrige cada uma de forma determinística, olhando o que ficou no disco,
|
|
22
|
+
os comandos executados e a resposta. O resultado vira histórico, comparado com a execução anterior
|
|
23
|
+
do mesmo agente e modelo.
|
|
24
|
+
|
|
25
|
+
## 3. User stories
|
|
26
|
+
- **Como** mantenedor do Forja, **quero** saber se uma mudança no AGENTS.md ou numa skill piorou o
|
|
27
|
+
comportamento dos agentes, **para que** a regressão apareça antes do release.
|
|
28
|
+
- **Como** usuário escolhendo entre Claude e Codex, **quero** ver qual segue melhor o método do Forja, **para que** a escolha tenha evidência.
|
|
29
|
+
- **Como** dono da máquina, **quero** que o agente avaliado só escreva no projeto descartável e que o custo tenha teto, **para que** rodar a suíte não tenha efeito colateral.
|
|
30
|
+
|
|
31
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
32
|
+
- [ ] AC-1: `forja eval:agents [--agent claude|codex] [--case a,b] [--model m] [--budget-usd n] [--json]` cria um workspace e um projeto descartáveis (`project:new --ai claude,codex`), aplica a semente de cada caso, roda o agente no projeto e corrige; o `forja` que o agente chama é o da instalação em teste.
|
|
33
|
+
- [ ] AC-2: os casos são dados (`templates/evals/agents/*.json`: id, prompt, semente, checks) e os checks são determinísticos: arquivo por glob com conteúdo, resposta, comando executado, critério coberto (`spec:trace`), comando que passa e arquivos inalterados.
|
|
34
|
+
- [ ] AC-3: a suíte inicial cobre ADR no lugar certo, spec criada pelo `spec:new`, teste que cita `SPEC-NNN AC-N`, resposta tirada da memória do projeto e próxima ação via `forja next`/`status`.
|
|
35
|
+
- [ ] AC-4: o agente só escreve no projeto e no workspace descartáveis: Codex com `-s workspace-write` (`-C` projeto, `--add-dir` workspace); Claude com `--permission-mode acceptEdits`, lista fechada de comandos Bash e `--max-budget-usd` por caso.
|
|
36
|
+
- [ ] AC-5: o resultado (por caso e por check, custo, duração) é anexado a `<workspace>/.context/agent-evals.jsonl` e comparado com a última execução do mesmo agente e modelo (casos que passaram a falhar ou a passar).
|
|
37
|
+
- [ ] AC-6: exit 0 quando todos os casos passam, 2 (`rejected`) quando algum falha, 1 quando o agente não está instalado ou o caso não existe; `--json` segue o contrato (ADR-0082).
|
|
38
|
+
- [ ] AC-7: o runner e os checks são testados offline com um agente falso; nenhum teste da suíte chama um provedor real.
|
|
39
|
+
|
|
40
|
+
## 5. Requisitos não-funcionais
|
|
41
|
+
- **Custo**: teto por caso (`--budget-usd`, padrão 1,00 no Claude); timeout por caso (padrão 300 s) nos dois.
|
|
42
|
+
- **Segurança**: nada fora dos diretórios descartáveis; o workspace real do usuário só recebe a linha de histórico.
|
|
43
|
+
- **Reprodutibilidade**: o histórico registra versão do Forja, agente, modelo e versão da CLI.
|
|
44
|
+
|
|
45
|
+
## 6. Fora de escopo
|
|
46
|
+
- Rodar no CI (custa e exige credenciais); fica sob demanda.
|
|
47
|
+
- Gemini, Cursor, opencode e Copilot CLI (entram com adapters de escrita confinada depois).
|
|
48
|
+
- Correção por LLM (juiz); só checks determinísticos.
|
|
49
|
+
|
|
50
|
+
## 7. Riscos e dependências
|
|
51
|
+
- Agentes não são determinísticos: um caso pode oscilar. O histórico mostra a oscilação; `--repeat` fica para depois.
|
|
52
|
+
- O Claude usa as configurações globais do usuário (hooks, plugins) além das do projeto; é o ambiente real, mas não é estéril.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Spec: criterios-ligados-a-testes
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-053
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0007](../../memory/90-decisions/0007-sdd-pipeline.md) (SDD), ADR-0092 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
Uma spec diz o que é "pronto" nos critérios de aceite (`AC-N`), mas nada liga um critério ao teste
|
|
12
|
+
que o prova. Uma spec vira `done` com critérios sem teste, e um critério renumerado deixa testes
|
|
13
|
+
apontando para o critério errado, sem ninguém notar. A convenção existe por costume (`SPEC-029 AC-5`
|
|
14
|
+
no nome do teste), mas ninguém a confere. Medição hoje: não sabemos quantos ACs têm teste.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
`forja spec:trace` mostra, para cada critério de cada spec, os testes que o citam, e aponta os
|
|
18
|
+
critérios sem teste e as citações órfãs. Com `--strict`, vira gate para specs aprovadas ou prontas.
|
|
19
|
+
|
|
20
|
+
## 3. User stories
|
|
21
|
+
- **Como** governance, **quero** ver quais critérios de uma spec `done` não têm teste, **para que** "pronto" signifique provado.
|
|
22
|
+
- **Como** dev, **quero** saber que citar `SPEC-053 AC-2` no nome do teste basta, **para que** a ligação não custe nada.
|
|
23
|
+
- **Como** dev que editou a spec, **quero** ser avisado de testes citando um critério que não existe mais, **para que** a rastreabilidade não minta.
|
|
24
|
+
|
|
25
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
26
|
+
- [ ] AC-1: `forja spec:trace [slug]` lista cada `AC-N` da spec e os testes que o citam (arquivo:linha), e resume `N/M critérios com teste`.
|
|
27
|
+
- [ ] AC-2: um teste cita um critério escrevendo `SPEC-NNN AC-N`, `<slug> AC-N` ou listas (`SPEC-029 AC-5/AC-6`, `AC-1, AC-2`); `AC-N` sozinho vale para a spec quando o arquivo de teste cita uma única spec (pelo ID, pelo slug, por `specs/<slug>/` ou pelo nome do arquivo, `<slug>.test.js`) e o critério existe nela; senão, é listado como ambíguo.
|
|
28
|
+
- [ ] AC-3: citação qualificada de critério inexistente (`SPEC-053 AC-9` sem AC-9) aparece como órfã.
|
|
29
|
+
- [ ] AC-4: arquivos de teste são achados em qualquer stack (`*.test.*`, `*.spec.*`, `test_*.py`, `*_test.go`, pastas `test/`, `tests/`, `__tests__/`), ignorando `node_modules`, `dist`, `.git` e `coverage`.
|
|
30
|
+
- [ ] AC-5: `--strict` sai com 2 (`rejected`) quando uma spec `approved`, `implementing` ou `done` tem critério sem teste ou citação órfã; sem `--strict` o comando só informa (exit 0). `--json` segue o contrato (ADR-0082).
|
|
31
|
+
- [ ] AC-6: o `AGENTS.md` do projeto gerado e a skill `testing` ensinam a convenção.
|
|
32
|
+
|
|
33
|
+
## 5. Requisitos não-funcionais
|
|
34
|
+
- **Performance**: repo do Forja (~90 arquivos de teste, ~50 specs) em < 2 s.
|
|
35
|
+
- **Segurança**: somente leitura.
|
|
36
|
+
|
|
37
|
+
## 6. Fora de escopo
|
|
38
|
+
- Rodar os testes e marcar o critério como verde/vermelho (fica para o executor de testes de cada stack).
|
|
39
|
+
- Editar specs ou testes automaticamente.
|
|
40
|
+
|
|
41
|
+
## 7. Riscos e dependências
|
|
42
|
+
- `AC-N` sozinho num arquivo que cita várias specs é ambíguo: não conta para nenhuma (o relatório diz por quê).
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Spec: memoria-de-sessao
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-052
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0086](../../memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md) (projeto conectado), ADR-0091 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O que acontece numa sessão de IA só fica no transcript, que o Forja não lê. Quando o contexto é
|
|
12
|
+
compactado, a IA perde o fio (quais arquivos mexeu, qual spec estava seguindo, o que já commitou), e a
|
|
13
|
+
sessão seguinte começa do zero: o briefing do SessionStart mostra specs e handoffs, mas nada sobre o
|
|
14
|
+
que foi feito por último. Medição hoje: 0 registros de sessão em `memory/` de qualquer projeto.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
Toda sessão do Claude Code que muda alguma coisa deixa um checkpoint determinístico na memória do
|
|
18
|
+
projeto, atualizado ao fim de cada turno e antes de cada compactação. Depois de compactar, a IA recebe
|
|
19
|
+
o checkpoint de volta; numa sessão nova, vê onde a anterior parou. Sem chamar LLM, sem custo.
|
|
20
|
+
|
|
21
|
+
## 3. User stories
|
|
22
|
+
- **Como** dev numa sessão longa, **quero** que a IA, depois da compactação, saiba quais arquivos já
|
|
23
|
+
editou e qual spec estava seguindo, **para que** ela não refaça nem contradiga o trabalho.
|
|
24
|
+
- **Como** dev abrindo uma sessão nova, **quero** ver onde a última parou, **para que** eu retome sem reler o histórico.
|
|
25
|
+
- **Como** dono do projeto, **quero** que nenhum texto de prompt ou comando inteiro vá para a memória
|
|
26
|
+
commitada, **para que** um segredo colado no chat não acabe no git.
|
|
27
|
+
|
|
28
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
29
|
+
- [x] AC-1: `forja hook:session-memory` lê o JSON do hook (stdin: `session_id`, `transcript_path`, `cwd`, `hook_event_name`) e grava `memory/60-runs/sessions/<AAAA-MM-DD>-<id8>.md` com: título da sessão (`ai-title`), branch, arquivos editados (Edit/Write/MultiEdit/NotebookEdit, relativos ao projeto), comandos `forja <cmd>` (só o nome), specs tocadas (citadas em caminhos editados ou em comandos `forja spec:*`) e assuntos de `git commit -m`.
|
|
30
|
+
- [x] AC-2: sessão sem edição, sem comando forja e sem commit não grava nada; o mesmo `session_id` reescreve o mesmo arquivo (idempotente); o arquivo não contém texto de prompt.
|
|
31
|
+
- [x] AC-3: o hook nunca derruba a sessão: transcript ausente, JSON inválido ou projeto sem `memory/` saem com 0 e sem saída.
|
|
32
|
+
- [x] AC-4: `project:wire` registra o hook nos eventos `Stop` e `PreCompact` do `.claude/settings.json`, e `project:wire --check` (check `claude-hooks`) falha se faltar algum dos quatro eventos.
|
|
33
|
+
- [x] AC-5: `hook:session-start` lê o `source` do stdin: em `compact` injeta o checkpoint da própria sessão; em `startup`/`resume` injeta uma linha com a última sessão registrada (data, título, nº de arquivos, specs).
|
|
34
|
+
- [x] AC-6: a jornada (`lib/core/journey.ts`) cobre o caminho: transcript sintético → checkpoint gravado → SessionStart `compact` o devolve.
|
|
35
|
+
|
|
36
|
+
## 5. Requisitos não-funcionais
|
|
37
|
+
- **Performance**: transcript de 10 MB processado em < 1 s (linhas sem `tool_use`/`ai-title` são descartadas antes do `JSON.parse`); timeout do hook 10 s.
|
|
38
|
+
- **Segurança/LGPD**: sem texto de prompt, sem argumentos de comando além do nome do subcomando `forja`, sem saída de ferramenta.
|
|
39
|
+
- **Observabilidade**: não audita (hooks já são excluídos da trilha, `bin/forja.ts`).
|
|
40
|
+
|
|
41
|
+
## 6. Fora de escopo
|
|
42
|
+
- Resumo por LLM da sessão (custo; pode vir depois, alimentado por este checkpoint).
|
|
43
|
+
- Gate de "pronto" no Stop (bloquear o fim do turno com testes vermelhos).
|
|
44
|
+
- Codex/Gemini/Copilot: não têm eventos equivalentes de fim de turno e compactação com transcript em disco.
|
|
45
|
+
|
|
46
|
+
## 7. Riscos e dependências
|
|
47
|
+
- Formato do transcript do Claude Code não é contrato público: o parser ignora o que não reconhece e degrada para "nada a gravar".
|
|
48
|
+
- Checkpoints entram no git do projeto como o resto de `memory/`; quem não quiser ignora `memory/60-runs/sessions/`.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Spec: v6-agent-runtime-portable
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-059
|
|
4
|
+
- **Status**: draft
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-08
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 2
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O forja fala com agentes de IA por subprocesso, e essa fronteira foi escrita para unix. Estado validado em 2026-11-08 (`packages/llm/src/index.ts`, `scripts/llm-fit.ts`, `lib/agent-evals.ts`, log da rodada 4 da célula `windows-latest` no PR #83, v5.2.0):
|
|
12
|
+
|
|
13
|
+
- **`llm:run` não spawnar o provedor** — `runLlm()` faz `spawn(executable, args, { shell: false, detached: true })` (`packages/llm/src/index.ts:123`). No Windows o que `npm i -g` instala é `claude.cmd`/`codex.cmd`, e o Node recusa spawnar `.bat`/`.cmd` sem `shell: true` desde o endurecimento da CVE-2024-27980 (18.20.2 / 20.12.2 / 21.7.3), com `EINVAL`. Toda execução termina em `errorCode: 'SPAWN_FAILED'`, exit 127, antes de falar com o provedor. **Não existe versão de Node suportada em que isso funcione**: a matriz do CI roda 22 e 24, ambas do lado endurecido.
|
|
14
|
+
- **`llm:doctor`/`llm:probe` mentem sobre o que está instalado** — as seis sondagens de binário usam `shell: false` explícito (`scripts/llm-fit.ts:76,84,86,91,104,108`). O mesmo `EINVAL` vira `available: false`, e o comando reporta "provedor indisponível" para uma CLI instalada e funcionando, saindo com código 1 se o perfil estiver habilitado. O `detail` traz o errno cru, não o diagnóstico.
|
|
15
|
+
- **`eval:agents` tem duas frentes unix** — `timed()`/`cliVersion()` spawnam o binário direto (`lib/agent-evals.ts:177,183`, mesma restrição do probe), e o check `type: 'command'` roda via `spawnSync('sh', ['-c', …])` (`lib/agent-evals.ts:254`). Sem `sh`, checks declarativos como `"run": "node --test"` (`templates/evals/agents/teste-do-criterio.json:21`) são inaplicáveis — ainda que o comando em si seja perfeitamente portável.
|
|
16
|
+
- **Timeout não derruba a árvore** — `killGroup()` mata com `process.kill(-pid, 'SIGTERM')` (`packages/llm/src/index.ts:132-140`). Grupo de processo por pid negativo é POSIX; no Windows lança e cai no `child.kill(signal)`, que (a) não alcança os netos — o CLI real que o shim `.cmd` spawnou sobrevive — e (b) não tem o grace de `SIGTERM_GRACE_MS`, porque sinal em Windows é emulação: `kill('SIGTERM')` termina incondicionalmente. O orçamento de custo do forja pressupõe que um agente estourando o timeout para de queimar token.
|
|
17
|
+
|
|
18
|
+
Quem sente: usuário Windows (`llm:run`/`llm:doctor`/`eval:agents` não funcionam, e um agente em timeout continua rodando e cobrando), agente de IA consumindo o doctor (relatório falso de disponibilidade), maintainer (esta família é 6 dos 10 casos que seguram o `continue-on-error` da célula Windows, SPEC-056 AC-4).
|
|
19
|
+
|
|
20
|
+
**Honestidade sobre os 6 casos do CI**: eles falham porque os testes modelam o CLI do agente como script com shebang + `chmod 0o755` (`test/agent-evals.test.js` AC-4/AC-5/AC-6, `test/llm-resume-validation.test.js:142` → `spawn EFTYPE`, `test/llm-claude-adapter.test.js:99`, `test/llm-integration.test.js:111`). O fixture é unix-cêntrico, mas o que ele expõe é o caminho real do produto: em Windows um binário de agente **é** um `.cmd`, e o produto não resolve `.cmd`. Consertar só o fixture — um stub em Node, por exemplo — deixaria a suíte verde com `llm:run` quebrado em produção. Por isso o AC-3 obriga o stub falso a passar pelo `.cmd`, em vez de desviar dele.
|
|
21
|
+
|
|
22
|
+
## 2. Proposta de valor
|
|
23
|
+
Um único módulo de execução de subprocesso (`lib/exec.ts`) que resolve o binário do agente (`where`/`PATHEXT`), escapa argumentos para `cmd.exe` quando o SO exige, derruba a árvore do processo no timeout e oferece um launcher de shell portável para checks declarativos. `llm:run`, `llm:doctor`, `llm:probe` e `eval:agents` passam a funcionar nos três SOs, e o primeiro item do inventário da SPEC-056 AC-4 — o único que quebra o produto do usuário em produção, e não o CI — zera.
|
|
24
|
+
|
|
25
|
+
Sem dependência nova, de propósito: o que falta são ~40 linhas de quoting que conseguimos testar exaustivamente, inclusive contra injeção. Importar `cross-spawn` para isso colocaria na cadeia de suprimento de uma CLI publicada um pacote que já teve o seu próprio CVE (ReDoS, CVE-2024-21538) — é o mesmo defeito que a SPEC-058 ataca, importar uma segunda máquina para o que a primeira já faz. A decisão fica registrada em ADR, com a alternativa documentada em vez de esquecida (R-1).
|
|
26
|
+
|
|
27
|
+
## 3. User stories
|
|
28
|
+
- **Como** usuário Windows, **quero** que `forja llm:run` encontre o `claude`/`codex` que o npm instalou, **para que** eu use o framework sem depender de WSL.
|
|
29
|
+
- **Como** operador, **quero** que o `llm:doctor` distinga "não instalado" de "instalado mas o forja não conseguiu executar", **para que** o relatório não me mande reinstalar o que já está lá.
|
|
30
|
+
- **Como** maintainer rodando `eval:agents` com orçamento, **quero** que o timeout derrube a árvore inteira do agente, **para que** um caso estourado não continue queimando token depois do resultado sair.
|
|
31
|
+
- **Como** contribuidor, **quero** escrever checks `type: 'command'` com comandos portáveis e vê-los rodar em qualquer SO, **para que** a suíte de evals não seja um ativo só de unix.
|
|
32
|
+
|
|
33
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
34
|
+
- [ ] AC-1: os quatro call sites de fronteira de agente passam por `lib/exec.ts` (`resolveCommand`, `spawnAgent`, `runShell`, `killTree`): `packages/llm/src/index.ts:123`, `scripts/llm-fit.ts:76,84,86,91,104,108`, `lib/agent-evals.ts:177,183` e `lib/agent-evals.ts:254`. Spawn de `git`, `node` e `process.execPath` continua como está — não é a fronteira em questão e mexer nele seria escopo emprestado.
|
|
35
|
+
- [ ] AC-2 (segurança): o quoting de argumentos para `cmd.exe` é provado por teste com argumentos hostis — `"`, `&`, `|`, `>`, `<`, `%VAR%`, `^`, espaço, caminho com `\` — chegando ao processo-filho byte a byte como foi passado, e nenhum deles executando um segundo comando. O prompt do usuário e o comando do perfil são argumentos: sem este AC, o AC-1 trocava `EINVAL` por injeção. `shell: true` do Node nunca é usado (ele não escapa argumentos).
|
|
36
|
+
- [ ] AC-3 (fixture não desvia do produto): o stub de agente dos testes é um `.cmd` no Windows e continua script com shebang em unix, executado pelo mesmo resolver do produto. Os 6 casos do inventário ficam verdes na célula Windows **sem skip**.
|
|
37
|
+
- [ ] AC-4 (a árvore morre junto): em timeout, `runLlm` derruba filho e netos nos três SOs — no Windows por `taskkill /pid <pid> /T /F` ou equivalente, em POSIX pelo pid negativo como hoje. Teste: agente falso de dois níveis cujo neto escreve a cada 100ms para de escrever depois do grace, nos dois SOs. `exitCode: 124` / `errorCode: 'TIMEOUT'` não mudam.
|
|
38
|
+
- [ ] AC-5 (diagnóstico honesto): binário não encontrável → `available: false` com `detail` dizendo o que foi procurado (caminho resolvido, `PATHEXT`); binário encontrável que falha ao executar → outro detail. O contrato `--json` (ADR-0082) e os campos existentes não mudam, só o conteúdo de `detail`.
|
|
39
|
+
- [ ] AC-6 (checks `command`): `type: 'command'` roda por `runShell`, que usa `sh -c` em POSIX e `%ComSpec% /d /s /c` no Windows; as suítes de `templates/evals/agents/*.json` rodam inteiras nos três SOs. `CheckResult` não ganha estado novo nesta spec.
|
|
40
|
+
|
|
41
|
+
## 5. Escopo
|
|
42
|
+
**Dentro**:
|
|
43
|
+
- `lib/exec.ts` (novo) + `test/exec.test.js` (novo): resolver, quoting, `killTree`, `runShell`.
|
|
44
|
+
- `packages/llm/src/index.ts`: `runLlm` aceita launcher injetável — o pacote hoje importa só `node:child_process` e continua assim; quem injeta é o `scripts/llm-fit.ts`.
|
|
45
|
+
- `scripts/llm-fit.ts`: as seis sondagens do doctor e a chamada de `runLlm`.
|
|
46
|
+
- `lib/agent-evals.ts`: `timed()`, `cliVersion()` e o check `command`.
|
|
47
|
+
- Fixtures dos quatro arquivos de teste do inventário: stub portável.
|
|
48
|
+
|
|
49
|
+
**Fora**:
|
|
50
|
+
- `cross-spawn`/`execa`/qualquer dependência nova (§2, R-1).
|
|
51
|
+
- Estado `skipped` em `CheckResult` — muda o JSON que o dashboard de evals consome; decisão separada.
|
|
52
|
+
- Os outros dois itens do inventário Windows (`git worktree` em `test/simulate-cli.test.js`, `spec:trace 0/0` na jornada) e a linha `continue-on-error` do `ci.yml`, que só sai quando o inventário inteiro zerar.
|
|
53
|
+
- WSL como caminho suportado: é contorno, não solução, e o framework já é usado fora dele.
|
|
54
|
+
- Reescrever checks `command` de usuários em Node: o launcher portável resolve sem exigir migração.
|
|
55
|
+
|
|
56
|
+
## 6. NFRs / restrições
|
|
57
|
+
- Segurança: fronteira de subprocesso com argumento vindo de usuário (prompt) e de configuração (comando do perfil). Quoting é requisito, não otimização.
|
|
58
|
+
- Compatibilidade: em POSIX/macOS nenhum comportamento muda — o caminho direto continua vencendo quando existe, como no `inside()` da SPEC-056. Zero regressão nos 666 testes das células ubuntu/macos.
|
|
59
|
+
- Superfície: um módulo, quatro funções. `hasBinary()` (`lib/project-wiring.ts:98`) já resolve binário por plataforma com `where`/`which` — o módulo segue essa convenção em vez de inventar outra, e ela passa a ser caso particular de `resolveCommand`.
|
|
60
|
+
- Custo: zero minuto novo de CI (os testes rodam na matriz que já existe).
|
|
61
|
+
|
|
62
|
+
## 7. Riscos e mitigação
|
|
63
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| Quoting de `cmd.exe` escrito à mão deixar passar injeção | M | A | AC-2 com casos hostis explícitos; ADR registra o que foi testado; alternativa (dependência) documentada em vez de esquecida |
|
|
66
|
+
| `taskkill /T` não alcançar neto de shim `.cmd` encadeado | M | M | AC-4 mede com agente falso de dois níveis; se não alcançar, o detail do timeout reporta quantos processos restaram |
|
|
67
|
+
| Consertar o fixture e não o produto (suíte verde, `llm:run` quebrado) | M | A | AC-3 obriga o stub a ser `.cmd` no Windows e a passar pelo resolver do produto |
|
|
68
|
+
| Launcher injetável em `runLlm` quebrar o contrato dos adapters | B | M | Injeção com default = comportamento atual; testes existentes de resume/timeout continuam provando o mesmo contrato |
|
|
69
|
+
| `resolveCommand` escolher binário errado (PATH com duplicados) | B | M | `where` lista todos; o módulo usa o primeiro e o AC-5 expõe o caminho resolvido no `detail` |
|
|
70
|
+
| `runShell` executar comando de check com semântica diferente por SO | M | M | AC-6 roda as suítes template nos três SOs; comando que não é portável falha com o launcher no detail, não silenciosamente |
|
|
71
|
+
|
|
72
|
+
## 8. Métricas de sucesso
|
|
73
|
+
30 dias após: `llm:run`, `llm:doctor` e `eval:agents` verdes na célula Windows do CI; inventário da SPEC-056 AC-4 de 3 causas/10 casos para 2 causas/4 casos; zero relato de "provedor indisponível" em máquina com o provedor instalado; nenhum caso novo nos testes de injeção de argumento.
|
|
74
|
+
|
|
75
|
+
## Evidências e estado real
|
|
76
|
+
Levantamento de 2026-11-08, branch `feat/v6-wave1` (PR #83), por leitura de código e log da rodada 4 — sem patch adivinhado:
|
|
77
|
+
|
|
78
|
+
- **Call sites lidos, um a um**: `packages/llm/src/index.ts:123` (`spawn` com `shell: false, detached: true`), `:132-140` (`killGroup` com `process.kill(-pid)` e fallback `child.kill`), `scripts/llm-fit.ts:76,84,86,91,104,108` (seis sondagens com `shell: false`), `lib/agent-evals.ts:177,183` (spawn direto do binário do agente), `:254` (`spawnSync('sh', ['-c', check.run])`).
|
|
79
|
+
- **Os 6 casos da célula Windows**: `test/llm-resume-validation.test.js:142` (`spawn EFTYPE`), `test/agent-evals.test.js` AC-4/AC-5/AC-6 (`agent.args` nunca escrito), `test/llm-claude-adapter.test.js:99`, `test/llm-integration.test.js:111`. Os 2 casos do AC-1 da SPEC-054, que eram desta família, ficaram verdes na rodada 2 — o que confirma que a causa deles era o CRLF das skills, não o stub, e é o motivo de esta spec não reivindicá-los.
|
|
80
|
+
- **Restrição do Node**: spawn de `.bat`/`.cmd` sem `shell: true` lança `EINVAL` desde 18.20.2 / 20.12.2 / 21.7.3 (endurecimento da CVE-2024-27980). A matriz do CI roda Node 22 e 24: as duas células estão do lado endurecido, então não há versão suportada em que o código atual funcione no Windows.
|
|
81
|
+
- **Comando do check template é portável, o launcher não**: `"run": "node --test"` em `templates/evals/agents/teste-do-criterio.json:21` roda igual em `cmd.exe`; o que impede é o `sh` fixo na linha 254.
|
|
82
|
+
- **Convenção que já existe no repo**: `lib/project-wiring.ts:98` usa `where` no Windows e `which` no resto. Também por isso o caminho é um módulo só — não quatro remendos de plataforma espalhados pelos call sites.
|
|
83
|
+
- **Estado**: spec em draft, nenhuma linha de produto escrita. A implementação depende de aprovação e roda na mesma branch da Wave 2.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Spec: v6-core-consolidation
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-058
|
|
4
|
+
- **Status**: draft
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-05
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 2
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O núcleo do forja cresceu por acréscimo e hoje há múltiplas implementações para a mesma responsabilidade. Estado validado em 2026-11-05 (v5.2.0):
|
|
12
|
+
|
|
13
|
+
- **6 leitores independentes** do audit trail `.context/forja-runs.jsonl` (`lib/governance-report.ts`, `lib/status-model.ts`, `lib/audit.ts`, `scripts/memory-schema.ts`, `scripts/risk.ts`, `scripts/audit-sync.ts`) — cada um com seu parsing; um bug de formato precisa ser corrigido 6×.
|
|
14
|
+
- **`process.exit(1)` em 32 arquivos** e `cli-output.ts` adotado em apenas **8 de 54 scripts** — saída e códigos de erro inconsistentes entre comandos.
|
|
15
|
+
- **`audit()` silencia sem workspace**: `bin/forja.ts` tem `if (!info.exists) return;` — comandos rodados fora de projeto forja não geram trilha (por design atual, mas sem alternativa de log mínimo).
|
|
16
|
+
- **`any` em 360 pontos** do código do repo (341 `: any` + 19 `as any`; 0 em `packages/` e `apps/`) — fronteiras internas sem contrato de tipo.
|
|
17
|
+
- Dispatch de comandos via processos `node:` separados (99 dos 104 comandos do registry) — overhead de spawn por comando e estado não compartilhado.
|
|
18
|
+
- Gates declarados em apenas **39 dos 104 comandos**, sem middleware uniforme de execução.
|
|
19
|
+
- `apps/worker` dormente desde 2026-08-01; `specs/clean-arch-boilerplate` ainda "approved" sem implementação — ativos ambíguos no repo.
|
|
20
|
+
|
|
21
|
+
Quem sente: maintainer (cada mudança toca N pontos), agentes de IA (saída inconsistente), contribuidores (sem contrato claro).
|
|
22
|
+
|
|
23
|
+
## 2. Proposta de valor
|
|
24
|
+
Uma única implementação por responsabilidade no núcleo: módulo de auditoria único, camada de saída/erros uniforme, gates como middleware e dispatch in-process — mudanças de comportamento passam de "editar N arquivos" para "editar 1 módulo", com tipos contratuais nas fronteiras.
|
|
25
|
+
|
|
26
|
+
## 3. User stories
|
|
27
|
+
- **Como** maintainer, **quero** um único módulo `audit` que lê/grava o JSONL, **para que** formato e migrações mudem em um só lugar.
|
|
28
|
+
- **Como** agente de IA consumindo saída do forja, **quero** formato e códigos de saída uniformes em todos os comandos, **para que** eu possa parsear sem casos especiais por comando.
|
|
29
|
+
- **Como** contribuidor, **quero** gates executados por um middleware do registry, **para que** adicionar gate a um comando seja declarativo, não código novo.
|
|
30
|
+
- **Como** usuário, **quero** dispatch in-process dos comandos `node:`, **para que** cada comando tenha menos latência de spawn.
|
|
31
|
+
|
|
32
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
33
|
+
- [ ] AC-1: Módulo único de auditoria (`lib/audit-core.ts` ou equivalente) é a **única** implementação de leitura/escrita do JSONL; os 6 consumidores atuais o utilizam (grep confirma zero parsing direto remanescente).
|
|
34
|
+
- [ ] AC-2: Camada uniforme de saída/erros: `cli-output` (ou sucessor) adotado nos 54 scripts; `process.exit(1)` direto eliminado ou restrito ao entrypoint `bin/forja.ts`.
|
|
35
|
+
- [ ] AC-3: Gates executados por middleware do dispatch: comando declara gate no registry e o runner aplica (pré/pós), sem código de gate por script; os 39 gates atuais preservados com mesmo comportamento (testes).
|
|
36
|
+
- [ ] AC-4: Dispatch in-process para comandos `node:` com fallback a spawn quando o módulo exigir (documentado); latência média por comando medida antes/depois nas evidências.
|
|
37
|
+
- [ ] AC-5: Fronteiras dos módulos públicos tipadas: `any` reduzido em ≥ 50% da baseline (360 → ≤ 180), com teto do lint (SPEC-056) acompanhando a redução.
|
|
38
|
+
- [ ] AC-6: Destino de `apps/worker` e `specs/clean-arch-boilerplate` decidido e executado (arquivar com status explícito ou reativar) — zero ativos "aprovados/dormentes" sem decisão.
|
|
39
|
+
|
|
40
|
+
## 5. Escopo
|
|
41
|
+
**Dentro**:
|
|
42
|
+
- Consolidação de auditoria, saída/erros, gates middleware, dispatch.
|
|
43
|
+
- Tipagem das fronteiras (redução de `any`).
|
|
44
|
+
- Decisão sobre worker/specs stale.
|
|
45
|
+
|
|
46
|
+
**Fora**:
|
|
47
|
+
- Mudança do formato do JSONL de auditoria (compatibilidade com trilhas existentes é obrigatória; migração só se inevitável, com ADR).
|
|
48
|
+
- Consolidação de `packages/` do monorepo além do necessário para o dispatch (pode virar ADR própria).
|
|
49
|
+
- Reescrita de comandos `bin:` (4) — continuam via shell.
|
|
50
|
+
- Redução de `any` em código gerado por templates de projeto.
|
|
51
|
+
|
|
52
|
+
## 6. NFRs / restrições
|
|
53
|
+
- Compatibilidade: trilhas JSONL antigas continuam legíveis; `forja-runs.jsonl` sem breaking change de schema.
|
|
54
|
+
- Performance: dispatch in-process não pode aumentar p95 de comando simples; AC-4 mede.
|
|
55
|
+
- Segurança: auditoria continua imutável (append-only); nenhum caminho novo permite edição de trilha.
|
|
56
|
+
- Observabilidade: erros uniformes incluem código estável de erro por classe de falha.
|
|
57
|
+
|
|
58
|
+
## 7. Riscos e mitigação
|
|
59
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
60
|
+
|---|---|---|---|
|
|
61
|
+
| Refatorar 6 leitores + 54 scripts em um PR gigante | A | A | Fatiar: AC-1 primeiro (audit-core), depois AC-2, cada um com testes e merge próprio |
|
|
62
|
+
| Dispatch in-process vazar estado entre comandos | M | A | Isolamento por contexto explícito; fallback spawn; testes de concorrência |
|
|
63
|
+
| Redução de `any` introduzir regressões de runtime | M | M | Teto decrescente (SPEC-056) + suíte completa multi-OS antes de cada merge |
|
|
64
|
+
| Mudar gates quebrar `release:check`/`project:smoke` | B | A | Gates atuais com snapshot de comportamento antes da migração |
|
|
65
|
+
|
|
66
|
+
## 8. Métricas de sucesso
|
|
67
|
+
30 dias após: 1 implementação de auditoria (grep = 0 duplicatas); 100% dos scripts na camada de saída uniforme; `any` ≤ 180; latência média de comando ≤ valor pré-refatoração; zero issues de trilha de auditoria ilegível.
|
|
68
|
+
|
|
69
|
+
## Evidências e estado real
|
|
70
|
+
- Diagnóstico validado em 2026-11-05 contra v5.2.0: 6 leitores JSONL confirmados por grep; `process.exit(1)` em 32 arquivos; `cli-output` em 8/54 scripts; `any`=360 (0 em packages/apps); registry 104 comandos (99 node:, 4 bin:, 1 outro; 39 com gates); `audit()` skip sem workspace em `bin/forja.ts`; worker último commit 2026-08-01; spec clean-arch "approved".
|