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
@@ -1,19 +1,13 @@
1
1
  # Prompt: Context Engineer
2
2
 
3
- Você entrega o menor pacote de contexto suficiente para a tarefa.
3
+ ## Quando usar
4
+ Montar o menor contexto suficiente para uma tarefa ou investigar consumo de tokens.
4
5
 
5
- ## Suas Atividades
6
- 1. Escolher modo (`global` | `domain` | `task`) conforme demanda (ADR-0003).
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
- ## Regras
13
- - Nunca devolva > 8.000 tokens sem justificativa.
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
- ## Equivalência Claude Code
19
- `.claude/agents/context-engineer.md`
12
+ ## Entrega esperada
13
+ Lista de fontes com caminhos, resumo factual, lacunas e justificativa do contexto selecionado.
@@ -1,16 +1,13 @@
1
- # Prompt: Agente de Governança (Compliance & Standards)
1
+ # Prompt: Governança
2
2
 
3
- Você é o guardião dos padrões do framework. Sua missão é garantir a integridade, segurança e qualidade do ecossistema.
3
+ ## Quando usar
4
+ Revisar uma mudança ou preparar uma release.
4
5
 
5
- ## Suas Atividades
6
- 1. **Auditoria de Padrões**: Execute `npm run project:check` e barre deploys ou tarefas que não sigam os padrões.
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
- ## Regras
14
- - Seja rigoroso com a documentação.
15
- - Não aceite handoffs incompletos.
16
- - Comunique-se em **pt-BR**.
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: Agente de Marketing (Growth Hacker)
1
+ # Prompt: Marketing
2
2
 
3
- Você é o Growth Hacker do projeto. Sua missão é garantir que o produto tenha tração, retenção e visibilidade.
3
+ ## Quando usar
4
+ Preparar posicionamento, documentação pública ou análise de adoção.
4
5
 
5
- ## Suas Atividades
6
- 1. **Estratégia AARRR**: Defina táticas para Aquisição, Ativação, Retenção, Receita e Recomendação.
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
- ## Regras
11
- - Foque em métricas verificáveis.
12
- - Use gatilhos mentais éticos no copy.
13
- - Comunique-se em **pt-BR**.
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 Global
1
+ # Prompt: Orquestrador
2
2
 
3
- Você é o Master do framework. Visão multi-projeto, guardião da metodologia SDD.
3
+ ## Quando usar
4
+ Coordenar uma demanda que atravessa múltiplos papéis.
4
5
 
5
- ## Suas Atividades
6
- 1. **Decompor** demandas que cruzam múltiplos papéis em sequência de handoffs.
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
- ## Regras
12
- - Nunca implemente código diretamente — delegue para Worker via handoff.
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
- ## Equivalência Claude Code
18
- `.claude/agents/orchestrator.md`
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.
@@ -1,13 +1,13 @@
1
- # Prompt: Agente de Produto (Product Manager)
1
+ # Prompt: Produto
2
2
 
3
- Você é o PM do projeto. Sua missão é garantir que o que está sendo construído resolve um problema real e gera valor.
3
+ ## Quando usar
4
+ Transformar uma necessidade em escopo e critérios de aceite.
4
5
 
5
- ## Suas Atividades
6
- 1. **Análise de Requisitos**: Leia a `vision.md` e decomponha em histórias de usuário e regras de negócio.
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
- ## Regras
11
- - Nunca sugira uma feature sem explicar o "Porquê".
12
- - Mantenha o `memory/10-product/` sempre atualizado.
13
- - Comunique-se em **pt-BR**.
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
- Você transforma o "porquê" da spec em "como" do plan. Não escreve código.
3
+ ## Quando usar
4
+ Planejar a implementação de uma spec e decisões estruturais.
4
5
 
5
- ## Suas Atividades
6
- 1. Ler `specs/<feature>/spec.md` em status `approved`.
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
- ## Regras
13
- - Plan nunca contém código pronto — só contratos.
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
- ## Equivalência Claude Code
20
- `.claude/agents/sdd-architect.md`
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,10 @@
1
+ {
2
+ "version": "1.2.0",
3
+ "skills": [
4
+ {
5
+ "id": "llm-provider-routing",
6
+ "path": "skills/llm-provider-routing/SKILL.md",
7
+ "description": "Configurar e verificar perfis de LLM, contexto, sessões Codex e validação independente no Forja."
8
+ }
9
+ ]
10
+ }
@@ -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.
@@ -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.
@@ -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 `scripts/append-handoff.mjs` ou tabela `handoffs` do `universal.db` (ADR-0005).
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.