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.
- package/.claude/agents/context-engineer.md +10 -16
- package/.claude/agents/governance.md +9 -45
- package/.claude/agents/marketing.md +10 -15
- package/.claude/agents/orchestrator.md +9 -21
- package/.claude/agents/product.md +10 -17
- package/.claude/agents/sdd-architect.md +10 -25
- package/.gemini-instructions.md +15 -9
- package/.github/copilot-instructions.md +15 -9
- package/.openai-instructions.md +16 -10
- package/AGENTS.md +9 -6
- package/CHANGELOG.md +48 -0
- package/DOC-MAP.md +4 -0
- package/dist/lib/core/health.js +2 -1
- package/dist/lib/core/release.js +3 -0
- package/dist/lib/llm/codex-output.d.ts +12 -0
- package/dist/lib/llm/codex-output.js +56 -0
- package/dist/lib/llm/context.d.ts +5 -0
- package/dist/lib/llm/context.js +17 -0
- package/dist/lib/llm/session.d.ts +18 -0
- package/dist/lib/llm/session.js +34 -0
- package/dist/lib/llm/validation.d.ts +37 -0
- package/dist/lib/llm/validation.js +88 -0
- package/dist/packages/evals/src/index.js +6 -0
- package/dist/packages/llm/src/index.d.ts +8 -1
- package/dist/packages/llm/src/index.js +38 -4
- package/dist/scripts/llm-fit.js +60 -13
- package/docs/agent-operating-contract.md +26 -0
- package/docs/llm-evolution.md +51 -0
- package/docs/llm-fit-loop.md +134 -5
- package/docs/publishing.md +40 -357
- package/memory/90-decisions/0080-llm-execution-evidence.md +42 -0
- package/memory/90-decisions/0081-llm-resume-validation.md +42 -0
- package/package.json +3 -1
- package/prompts/context-engineer-agent.md +8 -14
- package/prompts/governance-agent.md +10 -13
- package/prompts/marketing-agent.md +10 -10
- package/prompts/orchestrator-agent.md +9 -14
- package/prompts/product-agent.md +10 -10
- package/prompts/sdd-architect-agent.md +8 -15
- package/skills/MANIFEST.json +10 -0
- package/skills/llm-provider-routing/SKILL.md +18 -0
- package/specs/_templates/plan.md +7 -0
- package/specs/_templates/spec.md +7 -0
- package/specs/_templates/tasks.md +8 -1
- package/specs/agent-instructions-v4/plan.md +8 -0
- package/specs/agent-instructions-v4/spec.md +21 -0
- package/specs/agent-instructions-v4/tasks.md +12 -0
- package/specs/llm-integration-v2/plan.md +55 -0
- package/specs/llm-integration-v2/spec.md +61 -0
- package/specs/llm-integration-v2/tasks.md +28 -0
- package/specs/llm-resume-validation/plan.md +50 -0
- package/specs/llm-resume-validation/spec.md +35 -0
- package/specs/llm-resume-validation/tasks.md +19 -0
package/docs/llm-fit-loop.md
CHANGED
|
@@ -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
|
-
`
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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`
|
|
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).
|
package/docs/publishing.md
CHANGED
|
@@ -1,377 +1,60 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Publicação do ForjaJS
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
160
|
-
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
165
|
-
|
|
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
|
-
|
|
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
|
-
|
|
182
|
-
|
|
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
|
-
|
|
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
|
-
|
|
365
|
-
|
|
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
|
-
|
|
375
|
-
|
|
376
|
-
|
|
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
|
+
"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": {
|