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.
Files changed (113) hide show
  1. package/CHANGELOG.md +76 -0
  2. package/README.md +37 -4
  3. package/README.pt-BR.md +39 -4
  4. package/dist/apps/cli/src/index.d.ts +0 -1
  5. package/dist/apps/cli/src/index.js +43 -32
  6. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  7. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  8. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  10. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  11. package/dist/apps/server/src/forja-nest.module.js +55 -0
  12. package/dist/apps/server/src/main.d.ts +21 -4
  13. package/dist/apps/server/src/main.js +79 -57
  14. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  15. package/dist/apps/server/src/task-planning-service.js +195 -0
  16. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  17. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  18. package/dist/bin/forja.js +3 -2
  19. package/dist/lib/agent-evals.d.ts +138 -0
  20. package/dist/lib/agent-evals.js +349 -0
  21. package/dist/lib/cli-output.js +14 -2
  22. package/dist/lib/code-context.d.ts +33 -5
  23. package/dist/lib/code-context.js +70 -5
  24. package/dist/lib/context-builder.d.ts +49 -4
  25. package/dist/lib/context-builder.js +114 -47
  26. package/dist/lib/core/coverage-gate.d.ts +59 -0
  27. package/dist/lib/core/coverage-gate.js +58 -0
  28. package/dist/lib/core/doc-graph.d.ts +38 -0
  29. package/dist/lib/core/doc-graph.js +83 -0
  30. package/dist/lib/core/health.js +286 -5
  31. package/dist/lib/core/journey.js +26 -0
  32. package/dist/lib/core/registry.js +81 -6
  33. package/dist/lib/docs-reference.d.ts +35 -0
  34. package/dist/lib/docs-reference.js +57 -0
  35. package/dist/lib/project-wiring.js +6 -2
  36. package/dist/lib/session-memory.d.ts +38 -0
  37. package/dist/lib/session-memory.js +206 -0
  38. package/dist/lib/spec-trace.d.ts +46 -0
  39. package/dist/lib/spec-trace.js +184 -0
  40. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  41. package/dist/packages/adapter-nest/src/index.js +59 -1
  42. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  43. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  44. package/dist/packages/context/src/index.d.ts +2 -0
  45. package/dist/packages/context/src/index.js +36 -15
  46. package/dist/packages/contracts/src/index.d.ts +64 -0
  47. package/dist/packages/core/src/index.d.ts +9 -1
  48. package/dist/packages/core/src/index.js +28 -3
  49. package/dist/packages/graph/src/index.js +14 -5
  50. package/dist/packages/mcp/src/index.d.ts +8 -0
  51. package/dist/packages/mcp/src/index.js +12 -1
  52. package/dist/packages/observability/src/index.d.ts +11 -0
  53. package/dist/packages/observability/src/index.js +3 -0
  54. package/dist/packages/orchestration/src/index.d.ts +15 -1
  55. package/dist/packages/orchestration/src/index.js +127 -21
  56. package/dist/packages/planner/src/index.d.ts +7 -1
  57. package/dist/packages/planner/src/index.js +67 -10
  58. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  59. package/dist/packages/planner/src/proposal-store.js +109 -0
  60. package/dist/packages/policy/src/index.d.ts +9 -16
  61. package/dist/packages/policy/src/index.js +114 -31
  62. package/dist/packages/runtime/src/index.d.ts +16 -2
  63. package/dist/packages/runtime/src/index.js +176 -61
  64. package/dist/scripts/build-smart-context.d.ts +2 -0
  65. package/dist/scripts/build-smart-context.js +12 -3
  66. package/dist/scripts/code-context.d.ts +3 -1
  67. package/dist/scripts/code-context.js +13 -3
  68. package/dist/scripts/coverage-gate.d.ts +2 -0
  69. package/dist/scripts/coverage-gate.js +101 -0
  70. package/dist/scripts/eval-agents.d.ts +11 -0
  71. package/dist/scripts/eval-agents.js +96 -0
  72. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  73. package/dist/scripts/gen-commands-doc.js +18 -0
  74. package/dist/scripts/hook-session-memory.d.ts +9 -0
  75. package/dist/scripts/hook-session-memory.js +20 -0
  76. package/dist/scripts/hook-session-start.js +34 -0
  77. package/dist/scripts/spec-trace.d.ts +10 -0
  78. package/dist/scripts/spec-trace.js +73 -0
  79. package/dist/scripts/sync-universal-memory.js +69 -4
  80. package/dist/scripts/token-benchmark.d.ts +33 -1
  81. package/dist/scripts/token-benchmark.js +179 -5
  82. package/dist/scripts/token-economy.js +3 -1
  83. package/dist/scripts/tools-doctor.d.ts +16 -1
  84. package/dist/scripts/tools-doctor.js +58 -17
  85. package/docs/commands.md +155 -0
  86. package/docs/fluxo.md +11 -7
  87. package/docs/init-project.md +3 -1
  88. package/docs/llm-fit-loop.md +20 -0
  89. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  90. package/docs/produto/factsheet-marketing.md +7 -5
  91. package/docs/produto/roteiro-demo.md +14 -5
  92. package/docs/quick-reference.md +3 -3
  93. package/docs/token-optimization.md +10 -6
  94. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  95. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  96. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  97. package/package.json +4 -2
  98. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  99. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  100. package/specs/memoria-de-sessao/spec.md +48 -0
  101. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  102. package/specs/v6-core-consolidation/spec.md +70 -0
  103. package/specs/v6-docs-drift/spec.md +85 -0
  104. package/specs/v6-quality-gates/spec.md +99 -0
  105. package/specs/v6-token-economy/spec.md +84 -0
  106. package/templates/evals/agents/adr.json +25 -0
  107. package/templates/evals/agents/memoria.json +32 -0
  108. package/templates/evals/agents/proxima-acao.json +29 -0
  109. package/templates/evals/agents/spec-nova.json +26 -0
  110. package/templates/evals/agents/teste-do-criterio.json +29 -0
  111. package/templates/project/AGENTS.md +7 -0
  112. package/templates/project/CLAUDE.md +3 -2
  113. 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 parcial via API; não é requisito do fluxo CLI-first.
137
- - **Dashboard React/Vite legado:** útil para demonstração local de telas e navegação. Em 2026-08-17,
138
- ele inicia em Node 24 com `better-sqlite3` 12 e expõe API local em `127.0.0.1:7777`; o frontend
139
- Vite fica em `http://127.0.0.1:5173`. Um workspace sem projetos ou handoffs mostra coleções vazias,
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 local em 127.0.0.1:3000
21
- npm run dashboard:dev # app em http://localhost:3001
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"` antes de `npm run dashboard:api`.
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**): **GraphLoop** mostra specs, ADRs e evidências ligadas;
36
- **Approvals** e **Atividade recente** mostram as decisões e execuções auditadas.
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
@@ -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 legado/opcional
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
- node lib/context-builder.js global my-project
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
- node lib/context-builder.js domain my-project
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
- node lib/context-builder.js task my-project "auth backend"
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.js';
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.js` integrated
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.1.0",
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
- "test": "node --test test/*.test.js",
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".