forjajs 3.0.0 → 4.0.1

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 (53) hide show
  1. package/.claude/agents/context-engineer.md +10 -16
  2. package/.claude/agents/governance.md +9 -45
  3. package/.claude/agents/marketing.md +10 -15
  4. package/.claude/agents/orchestrator.md +9 -21
  5. package/.claude/agents/product.md +10 -17
  6. package/.claude/agents/sdd-architect.md +10 -25
  7. package/.gemini-instructions.md +15 -9
  8. package/.github/copilot-instructions.md +15 -9
  9. package/.openai-instructions.md +16 -10
  10. package/AGENTS.md +9 -6
  11. package/CHANGELOG.md +48 -0
  12. package/DOC-MAP.md +4 -0
  13. package/dist/lib/core/health.js +2 -1
  14. package/dist/lib/core/release.js +3 -0
  15. package/dist/lib/llm/codex-output.d.ts +12 -0
  16. package/dist/lib/llm/codex-output.js +56 -0
  17. package/dist/lib/llm/context.d.ts +5 -0
  18. package/dist/lib/llm/context.js +17 -0
  19. package/dist/lib/llm/session.d.ts +18 -0
  20. package/dist/lib/llm/session.js +34 -0
  21. package/dist/lib/llm/validation.d.ts +37 -0
  22. package/dist/lib/llm/validation.js +88 -0
  23. package/dist/packages/evals/src/index.js +6 -0
  24. package/dist/packages/llm/src/index.d.ts +8 -1
  25. package/dist/packages/llm/src/index.js +38 -4
  26. package/dist/scripts/llm-fit.js +60 -13
  27. package/docs/agent-operating-contract.md +26 -0
  28. package/docs/llm-evolution.md +51 -0
  29. package/docs/llm-fit-loop.md +134 -5
  30. package/docs/publishing.md +40 -357
  31. package/memory/90-decisions/0080-llm-execution-evidence.md +42 -0
  32. package/memory/90-decisions/0081-llm-resume-validation.md +42 -0
  33. package/package.json +3 -1
  34. package/prompts/context-engineer-agent.md +8 -14
  35. package/prompts/governance-agent.md +10 -13
  36. package/prompts/marketing-agent.md +10 -10
  37. package/prompts/orchestrator-agent.md +9 -14
  38. package/prompts/product-agent.md +10 -10
  39. package/prompts/sdd-architect-agent.md +8 -15
  40. package/skills/MANIFEST.json +10 -0
  41. package/skills/llm-provider-routing/SKILL.md +18 -0
  42. package/specs/_templates/plan.md +7 -0
  43. package/specs/_templates/spec.md +7 -0
  44. package/specs/_templates/tasks.md +8 -1
  45. package/specs/agent-instructions-v4/plan.md +8 -0
  46. package/specs/agent-instructions-v4/spec.md +21 -0
  47. package/specs/agent-instructions-v4/tasks.md +12 -0
  48. package/specs/llm-integration-v2/plan.md +55 -0
  49. package/specs/llm-integration-v2/spec.md +61 -0
  50. package/specs/llm-integration-v2/tasks.md +28 -0
  51. package/specs/llm-resume-validation/plan.md +50 -0
  52. package/specs/llm-resume-validation/spec.md +35 -0
  53. package/specs/llm-resume-validation/tasks.md +19 -0
@@ -18,6 +18,34 @@ Edite `<workspace>/.context/llm-profiles.json` para habilitar somente os adapter
18
18
  `command` aceita um executável; argumentos fixos vão em `commandArgs`. O processo é criado com
19
19
  `shell: false` e o Forja não lê API keys.
20
20
 
