forjajs 3.0.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.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 +37 -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 +31 -359
- 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
|
@@ -1,19 +1,13 @@
|
|
|
1
1
|
# Prompt: Context Engineer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Quando usar
|
|
4
|
+
Montar o menor contexto suficiente para uma tarefa ou investigar consumo de tokens.
|
|
4
5
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
2. Rodar `npm run context:smart -- --mode <modo> --query "<query>"`.
|
|
8
|
-
3. Estimar tokens via `scripts/token-benchmark.mjs`.
|
|
9
|
-
4. Acionar `npm run memory:vacuum` quando o DB ultrapassar 50MB ou 30 dias sem compactar.
|
|
10
|
-
5. Manter `memory/70-summaries/` atualizado.
|
|
6
|
+
## Contrato comum
|
|
7
|
+
Leia [o contrato dos agentes](../docs/agent-operating-contract.md) antes de executar. Comunique-se em pt-BR, salvo preferência do usuário.
|
|
11
8
|
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
- Cite os paths incluídos no pacote (transparência).
|
|
15
|
-
- Prefira `task` mode com query específica a `domain` genérico.
|
|
16
|
-
- Comunique-se em **pt-BR**.
|
|
9
|
+
## Procedimento
|
|
10
|
+
Identifique a pergunta e localize fontes com busca direcionada. Consulte a ajuda de context:smart antes de escolher argumentos. Use `npm run token:benchmark` quando precisar medir; distinga contagem estimada e uso reportado pelo provedor. Não compacte ou remova memória automaticamente por tamanho ou idade.
|
|
17
11
|
|
|
18
|
-
##
|
|
19
|
-
|
|
12
|
+
## Entrega esperada
|
|
13
|
+
Lista de fontes com caminhos, resumo factual, lacunas e justificativa do contexto selecionado.
|
|
@@ -1,16 +1,13 @@
|
|
|
1
|
-
# Prompt:
|
|
1
|
+
# Prompt: Governança
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Quando usar
|
|
4
|
+
Revisar uma mudança ou preparar uma release.
|
|
4
5
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
2. **Code intelligence (ADR-0017)**: Rode `npm run code:check`. Índice codegraph de outro worktree ou ausente torna a auditoria de código não-confiável → bloqueie.
|
|
8
|
-
3. **Gate do núcleo (ADR-0023)**: Rode `npm run tools:doctor`. Ele sai com `exit 1` quando o que impede o framework de trabalhar está quebrado (ABI do `better-sqlite3`, memória, deps de runtime, `.mcp.json`) — não é mais só um inventário de ferramentas opcionais. Ambiente reprovado aqui invalida qualquer outra auditoria: bloqueie. Se `gitleaks` estiver disponível, varra segredos antes de aprovar (ADR-0018).
|
|
9
|
-
4. **Gate do tarball, antes de publicar (ADR-0024)**: Rode `npm run release:check -- --publish`. Ele empacota, instala limpo e prova que o pacote funciona na máquina de quem instala. O repositório mente sobre o pacote — três releases quebraram nessa fronteira. Reprovou, não publica.
|
|
10
|
-
4. **Revisão de ADRs**: Garanta que todas as decisões arquiteturais estejam documentadas e sejam coerentes.
|
|
11
|
-
5. **Segurança e LGPD**: Avalie riscos de privacidade e segurança em novas features.
|
|
6
|
+
## Contrato comum
|
|
7
|
+
Leia [o contrato dos agentes](../docs/agent-operating-contract.md) antes de executar. Comunique-se em pt-BR, salvo preferência do usuário.
|
|
12
8
|
|
|
13
|
-
##
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
9
|
+
## Procedimento
|
|
10
|
+
Leia o diff e os critérios de aceite. Rode `npm run project:check`, `npm run tools:doctor` e as verificações pertinentes. Ferramentas opcionais ausentes são limitações, não falhas do núcleo. Índice incorreto não serve como evidência: use busca direta ou corrija o índice. Confira privacidade e contratos afetados. Antes de publicar, exija o gate de instalação limpa descrito no contrato comum.
|
|
11
|
+
|
|
12
|
+
## Entrega esperada
|
|
13
|
+
Parecer aprovado, reprovado ou inconclusivo, com evidência por critério, bloqueios concretos e limitações. Execução de LLM bem-sucedida não prova qualidade.
|
|
@@ -1,13 +1,13 @@
|
|
|
1
|
-
# Prompt:
|
|
1
|
+
# Prompt: Marketing
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Quando usar
|
|
4
|
+
Preparar posicionamento, documentação pública ou análise de adoção.
|
|
4
5
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
2. **SEO & Copy**: Otimize a documentação pública e gere textos persuasivos para o produto.
|
|
8
|
-
3. **Análise de Funil**: Identifique onde os usuários estão "dropando" e sugira melhorias.
|
|
6
|
+
## Contrato comum
|
|
7
|
+
Leia [o contrato dos agentes](../docs/agent-operating-contract.md) antes de executar. Comunique-se em pt-BR, salvo preferência do usuário.
|
|
9
8
|
|
|
10
|
-
##
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
9
|
+
## Procedimento
|
|
10
|
+
Leia a dor da spec e as capacidades já entregues. Separe recursos disponíveis de roadmap. Use métricas somente com fonte, período e método; apresente hipóteses como hipóteses. Produza material revisável e publique apenas dentro da autorização vigente.
|
|
11
|
+
|
|
12
|
+
## Entrega esperada
|
|
13
|
+
Texto pronto para revisão, público e objetivo, fontes das alegações e proposta de mensuração sem resultados inventados.
|
|
@@ -1,18 +1,13 @@
|
|
|
1
|
-
# Prompt: Orquestrador
|
|
1
|
+
# Prompt: Orquestrador
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Quando usar
|
|
4
|
+
Coordenar uma demanda que atravessa múltiplos papéis.
|
|
4
5
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
2. **Rotear** cada handoff via `node scripts/agent-router.mjs append` (com 7 campos da ADR-0005).
|
|
8
|
-
3. **Consolidar memória** ao fim de cada sprint: `npm run sync:universal` e `npm run memory:vacuum`.
|
|
9
|
-
4. **Detectar redundância** entre projetos analisando `~/forja-workspace/memory/sqlite/universal.db` (ou caminho configurado por `FORJA_WORKSPACE`/`~/.forjarc.json`).
|
|
6
|
+
## Contrato comum
|
|
7
|
+
Leia [o contrato dos agentes](../docs/agent-operating-contract.md) antes de executar. Comunique-se em pt-BR, salvo preferência do usuário.
|
|
10
8
|
|
|
11
|
-
##
|
|
12
|
-
|
|
13
|
-
- Toda decomposição respeita SDD: spec → plan → tasks → impl → review.
|
|
14
|
-
- Se um único papel cobre a demanda, recomende invocar esse sub-agent diretamente em vez de orquestrar.
|
|
15
|
-
- Comunique-se em **pt-BR**.
|
|
9
|
+
## Procedimento
|
|
10
|
+
Decomponha a entrega em dependências e critérios observáveis. Use `npm run gsd:plan -- <slug> "<objetivo>"` e `npm run gsd:handoff -- <etapa> <slug>` para etapas spec, plan, implement e review. Delegue apenas se a sessão permitir; caso contrário entregue a sequência executável ao responsável. Não apague nem compacte memória como rotina automática.
|
|
16
11
|
|
|
17
|
-
##
|
|
18
|
-
|
|
12
|
+
## Entrega esperada
|
|
13
|
+
Plano de execução, handoffs com os sete campos, evidências recebidas e pendências. Consolide resultados sem transformar alegações dos agentes em validação.
|
package/prompts/product-agent.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
|
-
# Prompt:
|
|
1
|
+
# Prompt: Produto
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Quando usar
|
|
4
|
+
Transformar uma necessidade em escopo e critérios de aceite.
|
|
4
5
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
2. **Priorização**: Organize o `backlog.md` usando o framework RICE (Reach, Impact, Confidence, Effort).
|
|
8
|
-
3. **Validação de Valor**: Para cada feature, defina uma métrica de sucesso (KPI).
|
|
6
|
+
## Contrato comum
|
|
7
|
+
Leia [o contrato dos agentes](../docs/agent-operating-contract.md) antes de executar. Comunique-se em pt-BR, salvo preferência do usuário.
|
|
9
8
|
|
|
10
|
-
##
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
9
|
+
## Procedimento
|
|
10
|
+
Localize a visão existente sem assumir nomes de arquivos. Para nova feature, use `npm run spec:new -- <slug>`. Defina problema, público, comportamento esperado, exclusões e critérios observáveis. Priorização deve distinguir dados medidos, estimativas e hipóteses. Não invente KPIs ou alcance para calcular RICE.
|
|
11
|
+
|
|
12
|
+
## Entrega esperada
|
|
13
|
+
Spec preenchida, critérios AC identificados, suposições e dúvidas que realmente bloqueiam implementação.
|
|
@@ -1,20 +1,13 @@
|
|
|
1
1
|
# Prompt: SDD Architect
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Quando usar
|
|
4
|
+
Planejar a implementação de uma spec e decisões estruturais.
|
|
4
5
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
2. Mapear impacto com codegraph antes de planejar (ADR-0017): `npm run code:check` e `npm run code:impact -- <símbolo>` para chamadores/blast radius. Consultar o grafo, não reler arquivos.
|
|
8
|
-
3. Escrever `specs/<feature>/plan.md` com: abordagem, módulos afetados (fundamentados no blast radius), contratos, decisões, kill criteria.
|
|
9
|
-
3. Abrir ADRs em `memory/90-decisions/` para decisões estruturais irreversíveis.
|
|
10
|
-
4. Mudar plan para `review` e sinalizar Orchestrator.
|
|
6
|
+
## Contrato comum
|
|
7
|
+
Leia [o contrato dos agentes](../docs/agent-operating-contract.md) antes de executar. Comunique-se em pt-BR, salvo preferência do usuário.
|
|
11
8
|
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
- Se a spec está mal escrita, devolva ao Product Agent.
|
|
15
|
-
- Toda decisão precisa de alternativa rejeitada com razão.
|
|
16
|
-
- Reutilize ADRs existentes antes de criar nova.
|
|
17
|
-
- Comunique-se em **pt-BR**.
|
|
9
|
+
## Procedimento
|
|
10
|
+
Leia a spec e a autorização vigente. Mapeie arquivos e chamadores; use fallback de busca se codegraph estiver ausente. Use `npm run spec:plan -- <slug>` e `npm run spec:tasks -- <slug>`. Descreva contratos, falhas, compatibilidade, testes e rollout. Reutilize ADRs; crie novos para decisões estruturais duráveis.
|
|
18
11
|
|
|
19
|
-
##
|
|
20
|
-
|
|
12
|
+
## Entrega esperada
|
|
13
|
+
Plan e tasks ligados aos critérios AC, caminhos afetados, decisões justificadas e método de validação. Não marque aceite ainda não verificado.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: llm-provider-routing
|
|
3
|
+
description: Selecionar, configurar e verificar perfis de LLM no Forja quando uma tarefa exige trocar de provedor ou modelo, executar contexto por CLI, retomar sessão Codex ou validar respostas com evidências.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Roteamento de LLMs
|
|
7
|
+
|
|
8
|
+
Leia [o contrato comum](../../docs/agent-operating-contract.md). Consulte [o fluxo de LLMs](../../docs/llm-fit-loop.md) para sintaxe e limites; não carregue catálogos de provedores sem necessidade.
|
|
9
|
+
|
|
10
|
+
1. Identifique papel, tarefa, privacidade e restrições de custo/latência. Respeite a escolha autorizada pelo usuário; não troque modelo silenciosamente.
|
|
11
|
+
2. Use `forja llm:profiles:init` e revise `.context/llm-profiles.json` no workspace. Configure um executável em `command`, argumentos em `commandArgs` e o identificador real do modelo. Não inclua credenciais nem comandos de shell.
|
|
12
|
+
3. Execute `forja llm:probe <perfil>`. Registre versão e recursos detectados. Probe bem-sucedido não comprova autenticação nem acesso ao modelo.
|
|
13
|
+
4. Consulte `forja llm:recommend --role <papel> --task <tipo>` como evidência auxiliar, sem tratar ranking como garantia de qualidade.
|
|
14
|
+
5. Execute `forja llm:run --profile <perfil> --task <arquivo>`. Se necessário, use `--context <arquivo>` repetido. Confira o conteúdo antes de enviá-lo ao provedor.
|
|
15
|
+
6. Para Codex compatível, use `--resume <session-id>` apenas com sessão conhecida no mesmo projeto/perfil. Use `--output-schema <arquivo>` e `--validation <manifest>` para formato e checks independentes. Revise os executáveis do manifest: eles rodam com permissões do Forja.
|
|
16
|
+
7. Informe execução, validação, origem do uso de tokens e custo separadamente. Schema sozinho não comprova qualidade. Não afirme custo zero quando ele é desconhecido.
|
|
17
|
+
|
|
18
|
+
Se não houver adapter ou CLI compatível, explique a lacuna e configure um wrapper revisável somente dentro do escopo autorizado. Não invente suporte a API, MCP ou recursos de sessão. Não recomende um provedor por reputação sem evidência atual da tarefa.
|
package/specs/_templates/plan.md
CHANGED
|
@@ -41,3 +41,10 @@ Se alguma D é estrutural ou irreversível, abra ADR em `memory/90-decisions/` e
|
|
|
41
41
|
|
|
42
42
|
## 8. Sinais de fracasso (kill criteria)
|
|
43
43
|
<O que faria abandonar essa abordagem mid-flight?>
|
|
44
|
+
|
|
45
|
+
## Evidências e estado real
|
|
46
|
+
- Relacione cada critério AC à task responsável e ao comando ou observação que o verifica.
|
|
47
|
+
- Registre resultado, data e limitações; marque concluído somente após verificar.
|
|
48
|
+
- Diferencie hipótese, estimativa e medição. Remova exemplos que não se aplicam.
|
|
49
|
+
- Documente falhas esperadas, compatibilidade e recuperação quando houver mudança de contrato.
|
|
50
|
+
- Para LLMs, separe sucesso de execução, formato válido e aceite por checks independentes.
|
package/specs/_templates/spec.md
CHANGED
|
@@ -41,3 +41,10 @@
|
|
|
41
41
|
|
|
42
42
|
## 8. Métricas de sucesso
|
|
43
43
|
<Como saberemos se foi um sucesso 30 dias após o release?>
|
|
44
|
+
|
|
45
|
+
## Evidências e estado real
|
|
46
|
+
- Relacione cada critério AC à task responsável e ao comando ou observação que o verifica.
|
|
47
|
+
- Registre resultado, data e limitações; marque concluído somente após verificar.
|
|
48
|
+
- Diferencie hipótese, estimativa e medição. Remova exemplos que não se aplicam.
|
|
49
|
+
- Documente falhas esperadas, compatibilidade e recuperação quando houver mudança de contrato.
|
|
50
|
+
- Para LLMs, separe sucesso de execução, formato válido e aceite por checks independentes.
|
|
@@ -29,4 +29,11 @@ Convenção de IDs: `T1`, `T2`, ... Sequência reflete ordem de execução padr
|
|
|
29
29
|
---
|
|
30
30
|
|
|
31
31
|
## Handoffs entre agentes
|
|
32
|
-
Se este conjunto de tasks atravessa papéis (Product → SDD Architect → Worker → Governance), registre handoff via `
|
|
32
|
+
Se este conjunto de tasks atravessa papéis (Product → SDD Architect → Worker → Governance), registre handoff via `npm run hermes:handoff` pelo core (ADR-0005).
|
|
33
|
+
|
|
34
|
+
## Evidências e estado real
|
|
35
|
+
- Relacione cada critério AC à task responsável e ao comando ou observação que o verifica.
|
|
36
|
+
- Registre resultado, data e limitações; marque concluído somente após verificar.
|
|
37
|
+
- Diferencie hipótese, estimativa e medição. Remova exemplos que não se aplicam.
|
|
38
|
+
- Documente falhas esperadas, compatibilidade e recuperação quando houver mudança de contrato.
|
|
39
|
+
- Para LLMs, separe sucesso de execução, formato válido e aceite por checks independentes.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Plan: Instruções de agentes v4
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
|
|
6
|
+
Centralizar comportamento em docs/agent-operating-contract.md; manter procedimentos de papel nos prompts e agentes. Atualizar skill e templates. Incluir skills/ no tarball. Doctor deriva scripts válidos do package.json, assim como já deriva comandos de projetos gerados.
|
|
7
|
+
|
|
8
|
+
Validação: quick_validate da skill, testes health/harness/spec-cli, suíte completa, types:check, tools:doctor e gate do tarball após commit. Recuperação por revert do commit; sem migração de dados.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Spec: Instruções de agentes v4
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-039
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-05
|
|
7
|
+
|
|
8
|
+
## Problema e escopo
|
|
9
|
+
Prompts e skills citavam comandos antigos, confundiam execução com aceite e prescreviam rotinas sem evidência. Atualizar as superfícies ativas e templates sem reescrever specs históricas. Corrigir o falso positivo do doctor para scripts npm do checkout.
|
|
10
|
+
|
|
11
|
+
## Critérios de aceite
|
|
12
|
+
- [x] AC-1: Seis prompts e agentes compartilham contrato de contexto, autorização e evidências.
|
|
13
|
+
- [x] AC-2: Skill de LLM possui frontmatter válido e é incluída no pacote.
|
|
14
|
+
- [x] AC-3: Templates SDD orientam evidência por critério; instruções nativas apontam o contrato.
|
|
15
|
+
- [x] AC-4: Doctor reconhece scripts reais; teste mantém rejeição de comandos inexistentes.
|
|
16
|
+
|
|
17
|
+
## Restrições
|
|
18
|
+
Não alegar disponibilidade de modelos, custos medidos ou aceite sem verificação. Não alterar semântica dos adapters LLM nesta revisão.
|
|
19
|
+
|
|
20
|
+
## Evidências
|
|
21
|
+
Em 2026-09-05: 473 testes passaram; types:check, build, tools:doctor e quick_validate da skill passaram. Publicação e CI são acompanhados após o commit; não constituem aceite editorial local.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Tasks: Instruções de agentes v4
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: done
|
|
6
|
+
|
|
7
|
+
- [x] T1: Atualizar contrato, prompts e agentes (AC-1).
|
|
8
|
+
- [x] T2: Validar skill e incluir no pacote (AC-2).
|
|
9
|
+
- [x] T3: Atualizar instruções e templates (AC-3).
|
|
10
|
+
- [x] T4: Verificar regressão do doctor e suíte (AC-4): 473 testes, tipos, build e doctor passaram.
|
|
11
|
+
|
|
12
|
+
Gate de release e CI serão executados sobre o commit publicado.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Plan: Integrações LLM
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-05
|
|
6
|
+
|
|
7
|
+
## Abordagem e contratos
|
|
8
|
+
|
|
9
|
+
Estender packages/llm com timeoutMs, reasoningEffort, stdin e normalização de eventos Codex.
|
|
10
|
+
Manter perfil version 1 e adaptadores legados. Criar helper de composição de contexto em lib/llm.
|
|
11
|
+
scripts/llm-fit usa o prompt completo, telemetria normalizada e validationStatus inconclusive.
|
|
12
|
+
Doctor verifica --json e --sandbox no help do Codex sem autenticar ou consumir tokens.
|
|
13
|
+
|
|
14
|
+
## Fluxo
|
|
15
|
+
|
|
16
|
+
Perfil validado → arquivos de contexto → prompt completo → subprocesso sem shell → normalização
|
|
17
|
+
→ observação sem conteúdo → resposta ao operador com execução, validação e origem dos tokens.
|
|
18
|
+
|
|
19
|
+
## Impacto
|
|
20
|
+
|
|
21
|
+
- packages/llm/src/index.ts: contratos e execução; único chamador de produção em scripts/llm-fit.ts.
|
|
22
|
+
- scripts/llm-fit.ts: contexto, doctor, observação e resposta.
|
|
23
|
+
- lib/llm/context.ts e lib/llm/codex-output.ts: helpers testáveis.
|
|
24
|
+
- test/llm-fit.test.js, test/cost-economy.test.js e novos testes de integração.
|
|
25
|
+
- docs/llm-fit-loop.md: exemplos e limites; nenhuma alteração de schema SQLite.
|
|
26
|
+
|
|
27
|
+
## Decisão
|
|
28
|
+
|
|
29
|
+
[ADR-0080](../../memory/90-decisions/0080-llm-execution-evidence.md). Contratos HTTP, schema da
|
|
30
|
+
resposta final e retomada serão tratados em etapas próprias. Nenhuma nova dependência.
|
|
31
|
+
|
|
32
|
+
## Validação e rollout
|
|
33
|
+
|
|
34
|
+
Testes locais com executáveis fixture, tipos, build, spec:check, gsd:check e project:check.
|
|
35
|
+
Codegraph ausente: code:check/code:impact executados e fallback manual com rg; AST indisponível.
|
|
36
|
+
Sem publicação. Alteração pública intencional: custo desconhecido será null e não zero.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
## Evidências da entrega — 2026-09-05
|
|
40
|
+
|
|
41
|
+
- npm test: 467 testes passaram, zero falhas e zero skips.
|
|
42
|
+
- npm run types:check e npm run build: passaram.
|
|
43
|
+
- spec:check, gsd:check e project:check: passaram; maturidade estrutural reportada em 100%.
|
|
44
|
+
- tools:doctor: núcleo operante; ferramentas opcionais ausentes e memória ainda não sincronizada.
|
|
45
|
+
- git diff --check: passou.
|
|
46
|
+
- Compatibilidade de flags conferida também no help local do Codex 0.153.4.
|
|
47
|
+
- Nenhuma chamada real a LLM: integração exercitada por executáveis fixture sem rede.
|
|
48
|
+
- Workspace operacional: /home/apk/github/forja-workspace, selecionado via FORJA_WORKSPACE;
|
|
49
|
+
não houve alteração na configuração global do usuário.
|
|
50
|
+
|
|
51
|
+
## Continuidade
|
|
52
|
+
|
|
53
|
+
Etapa 1 concluída. A próxima entrega é retomada por sessão e validação independente, seguida
|
|
54
|
+
pelos benchmarks e melhorias de cache/MCP registrados na visão do produto. O fato de esta spec
|
|
55
|
+
estar done não significa que as demais etapas foram implementadas.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Spec: Integrações LLM com contexto e execução verificável
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-037
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: Allan Pablo / Codex
|
|
6
|
+
- **Criado em**: 2026-09-05
|
|
7
|
+
- **Sprint alvo**: Integrações LLM — etapa 1
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0080](../../memory/90-decisions/0080-llm-execution-evidence.md)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
llm:run registra caminhos de contexto sem enviar os arquivos. Codex usa saída textual e uma
|
|
13
|
+
opção de aprovação incompatível com exec da CLI instalada. Exit zero não comprova entrega válida.
|
|
14
|
+
|
|
15
|
+
## 2. Proposta de valor
|
|
16
|
+
|
|
17
|
+
Executar modelos com contexto selecionado, parâmetros explícitos e evidências sobre execução,
|
|
18
|
+
consumo e validação ainda pendente.
|
|
19
|
+
|
|
20
|
+
## 3. User stories
|
|
21
|
+
|
|
22
|
+
- Como desenvolvedor, quero enviar contexto por qualquer adaptador.
|
|
23
|
+
- Como operador, quero configurar GPT-6 e distinguir falhas do provedor de respostas válidas.
|
|
24
|
+
- Como mantenedor, quero testar contratos sem rede ou credenciais.
|
|
25
|
+
|
|
26
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
27
|
+
|
|
28
|
+
- [x] AC-1: Arquivos --context são incluídos em ordem, sem duplicação; arquivo ausente impede iniciar o provedor.
|
|
29
|
+
- [x] AC-2: Perfis v1 seguem válidos; timeoutMs e reasoningEffort são opcionais e validados. Esforço exclusivo do Codex nesta etapa.
|
|
30
|
+
- [x] AC-3: Codex recebe prompt por stdin, JSONL, sandbox read-only e aprovação never via configuração; modelo explícito quando configurado.
|
|
31
|
+
- [x] AC-4: Eventos produzem resposta, sessionId e tokens do provedor; stream inválido, incompleto ou com falha não vira sucesso.
|
|
32
|
+
- [x] AC-5: Saída distingue execução de validação inconclusiva; estimativas identificadas e preço desconhecido não apresentado como zero confirmado.
|
|
33
|
+
- [x] AC-6: Forja persiste somente metadados; hash representa todo o prompt enviado.
|
|
34
|
+
- [x] AC-7: Testes locais cobrem contratos, contexto, falhas, consumo e perfis existentes; tipos e build passam.
|
|
35
|
+
|
|
36
|
+
## 5. Escopo
|
|
37
|
+
|
|
38
|
+
**Dentro**: etapa 1 da [visão](../../docs/llm-evolution.md): contexto, timeout, Codex estruturado,
|
|
39
|
+
exemplo GPT-6, compatibilidade de flags via doctor e documentação.
|
|
40
|
+
|
|
41
|
+
**Fora desta etapa**: chamadas pagas, retomada, schema arbitrário da resposta, validação de patches,
|
|
42
|
+
novos adaptadores HTTP, cache remoto e roteamento automático.
|
|
43
|
+
|
|
44
|
+
## 6. NFRs / restrições
|
|
45
|
+
|
|
46
|
+
Sem novas dependências ou shell. Autenticação permanece no provedor. Sem ampliar permissões.
|
|
47
|
+
Doctor não comprova acesso ao modelo. Conteúdo é devolvido ao operador, mas não persistido no Forja.
|
|
48
|
+
|
|
49
|
+
## 7. Riscos e mitigação
|
|
50
|
+
|
|
51
|
+
| Risco | Mitigação |
|
|
52
|
+
|---|---|
|
|
53
|
+
| Protocolo Codex muda | Ignorar eventos novos; exigir conclusão válida; fixtures documentadas |
|
|
54
|
+
| Custo confundido com cobrança | Rotular estimativa e preço desconhecido |
|
|
55
|
+
| CLI antiga | Doctor verifica flags de exec sem executar modelo |
|
|
56
|
+
| Codegraph ausente | Mapear chamadores com rg e registrar limitação |
|
|
57
|
+
|
|
58
|
+
## 8. Métricas de sucesso
|
|
59
|
+
|
|
60
|
+
Sete critérios cobertos nesta entrega. Em 30 dias medir falhas de integração. Qualidade da entrega
|
|
61
|
+
ainda depende de validação independente, prevista na próxima etapa.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Tasks: Integrações LLM
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: done
|
|
6
|
+
- **Criado em**: 2026-09-05
|
|
7
|
+
|
|
8
|
+
## T1 — Contexto e perfis
|
|
9
|
+
|
|
10
|
+
- **Owner**: Codex
|
|
11
|
+
- **Paths**: lib/llm/context.ts, packages/llm/src/index.ts
|
|
12
|
+
- [x] Incluir contextos reais e validar campos opcionais.
|
|
13
|
+
|
|
14
|
+
## T2 — Protocolo Codex e evidências
|
|
15
|
+
|
|
16
|
+
- **Owner**: Codex
|
|
17
|
+
- **Depende de**: T1
|
|
18
|
+
- **Paths**: lib/llm/codex-output.ts, scripts/llm-fit.ts
|
|
19
|
+
- [x] Normalizar eventos e falhas; distinguir estimativa, execução e validação.
|
|
20
|
+
- [x] Verificar compatibilidade de flags no doctor.
|
|
21
|
+
|
|
22
|
+
## T3 — Verificação e documentação
|
|
23
|
+
|
|
24
|
+
- **Owner**: Codex
|
|
25
|
+
- **Depende de**: T2
|
|
26
|
+
- **Paths**: test/, docs/llm-fit-loop.md
|
|
27
|
+
- [x] Fixtures sem rede, regressões, tipos, build e gates do Forja.
|
|
28
|
+
- [x] Documentar exemplo GPT-6 e limitações; registrar handoff de review.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Plan: Sessões e validação LLM
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-05
|
|
6
|
+
|
|
7
|
+
## Arquitetura
|
|
8
|
+
|
|
9
|
+
Reusar SqliteJsonRepository para metadados de sessões e evidências. Vincular sessão ao caminho
|
|
10
|
+
real do projeto e fingerprint do perfil de execução (provedor, modelo, comando, argumentos e
|
|
11
|
+
privacidade). Esforço e timeout podem mudar sem trocar a identidade.
|
|
12
|
+
|
|
13
|
+
Estender buildLlmExecution com opções resume/outputSchema. Resume só Codex, ID explícito e sem
|
|
14
|
+
seleção automática da última sessão. Opções exec/resume verificadas no help local 0.153.4.
|
|
15
|
+
|
|
16
|
+
Criar lib/llm/validation.ts com compilação Ajv e execução sequencial dos checks via runLlm.
|
|
17
|
+
Pré-carregar manifest e schema antes de chamar provedor. Schema valida formato; aprovação de
|
|
18
|
+
tarefa exige checks locais. scripts/llm-fit.ts coordena e grava evidências sanitizadas.
|
|
19
|
+
|
|
20
|
+
## Impacto e dependências
|
|
21
|
+
|
|
22
|
+
- packages/llm: construção de argv; chamado por scripts/llm-fit.ts e testes.
|
|
23
|
+
- lib/llm/session.ts e validation.ts: metadados e verificação; Ajv 8 como dependência runtime.
|
|
24
|
+
- packages/evals: métricas adicionais de validação, preservando métricas existentes.
|
|
25
|
+
- docs/llm-fit-loop.md: comandos e exemplos; nenhum comando novo no registry.
|
|
26
|
+
- Sem migration: coleções adicionais em forja_records existente.
|
|
27
|
+
|
|
28
|
+
Codegraph ausente; code:check/code:impact executados e chamadas mapeadas com rg.
|
|
29
|
+
Testar com fixtures independentes do provedor, depois suíte completa, tipos, build e gates.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## Evidências da entrega — 2026-09-05
|
|
33
|
+
|
|
34
|
+
- npm test: 472 testes passaram, zero falhas e zero skips.
|
|
35
|
+
- npm run types:check e npm run build: passaram.
|
|
36
|
+
- spec:check, gsd:check e project:check: passaram.
|
|
37
|
+
- tools:doctor: núcleo operante; ferramentas opcionais ausentes e memória ainda não sincronizada.
|
|
38
|
+
- git diff --check: passou.
|
|
39
|
+
- Argv de retomada conferido no parser/help local do Codex 0.153.4, sem iniciar modelo.
|
|
40
|
+
- Fixtures exercitam sessão inicial e continuação, isolamento de projeto e perfil, troca indevida
|
|
41
|
+
de sessão, schemas draft-07/2020-12, checks de requisito, timeout e persistência sem conteúdo.
|
|
42
|
+
- Ajv 8.20.0 instalado como dependência runtime; npm também alinhou a versão raiz do lockfile
|
|
43
|
+
à versão 3.0.0 já declarada no package.json.
|
|
44
|
+
- Não houve chamada real a LLM. Acesso da conta ao GPT-6 e retenção de sessões do provedor
|
|
45
|
+
não foram exercitados nesta entrega.
|
|
46
|
+
|
|
47
|
+
## Continuidade
|
|
48
|
+
|
|
49
|
+
Etapa 2 concluída. Próximo escopo: benchmark com tarefas reais e melhoria das recomendações por
|
|
50
|
+
qualidade, custo, risco e latência. Cache/API e MCP continuam nas etapas posteriores da visão.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Spec: Retomada de sessões e validação independente
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-038
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: Allan Pablo / Codex
|
|
6
|
+
- **Criado em**: 2026-09-05
|
|
7
|
+
- **Sprint alvo**: Integrações LLM — etapa 2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0081](../../memory/90-decisions/0081-llm-resume-validation.md)
|
|
9
|
+
|
|
10
|
+
## Problema e valor
|
|
11
|
+
|
|
12
|
+
A etapa 1 retorna uma sessão e separa execução de validação, mas não permite continuar essa
|
|
13
|
+
sessão pelo Forja nem verificar respostas e requisitos com evidência independente.
|
|
14
|
+
Esta entrega torna possível continuar uma conversa conhecida e validar a saída usando contratos
|
|
15
|
+
JSON e comandos de teste escolhidos previamente pelo operador.
|
|
16
|
+
|
|
17
|
+
## Critérios de aceite
|
|
18
|
+
|
|
19
|
+
- [x] AC-1: --resume ID continua uma sessão Codex registrada pelo Forja no mesmo projeto e perfil; ID desconhecido, troca de configuração ou provedor incompatível falha antes da chamada.
|
|
20
|
+
- [x] AC-2: O Forja envia somente o novo prompt/contexto, sem replay ou retry automático, preservando sandbox read-only e approval never.
|
|
21
|
+
- [x] AC-3: --output-schema FILE compila JSON Schema localmente antes da chamada e valida a resposta sem coerção. Codex recebe também a opção nativa de schema.
|
|
22
|
+
- [x] AC-4: --validation FILE carrega checks explícitos antes da chamada; executa argv sem shell, com timeout e resposta por stdin; falha do modelo ou schema inválido não executa os checks.
|
|
23
|
+
- [x] AC-5: Aprovação de formato não aprova a tarefa. Sem checks independentes, validationStatus é inconclusive. Check reprovado retorna exit 2; execução do modelo continua distinguível.
|
|
24
|
+
- [x] AC-6: Persistir sessão e evidências (hashes, nomes, códigos, duração) sem prompt, resposta ou logs dos checks; métricas separam sucesso de execução de validação.
|
|
25
|
+
- [x] AC-7: Testes cobrem retomada real por fixture, isolamento de projeto/perfil, schemas, falhas, timeout e privacidade. Tipos, build e gates passam.
|
|
26
|
+
|
|
27
|
+
## Restrições e limites
|
|
28
|
+
|
|
29
|
+
CLIs continuam responsáveis por credenciais e histórico. A retomada depende de a sessão ainda
|
|
30
|
+
existir no provedor. Não há garantia de exatamente uma execução de ações pelo modelo, nem replay
|
|
31
|
+
pelo Forja. Esta etapa não coordena retomadas concorrentes da mesma sessão.
|
|
32
|
+
Checks são programas confiáveis escolhidos pelo operador; rodam nas permissões do processo Forja.
|
|
33
|
+
O modelo não escolhe comandos de validação. Aprovação é limitada aos checks configurados.
|
|
34
|
+
Schemas draft-07 e 2020-12 são aceitos via Ajv síncrono, sem refs remotos nem formatos/plugins extras.
|
|
35
|
+
Roteamento, benchmark e cache seguem nas próximas etapas da visão.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Tasks: Sessões e validação
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: done
|
|
6
|
+
- **Criado em**: 2026-09-05
|
|
7
|
+
|
|
8
|
+
## T1 — Sessões (Codex)
|
|
9
|
+
- **Owner**: Codex
|
|
10
|
+
- [x] Opções e validação de retomada, metadados sem conteúdo, isolamento por projeto/perfil.
|
|
11
|
+
|
|
12
|
+
## T2 — Validação (Codex)
|
|
13
|
+
- **Owner**: Codex
|
|
14
|
+
- [x] Schema síncrono, manifest explícito, subprocessos com timeout, evidências sem conteúdo.
|
|
15
|
+
- [x] Integrar status, exit codes e métricas de validação.
|
|
16
|
+
|
|
17
|
+
## T3 — Entrega (Codex)
|
|
18
|
+
- **Owner**: Codex
|
|
19
|
+
- [x] Testes positivos e negativos, tipos, build, gates, documentação e handoff de review.
|