21
+ `commandArgs` preserva ordem, repetições e espaços dos argumentos. `timeoutMs` é opcional
22
+ (padrão 120000 ms, inteiro positivo até 2147483647). `reasoningEffort` é opcional e exclusivo
23
+ do Codex nesta versão: `low`, `medium`, `high`, `xhigh` ou `max`.
24
+
25
+ ## Perfil GPT-6 no Codex
26
+
27
+ Adicione um perfil ao objeto `profiles` do arquivo existente, mantendo `version: 1`:
28
+
29
+ ```json
30
+ {
31
+ "codex-gpt6": {
32
+ "provider": "codex",
33
+ "model": "gpt-6-astra",
34
+ "command": "codex",
35
+ "roles": ["worker", "sdd-architect"],
36
+ "taskTypes": ["implementation", "architecture", "review"],
37
+ "privacy": "external",
38
+ "enabled": true,
39
+ "reasoningEffort": "high",
40
+ "timeoutMs": 300000
41
+ }
42
+ }
43
+ ```
44
+
45
+ O modelo precisa estar disponível na conta autenticada da CLI. O doctor verifica instalação
46
+ e flags locais do Codex, mas não consulta acesso ao modelo (`modelAccess: "not-probed"`).
47
+ O perfil padrão continua usando o modelo configurado pelo operador, sem migração automática.
48
+
21
49
  ## Execução e evidência
22
50
 
23
51
  ```bash
@@ -25,17 +53,118 @@ forja llm:run --profile codex --task specs/pagamentos/spec.md --context .context
25
53
  forja llm:eval --scope model --id codex:default
26
54
  ```
27
55
 
28
- `llm:run` calcula hashes e tokens estimados, mas não salva o prompt ou a resposta no banco. Salva
29
- modelo, duração, resultado, comando, referências de contexto e métricas no armazenamento de
30
- observações. `llm:eval` usa regras determinísticas do `EvaluationEngine` para medir sucesso,
31
- retrabalho, custo, tempo e uso de contexto.
56
+ `--context` pode ser repetido: os arquivos são lidos e enviados ao modelo em ordem, com caminhos
57
+ duplicados removidos. Arquivo ausente ou diretório causa erro antes de executar o provedor.
58
+ O hash cobre tarefa e contexto completos. O Forja não salva esses conteúdos nem a resposta no banco
59
+ ou na auditoria; salva modelo, duração, resultado, comando, referências e contagens de tokens.
60
+
61
+ Codex recebe o prompt por stdin e retorna eventos JSONL. O Forja extrai a resposta do agente,
62
+ `sessionId` e uso, sem devolver eventos de raciocínio como resposta final. Falhas explícitas,
63
+ JSONL inválido ou ausência de conclusão resultam em erro mesmo com exit zero do subprocesso.
64
+ O identificador da sessão é registrado no workspace e pode ser usado na retomada descrita abaixo.
65
+
66
+ Na saída JSON:
67
+
68
+ - `executionStatus`: `completed` ou `failed`; não comprova a qualidade da entrega.
69
+ - `validationStatus`: `accepted`, `rejected`, `inconclusive` ou `blocked`, conforme os checks independentes.
70
+ - `usage.source`: `provider` quando há telemetria; `estimated` para aproximação por bytes/4.
71
+ - `usage.cachedInputTokens`: presente quando informado pelo Codex.
72
+ - `costSource`: `estimated` com tabela local; `unknown` e `costUsd: null` sem preço conhecido.
73
+ - `errorCode`: distingue timeout, falha de subprocesso, falha do provedor e protocolo inválido.
74
+
75
+ Mesmo com tokens do provedor, o preço calculado não representa uma fatura: a tabela atual não
76
+ modela descontos de cache ou assinaturas. A saída antes usava zero para custo desconhecido;
77
+ consumidores devem tratar null. O recorder histórico ainda representa custo ausente como zero;
78
+ `cost:economy` consulta a tabela para identificar modelos sem preço. Origem dos tokens e sessão
79
+ estão na saída; a sessão também é registrada como metadados em `llm_session`, sem histórico textual.
80
+
81
+ `llm:eval` mantém métricas de execução; sua taxa de sucesso não equivale a tarefas aprovadas.
82
+ As métricas adicionais `validationAcceptedCount`, `validationRejectedCount`, `validationCoverageRate`
83
+ e `validationSuccessRate` medem as observações validadas. A última usa como denominador somente
84
+ aceitas + rejeitadas; inconclusivas e bloqueadas não são aprovações nem reprovações.
85
+
86
+ ## Retomar uma sessão Codex
87
+
88
+ Use o `sessionId` retornado por uma execução anterior no mesmo workspace, projeto e perfil:
89
+
90
+ ```bash
91
+ forja llm:run --profile codex-gpt6 --resume SESSION_ID --prompt "Continue a análise do requisito pendente"
92
+ ```
93
+
94
+ O Forja envia apenas o novo prompt e os novos contextos selecionados. Não há replay, retry
95
+ automático nem escolha implícita da última sessão. O modo continua `read-only`. A sessão deve
96
+ continuar existindo no histórico da CLI do Codex. ID desconhecido ou mudança de projeto,
97
+ provedor, modelo declarado, executável, argumentos ou privacidade bloqueia antes da chamada.
98
+ Esforço e timeout podem mudar. A configuração global da CLI não é fingerprintada; use um modelo
99
+ explícito no perfil quando precisar fixá-lo. Não há coordenação de retomadas simultâneas da mesma
100
+ sessão nem garantia de que o modelo nunca repetirá uma ação.
101
+
102
+ ## Formato e validação independente
103
+
104
+ O operador escolhe o schema da resposta e os checks antes de executar o modelo:
105
+
106
+ ```bash
107
+ forja llm:run --profile codex-gpt6 --task specs/pagamentos/spec.md --output-schema result.schema.json --validation checks.json
108
+ ```
109
+
110
+ Exemplo de `result.schema.json`:
111
+
112
+ ```json
113
+ {
114
+ "type": "object",
115
+ "properties": { "summary": { "type": "string" } },
116
+ "required": ["summary"],
117
+ "additionalProperties": false
118
+ }
119
+ ```
120
+
121
+ O schema é compilado localmente antes da chamada e usado para validar a resposta sem coerção.
122
+ São suportados draft-07 (padrão) e 2020-12 com `$schema` explícito. Refs remotos, schemas
123
+ assíncronos e formatos/plugins extras não são carregados. O Codex também recebe a flag nativa;
124
+ outros adaptadores recebem a instrução de responder JSON, com a mesma validação local.
125
+ O suporte de geração do provedor pode ser mais restrito que o JSON Schema local.
126
+
127
+ Exemplo de `checks.json` para verificar a suíte do projeto:
128
+
129
+ ```json
130
+ {
131
+ "version": 1,
132
+ "checks": [
133
+ { "name": "testes-do-projeto", "command": "npm", "args": ["test"], "timeoutMs": 120000 }
134
+ ]
135
+ }
136
+ ```
137
+
138
+ Checks são programas confiáveis escolhidos pelo operador, executados sequencialmente no diretório
139
+ do projeto com as permissões do processo Forja. Não são comandos escolhidos pelo modelo nem
140
+ executados dentro do sandbox Codex. A resposta chega por stdin; um script próprio pode verificar
141
+ seu conteúdo e critérios de aceite. `args` é um array, sem interpretação por shell.
142
+ O manifest aceita 1–20 checks, nomes únicos e timeout de 1–600000 ms por check (padrão 120000).
143
+
144
+ Formato válido sozinho retorna `validation.formatStatus: "accepted"` e `validationStatus:
145
+ "inconclusive"`. Com checks, todos precisam passar para marcar `accepted`. O primeiro check
146
+ reprovado encerra a validação. Schema reprovado impede executar os checks; falha do provedor
147
+ deixa a validação `blocked`.
148
+
149
+ Uma rejeição de validação retorna exit **2**, mantendo `executionExitCode: 0` e `executionStatus:
150
+ "completed"` se o modelo terminou normalmente. Falhas do modelo preservam seu código de saída.
151
+ Sem schema ou checks, o comportamento continua sendo execução com validação inconclusiva.
152
+
153
+ `llm_validation` guarda o ID da observação, hashes do schema, manifest e resposta, nomes dos
154
+ checks, exit codes, duração e hashes dos logs. Não guarda resposta nem logs textuais. O resultado
155
+ aprova somente os checks configurados; não equivale a merge ou aprovação geral de segurança.
32
156
 
33
157
  ## Segurança e escopo
34
158
 
35
159
  - O adapter padrão do Codex é `read-only`; mudanças de arquivos continuam no runtime/sandbox
36
160
  supervisionado do Forja.
37
- - `llm:probe` só executa `--version`; não consome tokens nem envia conteúdo do projeto.
161
+ - `llm:probe` executa `--version` e, para Codex, os helps de `exec` e `exec resume`;
162
+ informa também `features.resume` e `features.outputSchema`, sem consumir tokens ou enviar contexto.
38
163
  - Recomendações são ordenadas por compatibilidade declarada e observações locais. O operador escolhe
39
164
  o perfil; não existe failover automático nem chamada direta a APIs nesta versão.
40
165
  - O dashboard pode editar e exibir perfis, mas não executa modelos. A antiga rota de execução retorna
41
166
  `USE_FORJA_LLM_RUN`; use o CLI para que policy, auditoria e observabilidade sejam aplicadas.
167
+ - O histórico da CLI do provedor segue a configuração desse provedor, fora do armazenamento Forja.
168
+
169
+ Veja [visão e próximas etapas](llm-evolution.md) e
170
+ [documentação oficial do Codex](https://learn.chatgpt.com/docs/non-interactive-mode).
@@ -1,377 +1,60 @@
1
- # 📦 Guia de Publicação no npm
1
+ # Publicação do ForjaJS
2
2
 
3
- Este documento explica exatamente o que será publicado e o que fica privado.
3
+ O pacote npm é `forjajs`. A fonte TypeScript é compilada em `dist/`; a lista `files` do
4
+ package.json define o conteúdo distribuído. O workspace de produtos fica fora do repositório.
4
5
 
5
- ---
6
+ ## Preparar uma versão
6
7
 
7
- ## ✅ O que SERÁ Publicado
8
+ Instalar as dependências do checkout com `npm ci` antes de executar os comandos abaixo.
9
+ Se `better-sqlite3` estiver ausente, o CLI falha com `ERR_MODULE_NOT_FOUND` antes de iniciar
10
+ o doctor ou o gate de release.
8
11
 
9
- Quando você rodar `npm publish --access public`, apenas isso será incluído:
12
+ 1. Revisar mudanças, atualizar versão em package.json e package-lock.json e escrever o changelog.
13
+ 2. Executar tipos, testes e governança pelo core do Forja.
14
+ 3. Commitar a entrega. O modo de publicação exige árvore Git limpa.
15
+ 4. Executar doctor e o gate estrito do tarball na revisão que será publicada.
10
16
 
11
- ```
12
- create-memory-nest-kit/
13
- │
14
- ├── bin/
15
- │ ├── create-memory-nest-kit.js ← Gerador original (sempre)
16
- │ └── init-project.js ← Novo: comando universal
17
- │
18
- ├── Documentação
19
- │ ├── README.md ← Atualizado (350+ linhas)
20
- │ ├── START-HERE.md
21
- │ ├── SUMARIO-EXECUTIVO.md
22
- │ ├── REFINAMENTO-v1.0.md
23
- │ ├── IMPLEMENTACAO-FASE1.md
24
- │ ├── EXEMPLOS-CODIGO.md
25
- │ ├── INDICE-MASTER.md
26
- │ ├── INIT-PROJECT-GUIDE.md
27
- │ ├── ESTRUTURA-PROJETO.md
28
- │ ├── .github/copilot-instructions.md
29
- │ └── .gemini-instructions.md
30
- │
31
- ├── CLAUDE.md ← Instruções para Claude
32
- ├── LICENSE
33
- ├── package.json
34
- ├── .npmignore ← Controla exclusões
35
- └── .gitignore
36
-
37
- ```
38
-
39
- ---
40
-
41
- ## ❌ O que NÃO Será Publicado
42
-
43
- Estes diretórios e arquivos são **excluídos** pelo `.npmignore`:
44
-
45
- ```
46
- ❌ exemplo-projeto/ ← Exemplo v1 (referência local)
47
- ❌ exemplo-v2/ ← Exemplo v2 (referência local)
48
- ❌ exemplo-v3/ ← Exemplo v3 (referência local)
49
- ❌ teste-completo/ ← Projeto de teste
50
- ❌ teste-local/ ← Projeto de teste
51
- ❌ ai-medico/ ← Exemplo com caso real
52
- ❌ bpo-financeiro/ ← Exemplo com caso real
53
- ❌ test-init-demo/ ← Teste do comando
54
- ❌ .env ← Configuração local
55
- ❌ .env.local
56
- ❌ .env.*.local
57
- ❌ docs/ ← Documentação interna
58
- ❌ node_modules/ ← Dependências
59
- ❌ .DS_Store ← macOS
60
- ❌ *.log ← Logs
61
- ❌ *.tgz ← Archives
62
- ```
63
-
64
- ---
65
-
66
- ## 🔍 Como Verificar
67
-
68
- Antes de publicar, confirme o que será enviado:
69
-
70
- ```bash
71
- # 1. Ver o que npm vai publicar
72
- npm pack --dry-run
73
-
74
- # 2. Listar arquivos
75
- npm pack --dry-run | tar tzf -
76
-
77
- # 3. Verificar .npmignore
78
- cat .npmignore
79
- ```
80
-
81
- ---
82
-
83
- ## 📋 Checklist Pré-Publicação
84
-
85
- Antes de `npm publish`:
86
-
87
- ### 1. Verificar Versão
88
- ```bash
89
- cat package.json | grep version
90
- # Esperado: "version": "0.3.0"
91
- ```
92
-
93
- ### 2. Build e Testes
94
- ```bash
95
- npm run build # Se houver
96
- npm run test # Se houver
97
- npm run lint # Se houver
98
- ```
99
-
100
- ### 3. Verificar .npmignore
101
- ```bash
102
- # Deve excluir:
103
- grep "exemplo-" .npmignore
104
- grep "teste-" .npmignore
105
- grep "\.env" .npmignore
106
- ```
107
-
108
- ### 4. Verificar Package.json
109
- ```json
110
- {
111
- "name": "create-memory-nest-kit",
112
- "version": "0.3.0",
113
- "description": "Professional-grade scaffold for multi-agent orchestration",
114
- "main": "bin/create-memory-nest-kit.js",
115
- "bin": {
116
- "create-memory-nest-kit": "bin/create-memory-nest-kit.js",
117
- "init-project": "bin/init-project.js"
118
- },
119
- "repository": {
120
- "type": "git",
121
- "url": "https://github.com/seu-usuario/create-memory-nest-kit.git"
122
- },
123
- "keywords": [
124
- "scaffold",
125
- "multi-agent",
126
- "orchestration",
127
- "memory",
128
- "nestjs",
129
- "ai"
130
- ],
131
- "author": "Seu Nome",
132
- "license": "MIT"
133
- }
134
- ```
135
-
136
- ### 5. Testar Comando Localmente
137
- ```bash
138
- # Simular publicação
139
- npm pack
140
-
141
- # Resultado: create-memory-nest-kit-0.3.0.tgz
142
-
143
- # Extrair e verificar
144
- tar tzf create-memory-nest-kit-0.3.0.tgz | head -20
145
-
146
- # Limpar
147
- rm create-memory-nest-kit-0.3.0.tgz
148
- ```
149
-
150
- ---
151
-
152
- ## 🚀 Passos de Publicação
153
-
154
- ### Passo 1: Login no npm
155
17
  ```bash
156
- npm login
18
+ npm run types:check
19
+ npm test
20
+ npm run project:check
21
+ npm run tools:doctor
22
+ npm run release:check -- --publish
157
23
  ```
158
24
 
159
- Você será pedido para:
160
- - Username
161
- - Password
162
- - Email (opcional)
25
+ O gate constrói dist, empacota, instala em diretório isolado e verifica o pacote instalado.
26
+ Os subprocessos npm usam um cache próprio em `.npm-cache` dentro desse diretório temporário,
27
+ removido pelo bloco de limpeza ao final, inclusive em caso de erro. O gate não depende das
28
+ permissões nem do conteúdo do cache global do npm e precisa de acesso ao registry para baixar
29
+ as dependências. Variáveis herdadas `npm_*`, incluindo `npm_config_cache`, são descartadas antes
30
+ de configurar esse cache isolado. Essa configuração vale apenas para o gate; não altera o cache
31
+ usado por comandos npm executados diretamente.
163
32
 
164
- ### Passo 2: Publicar
165
- ```bash
166
- npm publish --access public
167
- ```
33
+ O parecer vale para aquele conteúdo: mudanças posteriores exigem nova verificação.
34
+ Ferramentas opcionais ausentes são reportadas separadamente pelo doctor.
168
35
 
169
- Resultado esperado:
170
- ```
171
- npm notice 📦 create-memory-nest-kit@0.3.0
172
- npm notice === Tarball Contents ===
173
- npm notice 500.0 kB bin/create-memory-nest-kit.js
174
- npm notice 400.0 kB bin/init-project.js
175
- npm notice 250.0 kB README.md (+ 11 docs)
176
- npm notice ...
177
- npm notice === Dist Files ===
178
- npm notice +publish create-memory-nest-kit@0.3.0
179
- ```
36
+ ## Publicar a revisão aprovada
180
37
 
181
- ### Passo 3: Verificar Publicação
182
- ```bash
183
- npm view create-memory-nest-kit@0.3.0
184
- ```
38
+ A publicação precisa de autorização do mantenedor e autenticação no npm. Nunca salvar tokens
39
+ no repositório. O comando de publicação executa prepublishOnly, que repete o gate estrito.
185
40
 
186
- Deve mostrar:
187
- - Nome
188
- - Versão
189
- - Descrição
190
- - Keywords
191
- - Repository URL
192
-
193
- ---
194
-
195
- ## 🧪 Testar Após Publicação
196
-
197
- ### Instalação via npm
198
41
  ```bash
199
- # Limpar local
200
- rm -rf test-npm-install
201
-
202
- # Instalar do npm
203
- npm install -g create-memory-nest-kit@0.3.0
204
-
205
- # Testar
206
- create-memory-nest-kit meu-projeto-novo
207
- cd meu-projeto-novo
208
- cat .ia-instructions/copilot.md
209
- ```
210
-
211
- ### Instalação via npx
212
- ```bash
213
- npx create-memory-nest-kit@0.3.0 outro-projeto
214
- cd outro-projeto
215
- npm run build # Se houver
216
- ```
217
-
218
- ---
219
-
220
- ## 📊 Tamanho do Pacote
221
-
222
- Esperado (final):
223
- - **Total**: ~1-2 MB (comprimido)
224
- - **Descompactado**: ~3-5 MB
225
- - **Sem exemplos**: ~500 KB (documentação + scripts)
226
-
227
- Se ultrapassar 10MB, verificar:
228
- ```bash
229
- npm pack
230
- tar tzf *.tgz | wc -l # Contar arquivos
231
- du -sh *.tgz # Tamanho
232
- ```
233
-
234
- ---
235
-
236
- ## 🔐 Privacidade
237
-
238
- ### Público (no npm)
239
- - ✅ `bin/` - Scripts executáveis
240
- - ✅ `*.md` - Documentação
241
- - ✅ `package.json` - Metadados
242
- - ✅ `.github/` - Instruções Copilot
243
- - ✅ `LICENSE` - Licença
244
-
245
- ### Privado (não no npm)
246
- - ❌ `exemplo-*` - Exemplos de output
247
- - ❌ `teste-*` - Testes locais
248
- - ❌ `.env` - Configuração sensível
249
- - ❌ `docs/` - Documentação interna
250
- - ❌ `node_modules/` - Dependências
251
-
252
- ---
253
-
254
- ## 🎯 Depois de Publicar
255
-
256
- ### 1. Atualizar GitHub
257
- ```bash
258
- git tag v0.3.0
259
- git push origin main --tags
260
- git push origin main
261
- ```
262
-
263
- ### 2. Anunciar
264
- ```
265
- Publicado: create-memory-nest-kit@0.3.0
266
-
267
- ✨ Novidades:
268
- - bin/init-project.js comando universal
269
- - 11 documentos profissionais (350+ KB)
270
- - Suporte a Copilot, Claude, Gemini
271
- - 38 melhorias especificadas
272
- - Estrutura de memória hierárquica
273
- - Multi-agent orchestration
274
- - SQLite para rastreamento
275
- - Enterprise-grade quality
276
-
277
- Use:
278
- npx create-memory-nest-kit@0.3.0 meu-projeto
279
- node bin/init-project.js meu-projeto
280
-
281
- https://npm.im/create-memory-nest-kit
282
- ```
283
-
284
- ### 3. GitHub Releases
285
- Criar release em GitHub com:
286
- - Changelog
287
- - Download links
288
- - Instruções de uso
289
-
290
- ---
291
-
292
- ## 🆘 Troubleshooting
293
-
294
- ### "Directory não encontrado"
295
- ```bash
296
- # Verificar pasta
297
- ls -la
298
-
299
- # Executar de dentro da pasta
300
- cd /home/apk/Documentos/GitHub/2-Projeto-Agents
301
- npm publish --access public
302
- ```
303
-
304
- ### "npm ERR! 403 Forbidden"
305
- ```bash
306
- # Verificar login
307
42
  npm whoami
308
-
309
- # Fazer login novamente
310
- npm login
311
- npm publish --access public
312
- ```
313
-
314
- ### "Tag já existe"
315
- ```bash
316
- # Ver tags
317
- git tag
318
-
319
- # Usar versão diferente
320
- # Atualizar package.json: version: 0.3.1
321
- npm publish --access public
43
+ npm publish --access public --tag latest
44
+ npm view forjajs version dist-tags --json
322
45
  ```
323
46
 
324
- ---
325
-
326
- ## 📝 Notas Importantes
327
-
328
- 1. **Sempre testar localmente antes**
329
- ```bash
330
- npm pack
331
- # Extrair e verificar conteúdo
332
- ```
333
-
334
- 2. **Manter .npmignore atualizado**
335
- Sempre que adicionar exemplo/teste, adicionar ao `.npmignore`
336
-
337
- 3. **Versioning semântico**
338
- - 0.3.0 → feature release (novo init-project.js)
339
- - 0.3.1 → bug fix
340
- - 1.0.0 → breaking changes
341
-
342
- 4. **Documentação no GitHub**
343
- Manter README.md sincronizado com npm
344
-
345
- ---
346
-
347
- ## 🎉 Depois Publicamente Disponível
348
-
349
- Usuários podem:
350
-
351
- ```bash
352
- # Via npx (sem instalar)
353
- npx create-memory-nest-kit@latest meu-projeto
354
-
355
- # Via npm global
356
- npm install -g create-memory-nest-kit
357
- create-memory-nest-kit meu-projeto
358
-
359
- # Via npm local
360
- npm install create-memory-nest-kit
361
- npx create-memory-nest-kit meu-projeto
362
- ```
47
+ Se a sessão expirou, o mantenedor renova o login com `npm login`. Se o npm exigir autenticação
48
+ adicional, concluir o fluxo oficial. Não contornar o gate com ignore-scripts.
363
49
 
364
- E automaticamente terão:
365
- - ✅ Estrutura de memória completa
366
- - ✅ Agentes orquestrados
367
- - ✅ Backend NestJS
368
- - ✅ Instruções para Copilot/Claude/Gemini
369
- - ✅ SQLite indexação
370
- - ✅ 38 melhorias implementadas
50
+ Enviar o commit para o GitHub, aguardar o CI e criar a tag/release correspondente à versão
51
+ publicada. Não mover uma tag existente nem republicar uma versão imutável.
371
52
 
372
- ---
53
+ ## Conteúdo e compatibilidade
373
54
 
374
- **Status**: 🟢 Pronto para Publicação
375
- **Versão**: 0.3.0
376
- **Data**: 2026-04-21
55
+ Conferir os arquivos com `npm pack --dry-run --json`. O pacote inclui executáveis compilados,
56
+ memória e documentação distribuíveis, prompts e templates declarados em files. Credenciais,
57
+ node_modules, bancos e contextos privados não devem entrar no tarball.
377
58
 
59
+ A versão 4.0.0 altera costUsd desconhecido de zero para null no JSON de llm:run. As opções de
60
+ retomada, schema e checks são explícitas. Exemplos em [LLM Fit Loop](llm-fit-loop.md).
@@ -0,0 +1,42 @@
1
+ # ADR-0080: Contexto e evidência na integração LLM
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-09-05
5
+ - **Autor(es)**: Allan Pablo / Codex
6
+ - **Tags**: llm, cli, observability
7
+
8
+ ## Contexto
9
+
10
+ O LLM Fit Loop perde contexto selecionado e não interpreta eventos do Codex. O produto requer
11
+ integração com GPT-6 e demais LLMs, distinguindo execução de validação.
12
+
13
+ ## Decisão
14
+
15
+ Estender perfis v1 com timeout e esforço opcional do Codex. Enviar o prompt completo por stdin
16
+ ao Codex e normalizar JSONL em resposta, sessão e uso. Adaptadores legados mantêm argv.
17
+ Contextos são carregados antes de iniciar qualquer subprocesso.
18
+
19
+ Observation.outcome continua descrevendo execução para compatibilidade; validationStatus será
20
+ inconclusive até existir validação independente. A saída explicita essa distinção.
21
+ Falhas de protocolo/provedor prevalecem sobre exit zero.
22
+
23
+ Preços calculados com a tabela local são estimativas, mesmo com tokens do provedor. Preço ausente
24
+ é null na saída pública; a representação histórica no recorder permanece nesta etapa.
25
+ Eventos brutos não são persistidos pelo Forja. O provedor controla seu próprio histórico.
26
+
27
+ ## Alternativas consideradas
28
+
29
+ - API direta: adiada, altera a fronteira de credenciais da ADR-0074.
30
+ - Reescrever storage: adiado; validationStatus existente permite evolução compatível.
31
+ - Failover automático: rejeitado, pode alterar privacidade e custo.
32
+
33
+ ## Consequências
34
+
35
+ Perfis existentes seguem válidos. JSONL inválido falha explicitamente. Métricas antigas de sucesso
36
+ continuam sendo de execução. Retomada, schema da resposta, cache e benchmark seguem no roadmap.
37
+
38
+ ## Rastreamento
39
+
40
+ - [Spec](../../specs/llm-integration-v2/spec.md)
41
+ - [Visão](../../docs/llm-evolution.md)
42
+ - [ADR-0074](0074-llm-fit-loop-cli-adapters.md)
@@ -0,0 +1,42 @@
1
+ # ADR-0081: Sessões e validação independente de LLM
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-09-05
5
+ - **Autor(es)**: Allan Pablo / Codex
6
+ - **Tags**: llm, validation, sessions
7
+
8
+ ## Contexto
9
+
10
+ O usuário autorizou continuar a evolução LLM após a primeira etapa. Precisamos retomar sessões
11
+ e distinguir uma resposta com formato válido de uma tarefa aprovada por critérios independentes.
12
+
13
+ ## Decisão
14
+
15
+ Retomar apenas IDs registrados no Forja e vinculados a projeto real e fingerprint do perfil.
16
+ Não relançar automaticamente uma sessão que falhou nem trocar silenciosamente de modelo.
17
+ Persistir metadados nas coleções llm_session e llm_validation do SqliteJsonRepository existente.
18
+
19
+ Usar Ajv 8 para validar JSON Schema localmente, com compilação antes da chamada ao modelo,
20
+ sem coerção de dados ou carregamento remoto. Uma implementação própria parcial de JSON Schema
21
+ foi rejeitada porque aceitaria contratos que não sabe verificar.
22
+
23
+ Checks independentes vêm de um manifest explícito escolhido pelo operador antes da chamada.
24
+ Executar argv sem shell, timeout limitado e resposta por stdin. Não executar comandos sugeridos
25
+ pela resposta. Guardar somente hashes, resultado e duração dos checks.
26
+
27
+ Formato válido sozinho deixa validação inconclusive. Checks aprovados podem marcar accepted;
28
+ falha marca rejected e exit 2, mantendo executionStatus/Observation.outcome do modelo separados.
29
+ Métricas existentes permanecem; métricas adicionais descrevem validação independente.
30
+
31
+ ## Consequências
32
+
33
+ Ajv entra em dependencies. Sessões dependem do histórico do provedor; não há coordenação de
34
+ retomadas simultâneas ou garantia de exactly-once no agente. Checks rodam com as permissões do
35
+ operador e aprovam somente os requisitos que efetivamente verificam.
36
+
37
+ ## Rastreamento
38
+
39
+ - [Spec](../../specs/llm-resume-validation/spec.md)
40
+ - [Visão](../../docs/llm-evolution.md)
41
+ - [Codex não interativo](https://learn.chatgpt.com/docs/non-interactive-mode)
42
+ - [Ajv](https://ajv.js.org/guide/getting-started)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "3.0.0",
3
+ "version": "4.0.1",
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",
@@ -12,6 +12,7 @@
12
12
  "files": [
13
13
  "dist/",
14
14
  "prompts/",
15
+ "skills/",
15
16
  "boilerplates/",
16
17
  "design-md/",
17
18
  "memory/",
@@ -125,6 +126,7 @@
125
126
  "author": "Allan Pablo",
126
127
  "license": "MIT",
127
128
  "dependencies": {
129
+ "ajv": "^8.20.0",
128
130
  "better-sqlite3": "^12.11.1"
129
131
  },
130
132
  "allowScripts": {