forjajs 2.0.3 → 3.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.
Files changed (160) hide show
  1. package/.claude/agents/release-auditor.md +19 -10
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +80 -0
  4. package/DOC-MAP.md +9 -0
  5. package/README.md +85 -5
  6. package/README.pt-BR.md +34 -5
  7. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  8. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  9. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  10. package/dist/apps/server/src/forja-nest.module.js +9 -4
  11. package/dist/apps/server/src/main.js +10 -1
  12. package/dist/bin/forja.js +14 -2
  13. package/dist/lib/code-context.js +6 -0
  14. package/dist/lib/core/architecture-gate.d.ts +20 -0
  15. package/dist/lib/core/architecture-gate.js +60 -0
  16. package/dist/lib/core/doc-graph.js +6 -4
  17. package/dist/lib/core/drift-gate.d.ts +18 -0
  18. package/dist/lib/core/drift-gate.js +55 -0
  19. package/dist/lib/core/gates.d.ts +9 -2
  20. package/dist/lib/core/gates.js +13 -2
  21. package/dist/lib/core/health.js +15 -0
  22. package/dist/lib/core/incident-search.d.ts +19 -0
  23. package/dist/lib/core/incident-search.js +32 -0
  24. package/dist/lib/core/model-pricing.d.ts +31 -0
  25. package/dist/lib/core/model-pricing.js +74 -0
  26. package/dist/lib/core/registry.d.ts +248 -0
  27. package/dist/lib/core/registry.js +249 -0
  28. package/dist/lib/core/release.d.ts +247 -0
  29. package/dist/lib/core/release.js +5 -1
  30. package/dist/lib/core/risk-collect.d.ts +19 -0
  31. package/dist/lib/core/risk-collect.js +173 -0
  32. package/dist/lib/drift-sentinel.d.ts +59 -0
  33. package/dist/lib/drift-sentinel.js +126 -0
  34. package/dist/lib/generators/memory-generator.js +8 -6
  35. package/dist/lib/generators/nest-generator.js +24 -10
  36. package/dist/lib/project-upgrade.js +1 -1
  37. package/dist/lib/workspace.d.ts +7 -0
  38. package/dist/lib/workspace.js +34 -5
  39. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  40. package/dist/packages/adapter-git/src/index.js +11 -6
  41. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  42. package/dist/packages/adapter-nest/src/index.js +26 -1
  43. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  44. package/dist/packages/adapter-sqlite/src/index.js +49 -0
  45. package/dist/packages/contracts/src/index.d.ts +33 -0
  46. package/dist/packages/contracts/src/index.js +13 -0
  47. package/dist/packages/core/src/index.d.ts +12 -0
  48. package/dist/packages/core/src/index.js +29 -0
  49. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  50. package/dist/packages/engineering/architecture/src/index.js +131 -0
  51. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  52. package/dist/packages/engineering/evidence/src/index.js +31 -0
  53. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  54. package/dist/packages/engineering/identity/src/index.js +88 -0
  55. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  56. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  57. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  58. package/dist/packages/engineering/provenance/src/index.js +21 -0
  59. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  60. package/dist/packages/engineering/risk/src/index.js +120 -0
  61. package/dist/packages/graph/src/index.d.ts +23 -1
  62. package/dist/packages/graph/src/index.js +88 -15
  63. package/dist/packages/llm/src/index.d.ts +43 -0
  64. package/dist/packages/llm/src/index.js +131 -0
  65. package/dist/packages/mcp/src/index.js +27 -8
  66. package/dist/packages/orchestration/src/index.d.ts +11 -1
  67. package/dist/packages/orchestration/src/index.js +34 -7
  68. package/dist/packages/policy/src/index.d.ts +40 -0
  69. package/dist/packages/policy/src/index.js +39 -4
  70. package/dist/packages/runtime/src/index.js +3 -0
  71. package/dist/packages/sandbox/src/index.d.ts +47 -0
  72. package/dist/packages/sandbox/src/index.js +59 -0
  73. package/dist/packages/validator/src/index.d.ts +8 -0
  74. package/dist/packages/validator/src/index.js +21 -6
  75. package/dist/scripts/adr.d.ts +17 -0
  76. package/dist/scripts/adr.js +152 -0
  77. package/dist/scripts/agent-harness.js +14 -4
  78. package/dist/scripts/agent.d.ts +27 -0
  79. package/dist/scripts/agent.js +249 -0
  80. package/dist/scripts/architecture.d.ts +16 -0
  81. package/dist/scripts/architecture.js +186 -0
  82. package/dist/scripts/cost-economy.d.ts +2 -0
  83. package/dist/scripts/cost-economy.js +79 -0
  84. package/dist/scripts/demo-autonomy.js +15 -8
  85. package/dist/scripts/demo-workspace.d.ts +6 -0
  86. package/dist/scripts/demo-workspace.js +101 -0
  87. package/dist/scripts/drift-check.d.ts +17 -0
  88. package/dist/scripts/drift-check.js +63 -0
  89. package/dist/scripts/engineer.d.ts +20 -0
  90. package/dist/scripts/engineer.js +208 -0
  91. package/dist/scripts/evidence.d.ts +12 -0
  92. package/dist/scripts/evidence.js +55 -0
  93. package/dist/scripts/gates.d.ts +6 -2
  94. package/dist/scripts/gates.js +14 -4
  95. package/dist/scripts/incident.d.ts +19 -0
  96. package/dist/scripts/incident.js +103 -0
  97. package/dist/scripts/llm-fit.js +160 -0
  98. package/dist/scripts/provenance.d.ts +14 -0
  99. package/dist/scripts/provenance.js +114 -0
  100. package/dist/scripts/risk.d.ts +15 -0
  101. package/dist/scripts/risk.js +81 -0
  102. package/dist/scripts/simulate.d.ts +20 -0
  103. package/dist/scripts/simulate.js +150 -0
  104. package/dist/scripts/sync-universal-memory.js +19 -6
  105. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  106. package/docs/llm-fit-loop.md +41 -0
  107. package/docs/modos-de-operacao.md +52 -0
  108. package/docs/produto/factsheet-marketing.md +151 -0
  109. package/docs/produto/roteiro-demo.md +47 -0
  110. package/memory/40-delivery/current-sprint.md +3 -6
  111. package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
  112. package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
  113. package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
  114. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  115. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  116. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  117. package/package.json +9 -2
  118. package/specs/agent-identity-reputation/plan.md +133 -0
  119. package/specs/agent-identity-reputation/spec.md +125 -0
  120. package/specs/agent-identity-reputation/tasks.md +51 -0
  121. package/specs/agent-runtime-monitoring/plan.md +78 -0
  122. package/specs/agent-runtime-monitoring/spec.md +92 -0
  123. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  124. package/specs/ai-code-provenance/plan.md +71 -0
  125. package/specs/ai-code-provenance/spec.md +97 -0
  126. package/specs/ai-code-provenance/tasks.md +39 -0
  127. package/specs/architecture-constitution/plan.md +110 -0
  128. package/specs/architecture-constitution/spec.md +114 -0
  129. package/specs/architecture-constitution/tasks.md +58 -0
  130. package/specs/change-risk-engine/plan.md +130 -0
  131. package/specs/change-risk-engine/spec.md +119 -0
  132. package/specs/change-risk-engine/tasks.md +72 -0
  133. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  134. package/specs/drift-sentinel/spec.md +117 -0
  135. package/specs/engineer-facade-extension/plan.md +71 -0
  136. package/specs/engineer-facade-extension/spec.md +98 -0
  137. package/specs/engineer-facade-extension/tasks.md +36 -0
  138. package/specs/engineering-evidence-ledger/plan.md +121 -0
  139. package/specs/engineering-evidence-ledger/spec.md +90 -0
  140. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  141. package/specs/engineering-graph-extensions/plan.md +92 -0
  142. package/specs/engineering-graph-extensions/spec.md +101 -0
  143. package/specs/engineering-graph-extensions/tasks.md +60 -0
  144. package/specs/engineering-intelligence/spec.md +177 -0
  145. package/specs/learning-loop-incidents/plan.md +59 -0
  146. package/specs/learning-loop-incidents/spec.md +93 -0
  147. package/specs/learning-loop-incidents/tasks.md +36 -0
  148. package/specs/predictive-change-simulation/plan.md +109 -0
  149. package/specs/predictive-change-simulation/spec.md +107 -0
  150. package/specs/predictive-change-simulation/tasks.md +41 -0
  151. package/specs/release-auditor-health/plan.md +88 -0
  152. package/specs/release-auditor-health/spec.md +82 -0
  153. package/specs/release-auditor-health/tasks.md +72 -0
  154. package/specs/smart-agent-routing/plan.md +55 -0
  155. package/specs/smart-agent-routing/spec.md +85 -0
  156. package/specs/smart-agent-routing/tasks.md +26 -0
  157. package/dist/scripts/server-persistence-probe.d.ts +0 -1
  158. package/dist/scripts/server-persistence-probe.js +0 -52
  159. package/dist/scripts/server-persistence-probe.mjs +0 -52
  160. /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
@@ -0,0 +1,151 @@
1
+ # ForjaJS: Factsheet de Produto
2
+
3
+ **Versão de referência:** 2.0.3 com o LLM Fit Loop em desenvolvimento.
4
+
5
+ ## Mensagem central
6
+
7
+
8
+
9
+ ## Para quem é
10
+
11
+ - Desenvolvedores solo e times pequenos que usam IA como força principal de implementação.
12
+ - Tech leads que precisam limitar autonomia sem desacelerar o fluxo de entrega.
13
+ - Produtos que precisam manter decisões, specs e evidências entre sessões e entre ferramentas de IA.
14
+
15
+ Não é uma IDE, uma hospedagem de agentes, uma plataforma SaaS multi-tenant nem substitui Git.
16
+
17
+ ## Problema que resolve
18
+
19
+ Agentes de desenvolvimento são bons em uma sessão, mas normalmente não têm memória persistente,
20
+ processo verificável ou uma fronteira confiável entre sugestão e ação. Isso resulta em contexto
21
+ repetido, decisões perdidas, mudanças sem validação e autonomia baseada em confiança.
22
+
23
+ O ForjaJS adiciona a camada operacional ao redor do agente:
24
+
25
+ ```text
26
+ contexto e memória -> plano -> policy/aprovação -> execução isolada -> validação -> evidência
27
+ ```
28
+
29
+ ## O núcleo funcional
30
+
31
+ | Capacidade | O que entrega | Prova operacional |
32
+ | --- | --- | --- |
33
+ | CLI e Capability Registry | Capacidades versionadas, descobríveis e com entrada/saída validadas | `forja capabilities:list` e `forja capability:execute` |
34
+ | Policy Engine | Allow, deny, limites e aprovação para ações por risco | contratos e testes de policy/runtime |
35
+ | Runtime supervisionado | Execução com estado, checkpoints, pausa, retomada, retry limitado e orçamento | `test/runtime.test.js` |
36
+ | SDD/GSD | Spec, plano, tarefas, handoffs de sete campos e gates de governança | `forja spec:*`, `forja gsd:*`, `forja orchestrate:*` |
37
+ | Memória e contexto | SQLite local, evidências, contexto selecionado por orçamento e cache | `forja context:smart`, `forja benchmark:context` |
38
+ | GraphLoop | Grafo incremental de documentos, símbolos, relações e evidências | `forja graph:sync`, impacto e consultas GraphLoop |
39
+ | Sandbox Git | Worktree isolada, diff, promoção explícita e rollback | `forja demo:autonomy` |
40
+ | Validator | Resultado aceito, rejeitado, inconclusivo ou bloqueado por checks/evidências | `packages/validator` e testes de runtime |
41
+ | Observabilidade e evals | Observações locais, custo/tokens quando fornecidos e métricas determinísticas | `EvaluationEngine` e `llm:eval` |
42
+ | MCP e SDK | Acesso programático à mesma capability registry | `forja mcp:start` e `packages/sdk` |
43
+ | Plugins | Fronteiras permissionadas para extensões | manifests GitHub/Docker e Plugin SDK |
44
+
45
+ ## Fluxo de entrega
46
+
47
+ ```text
48
+ briefing -> spec -> plano -> tarefas -> implementação -> validação -> governança
49
+ | |
50
+ +-- contexto mínimo e evidências ----+
51
+ ```
52
+
53
+ O motor `orchestrate` mantém essa sequência como máquina de estados. Uma etapa só avança depois do
54
+ artefato exigido e do gate correspondente. O agente ou humano executa o trabalho; o ForjaJS controla
55
+ o processo, a política e a evidência.
56
+
57
+ ## LLM Fit Loop
58
+
59
+ O ForjaJS não exige um único fornecedor de modelo. O LLM Fit Loop integra CLIs já autenticadas pelo
60
+ operador, como Codex, Claude, Gemini, Ollama e executáveis compatíveis.
61
+
62
+ ```bash
63
+ forja llm:profiles:init
64
+ forja llm:doctor
65
+ forja llm:recommend --role worker --task implementation
66
+ forja llm:run --profile codex --task specs/minha-feature/spec.md
67
+ forja llm:eval --scope model --id codex:default
68
+ ```
69
+
70
+ O ciclo registra modelo, duração, resultado, referências de contexto e tokens estimados. A seleção é
71
+ uma recomendação explicável, não failover automático. Credenciais ficam na CLI do fornecedor; prompts
72
+ passados por `--prompt` são mascarados da trilha de auditoria.
73
+
74
+ ## Segurança e privacidade
75
+
76
+ - **Local-first:** SQLite, filesystem e Git local são as dependências padrão do fluxo comprovado.
77
+ - **Aprovação explícita:** ações de risco podem exigir uma aprovação persistida antes da execução.
78
+ - **Sandbox:** alterações são feitas em worktree e só chegam ao repositório por promoção explícita.
79
+ - **Rollback:** uma promoção pode ser revertida por operação auditável.
80
+ - **Sem shell para adapters LLM:** executáveis recebem `argv` estruturado.
81
+ - **Evidência separada de afirmação:** validação e GraphLoop carregam status e referências de prova.
82
+
83
+ ## Demonstrações que sustentam a mensagem
84
+
85
+ | Demonstração | O que mostra |
86
+ | --- | --- |
87
+ | `forja demo:autonomy` | fixture externa, Git worktree real, aprovação, teste, diff, promoção, SQLite, GraphLoop e handoff |
88
+ | `forja benchmark:context` | baseline, contexto selecionado, checksum, cache e estimativa de economia de tokens |
89
+ | `forja mcp:start` | transporte MCP JSON-RPC por stdio e tools derivadas do registry |
90
+ | `forja llm:profiles:init` + `llm:run` | adapters de LLM sem API key no framework e observação persistida |
91
+ | `forja demo:workspace` | workspace isolado e rotulado para demonstração de CLI e dashboard sem dados reais |
92
+
93
+ ## Mensagens prontas para marketing
94
+
95
+ ### Headline
96
+
97
+ **Pare de tratar agentes de código como chats descartáveis. Opere-os como um time de engenharia.**
98
+
99
+ ### Subheadline
100
+
101
+ ForjaJS adiciona memória, contexto econômico, política, sandbox e evidência ao fluxo de agentes de
102
+ desenvolvimento, sem exigir nuvem nem prender seu time a um provedor de LLM.
103
+
104
+ ### Diferenciais em três pontos
105
+
106
+ 1. **Memória que sobrevive:** contexto, decisions e handoffs continuam entre sessões e ferramentas.
107
+ 2. **Autonomia com limite:** policy, orçamento, sandbox e aprovação decidem o que pode acontecer.
108
+ 3. **Entrega comprovável:** validação independente, evidências e auditoria substituem “o agente disse
109
+ que terminou”.
110
+
111
+ ### Elevator pitch
112
+
113
+ ForjaJS é o control plane local-first para times que desenvolvem software com agentes de IA. Ele não
114
+ tenta substituir o modelo: organiza o processo ao redor dele, conectando contexto, execução
115
+ supervisionada, governança e memória em uma trilha auditável.
116
+
117
+ ## Claims permitidos
118
+
119
+ - “CLI-first e local-first para operação de agentes de desenvolvimento.”
120
+ - “Memória SQLite, contexto selecionado por orçamento e evidências persistentes.”
121
+ - “Execução supervisionada com policy, aprovação, sandbox Git e rollback explícito.”
122
+ - “Integração multi-LLM por adapters de CLI, sem API keys armazenadas no ForjaJS.”
123
+ - “MCP, SDK, REST/SSE e CLI sobre contratos versionados.”
124
+
125
+ ## Claims a evitar por enquanto
126
+
127
+ - “Autonomia total” ou “agentes trabalham sozinhos sem supervisão”.
128
+ - “Integração completa com GitHub ou Docker”: hoje existem boundaries/plugin manifests permissionados,
129
+ não clientes externos completos.
130
+ - “Economia fixa de tokens”: o benchmark usa proxy bytes/4 e varia por projeto/contexto.
131
+ - “Dashboard de produção”: o dashboard 2.x é parcial e a interface legada é opcional.
132
+ - ROI, redução de bugs, cobertura ou velocidade com percentuais sem telemetria do usuário.
133
+
134
+ ## Estado das superfícies visuais
135
+
136
+ - **Dashboard 2.x:** superfície de supervisão parcial via API; não é requisito do fluxo CLI-first.
137
+ - **Dashboard React/Vite legado:** útil para demonstração local de telas e navegação. Em 2026-08-17,
138
+ ele inicia em Node 24 com `better-sqlite3` 12 e expõe API local em `127.0.0.1:7777`; o frontend
139
+ Vite fica em `http://127.0.0.1:5173`. Um workspace sem projetos ou handoffs mostra coleções vazias,
140
+ não dados de demonstração inventados.
141
+ - O dashboard não executa LLMs diretamente: essa ação foi direcionada para `forja llm:run` para manter
142
+ policy, auditoria e privacidade.
143
+
144
+ ## Referências de engenharia
145
+
146
+ - Visão: `docs/vision/FORJA-2.0-VISION.md`
147
+ - Arquitetura: `docs/architecture/FORJA-2.0-ARCHITECTURE.md`
148
+ - Auditoria de implementação: `docs/2x/IMPLEMENTATION-AUDIT.md`
149
+ - LLM Fit Loop: `docs/llm-fit-loop.md`
150
+ - Roteiro de demonstração: `docs/produto/roteiro-demo.md`
151
+ - Decisões: `memory/90-decisions/`
@@ -0,0 +1,47 @@
1
+ # Roteiro de Demonstração: Atlas Pay
2
+
3
+ `forja demo:workspace` cria dados sintéticos e isolados para mostrar o produto sem acessar projetos
4
+ reais. O cenário não chama LLMs, não usa rede e não representa métricas de clientes.
5
+
6
+ ## Preparação
7
+
8
+ ```bash
9
+ forja demo:workspace
10
+ ```
11
+
12
+ O comando cria `~/forja-demo-workspace` com o projeto fictício `atlas-pay`, uma spec aprovada, plano,
13
+ tarefas, contexto, três handoffs, três observações e um perfil LLM local desabilitado.
14
+
15
+ Para abrir o dashboard sobre esse cenário, inicie os dois processos com o mesmo workspace:
16
+
17
+ ```bash
18
+ FORJA_WORKSPACE=~/forja-demo-workspace npm --prefix dashboard start
19
+ FORJA_WORKSPACE=~/forja-demo-workspace npm --prefix dashboard/web run dev
20
+ ```
21
+
22
+ No Windows PowerShell:
23
+
24
+ ```powershell
25
+ $env:FORJA_WORKSPACE = "$HOME\forja-demo-workspace"
26
+ npm --prefix dashboard start
27
+ ```
28
+
29
+ Abra `http://127.0.0.1:5173`. O dashboard mostra o estado vazio apenas se não estiver recebendo a
30
+ variável `FORJA_WORKSPACE` do cenário.
31
+
32
+ ## Sequência de apresentação
33
+
34
+ 1. Abra **Sistema**: mostra o projeto Atlas Pay, gates e a contagem de handoffs.
35
+ 2. Abra **Specs**: apresente problema, critérios de aceite, plano e tarefas aprovados.
36
+ 3. Abra **Handoffs**: há dois handoffs concluídos e um em review, todos marcados como demonstração.
37
+ 4. Abra **Memória** e **Tokens**: explique que contexto e observações são dados locais e consultáveis.
38
+ 5. Abra **Agentes** para mostrar o perfil `demo-ollama`: ele fica desabilitado até existir uma CLI
39
+ Ollama local, reforçando que o Forja não inventa disponibilidade de modelo.
40
+ 6. Mostre `forja demo:autonomy` separadamente para a prova de sandbox Git, aprovação e promoção real.
41
+
42
+ ## Regras de uso
43
+
44
+ - Nunca apresente Atlas Pay como cliente, case real ou métrica de produção.
45
+ - Não habilite o perfil `demo-ollama` sem uma instalação local de Ollama.
46
+ - Use `forja demo:workspace --path <diretório>` para criar outro cenário isolado.
47
+ - O comando recusa gravar em diretório existente que não tenha o selo `.context/forja-demo.json`.
@@ -11,12 +11,9 @@ framework-root (o repo do Forja — produtos vivem no workspace, ADR-0019)
11
11
  `tools:doctor` deixa de auditar só ferramentas opcionais e passa a ser gate do núcleo:
12
12
  ABI nativa, memória, workspace, deps de runtime, `.mcp.json`. Exit 1 no que trava o fluxo.
13
13
  - [x] `spec:new` mantém a allow-list do `.gitignore` — spec nova do framework nascia invisível ao git.
14
-
15
- ## Próximos candidatos (sem spec ainda)
16
- - `release-auditor` consumindo `lib/core/health.mjs` em vez de heurística própria — é a terceira
17
- superfície prevista no ADR-0023 e a única que ainda não migrou.
18
- - Checks de núcleo no CI (`tools:doctor` como step), fechando o ciclo: hoje o CI roda os testes,
19
- mas não o gate.
14
+ - [x] SPEC-022 — Release Auditor consome a saúde canônica (`specs/release-auditor-health/`)
15
+ `tools:doctor` passa a anteceder o gate estrito `release:check --publish`, sem probes duplicados
16
+ e sem substituir o modo de publicação por `check:all --full`.
20
17
 
21
18
  ## Ritual CLI
22
19
  - Planejar: npm run gsd:plan -- <slug> "<objetivo>"
@@ -0,0 +1,51 @@
1
+ # ADR-0074: LLM Fit Loop por adapters de CLI
2
+
3
+ - **Status**: proposed
4
+ - **Data**: 2026-08-17
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: llm, cli, observability, local-first, security
7
+
8
+ ## Contexto
9
+
10
+ O ForjaJS já preserva `Observation`, avaliação determinística e execução supervisionada, mas o
11
+ roteamento de LLMs era uma configuração estática de dashboard, com paths locais e sem evidência de
12
+ qual perfil funcionou para cada papel ou tarefa. Chamar SDKs diretamente concentraria credenciais no
13
+ framework e contrariaria a operação local-first. A escolha precisa continuar explícita, auditável e
14
+ independente do fornecedor.
15
+
16
+ ## Decisão
17
+
18
+ Adotar perfis de LLM no workspace e adapters de CLI sem shell. O Forja registra somente metadata de
19
+ execução e hashes: perfis, executável, modelo, tipo de tarefa, duração, tokens estimados e resultado.
20
+ Credenciais, prompts e respostas não são persistidos. `llm:recommend` ordena perfis por compatibilidade
21
+ declarada e observações locais; não altera a rota automaticamente.
22
+
23
+ ## Alternativas consideradas
24
+
25
+ - **SDKs/API keys de cada fornecedor no core**: rejeitada porque amplia a superfície de segredo,
26
+ acopla releases aos fornecedores e exclui CLIs autenticadas pelo operador.
27
+ - **Manter o routing no dashboard**: rejeitada porque uma superfície opcional não pode ser o caminho
28
+ de configuração, execução e auditoria de uma operação CLI-first.
29
+ - **Failover automático por custo ou latência**: rejeitada no MVP porque troca silenciosamente a
30
+ fronteira de privacidade e não possui evidência suficiente por tipo de tarefa.
31
+
32
+ ## Consequências
33
+
34
+ **Positivas**:
35
+ - Conectores de Codex, Claude, Gemini, Ollama e executáveis compatíveis usam um contrato único.
36
+ - A recomendação usa dados persistidos e a avaliação existente, sem uma LLM julgando outra LLM.
37
+ - Perfis são portáveis dentro do workspace e não expõem API keys.
38
+
39
+ **Negativas / Trade-offs**:
40
+ - Cada CLI continua responsável por autenticação, formato de custo e disponibilidade.
41
+ - Tokens são estimados por bytes/4 quando o adapter não fornece telemetria do provedor.
42
+ - A execução inicial é de leitura; mudanças de arquivos permanecem no runtime/sandbox supervisionado.
43
+ - O dashboard legado perde a execução direta de modelos; ele continua apenas como leitura/edição de
44
+ perfis do workspace.
45
+
46
+ ## Rastreamento
47
+
48
+ - Implementação: `packages/llm/src/index.ts`, `scripts/llm-fit.ts`, `lib/core/registry.ts`, `dashboard/server/`
49
+ - Testes: `test/llm-fit.test.js`
50
+ - Documentação: `docs/llm-fit-loop.md`, `skills/llm-provider-routing/SKILL.md`
51
+ - ADRs relacionadas: ADR-0037, ADR-0049, ADR-0052, ADR-0059
@@ -0,0 +1,43 @@
1
+ # ADR-0075: Workspace de demonstração isolado
2
+
3
+ - **Status**: proposed
4
+ - **Data**: 2026-08-17
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: demo, workspace, marketing, local-first
7
+
8
+ ## Contexto
9
+
10
+ O dashboard e a demonstração comercial precisam de artefatos visuais, mas usar dados reais de produto
11
+ expõe contexto e torna a apresentação irreproduzível. Uma UI vazia também não permite demonstrar o
12
+ fluxo SDD, handoffs, memória e observabilidade.
13
+
14
+ ## Decisão
15
+
16
+ Adicionar `forja demo:workspace`, que cria por padrão `~/forja-demo-workspace`, separado do workspace
17
+ de produção. O cenário é explicitamente marcado, contém apenas dados sintéticos e recusa escrever em
18
+ um diretório existente sem o selo de demo.
19
+
20
+ ## Alternativas consideradas
21
+
22
+ - **Preencher o workspace padrão**: rejeitada porque mistura dados de apresentação e dados reais.
23
+ - **Usar screenshots estáticos**: rejeitada porque não prova que CLI, SQLite e dashboard lêem o mesmo
24
+ cenário local.
25
+ - **Chamar uma LLM para gerar dados**: rejeitada porque torna a demo variável, pode exigir credenciais
26
+ e não acrescenta prova de produto.
27
+
28
+ ## Consequências
29
+
30
+ **Positivas**:
31
+ - Demonstrações reproduzíveis mostram artefatos reais do ForjaJS sem dados de cliente.
32
+ - Dashboard, CLI e observabilidade podem ser apresentados com a mesma fonte local.
33
+
34
+ **Negativas / Trade-offs**:
35
+ - Os dados precisam permanecer explicitamente rotulados como sintéticos.
36
+ - O cenário não substitui uma prova de autonomia com Git real, coberta por `demo:autonomy`.
37
+
38
+ ## Rastreamento
39
+
40
+ - Implementação: `scripts/demo-workspace.ts`, `lib/core/registry.ts`
41
+ - Testes: `test/demo-workspace.test.js`
42
+ - Documentação: `docs/produto/roteiro-demo.md`
43
+ - ADRs relacionadas: ADR-0019, ADR-0069, ADR-0074
@@ -0,0 +1,43 @@
1
+ # ADR-0076: Modos embedded e studio
2
+
3
+ - **Status**: proposed
4
+ - **Data**: 2026-08-17
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: workspace, cli, consumer-project, local-first
7
+
8
+ ## Contexto
9
+
10
+ ForjaJS é usado tanto como CLI de studio para criar produtos quanto como dependência dentro de um
11
+ projeto existente. Resolver sempre `~/forja-workspace` faz comandos de memória, LLM e auditoria de um
12
+ consumidor gravarem fora do repositório que estão operando.
13
+
14
+ ## Decisão
15
+
16
+ Adotar dois modos. `embedded` usa o `cwd` de um projeto consumidor para memória, specs, contexto e
17
+ auditoria. `studio` usa o workspace externo para catálogo e criação de múltiplos projetos. O core
18
+ detecta `package.json` no consumidor, força studio para comandos de catálogo e aceita
19
+ `FORJA_MODE=embedded|studio` como override explícito.
20
+
21
+ ## Alternativas consideradas
22
+
23
+ - **Workspace global obrigatório**: rejeitada porque viola isolamento do projeto consumidor.
24
+ - **Uma flag em cada comando**: rejeitada porque torna o caminho comum frágil e fácil de esquecer.
25
+ - **Detectar somente pela instalação global/local**: rejeitada porque binários podem ser chamados por
26
+ `npx`, symlink ou scripts; o `cwd` é a fonte confiável da superfície operada.
27
+
28
+ ## Consequências
29
+
30
+ **Positivas**:
31
+ - Um projeto que depende de ForjaJS carrega seus próprios artefatos e histórico.
32
+ - Studio permanece adequado para um operador que mantém vários produtos.
33
+
34
+ **Negativas / Trade-offs**:
35
+ - Scripts fora de um projeto precisam declarar `FORJA_MODE` quando quiserem embedded.
36
+ - Integrações antigas que presumem banco global devem usar explicitamente studio ou `FORJA_WORKSPACE`.
37
+
38
+ ## Rastreamento
39
+
40
+ - Implementação: `lib/workspace.ts`, `bin/forja.ts`, `scripts/sync-universal-memory.ts`
41
+ - Testes: `test/embedded-mode.test.js`
42
+ - Documentação: `docs/modos-de-operacao.md`
43
+ - ADRs relacionadas: ADR-0019, ADR-0032, ADR-0075
@@ -0,0 +1,95 @@
1
+ # ADR-0077: orçamento de autonomia por custo real (maxCostUsd)
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-09-01
5
+ - **Autor(es)**: apk
6
+ - **Tags**: policy, cost, observability, cli, llm
7
+
8
+ ## Contexto
9
+
10
+ `PolicyLimits` (`maxTokens`, `maxFiles`, `maxDurationMs`, `maxRetries`) ganhou enforcement real em
11
+ `CapabilityRegistry.checkLimits` na auditoria de segurança de 2026-08-31 (ADR-0074 cita o contexto do
12
+ LLM Fit Loop que motiva isso). Nenhum desses limites fala em dinheiro: um profile `codex:default` e um
13
+ `claude:opus` podem gastar o mesmo número de tokens e custar ordens de magnitude diferentes. Quem opera
14
+ múltiplos produtos/clientes ao mesmo tempo (o usuário principal do Forja) só descobre o estouro de
15
+ custo na fatura do provider — depois do fato. Ver SPEC-029 para o problema completo, ACs e riscos.
16
+
17
+ Duas perguntas estruturais tinham que ser respondidas antes de codificar:
18
+
19
+ 1. Onde mora o cálculo de custo, dado que `packages/core`/`policy`/`contracts` não podem importar uma
20
+ tabela de preço específica de provider (ver `docs/architecture/FORJA-2.0-ARCHITECTURE.md`, "Direção
21
+ de dependência" — domain core não conhece adapters)?
22
+ 2. O que fazer quando o provider/modelo de uma execução não está na tabela de preço local?
23
+
24
+ ## Decisão
25
+
26
+ **Cálculo de custo fica fora do domain core.** `CapabilityExecutionRequest` (packages/core) ganha um
27
+ campo opcional `estimatedCostUsd?: number`, calculado pelo CHAMADOR (o script/adapter que já sabe qual
28
+ modelo está em jogo) e só comparado contra `PolicyLimits.maxCostUsd` em `checkLimits` — o mesmo padrão
29
+ já usado para `budget.totalTokens` vs. `maxTokens`. `packages/core` nunca importa `lib/core/model-pricing.ts`
30
+ nem sabe o que é um "provider".
31
+
32
+ **Preço desconhecido é fail-open, e só para custo.** Quando o chamador não tem preço para o
33
+ provider/modelo (`estimatedCostUsd` ausente), `checkLimits` NÃO aplica `maxCostUsd` para aquela
34
+ chamada — a execução segue. Isto é uma exceção deliberada ao princípio "autonomia supervisionada por
35
+ padrão" que rege o resto do framework (onde a ausência de informação tende a bloquear, não liberar).
36
+ A justificativa: uma tabela de preço desatualizada ou incompleta é um problema de MANUTENÇÃO da tabela,
37
+ não um sinal de que o trabalho é ilegítimo — bloquear trabalho legítimo por um gap de catalogação é
38
+ pior que reportar um custo impreciso. O aviso (não o bloqueio) é o instrumento certo aqui: `forja
39
+ llm:doctor` reporta `pricing.known`/`pricing.stale` por profile, e `forja llm:run` avisa em stderr
40
+ quando grava uma observação sem custo computado.
41
+
42
+ **Tabela de preço local, versionada, com `asOf` por entrada.** `lib/core/model-pricing.json` +
43
+ `lib/core/model-pricing.ts` (loader/validador/calculadora puros, só fs — sem rede). Cada entrada carrega
44
+ `asOf`; `isPriceStale` (> 90 dias) alimenta o aviso de `llm:doctor` — mitigação direta do risco "tabela
45
+ desatualizada" do SPEC-029.
46
+
47
+ **Relatório é comando novo (`cost:economy`), não seção em `token:economy`.** `token:economy` mede
48
+ CENÁRIOS SINTÉTICOS de fixture (clean vs. flat, memória quente vs. fria) — nunca rodou um LLM de
49
+ verdade. `cost:economy` agrega OBSERVAÇÕES REAIS do `ObservationStore` (o mesmo que `llm:eval` usa),
50
+ multiplicadas pela tabela de preço. Misturar os dois faria "economia de token" parecer "economia de
51
+ custo" sobre números que nunca geraram custo real.
52
+
53
+ ## Alternativas consideradas
54
+
55
+ - **`packages/policy` importa a tabela de preço diretamente**: rejeitada — viola a direção de
56
+ dependência (domain core conhecendo pricing de provider, um detalhe de adapter).
57
+ - **Preço desconhecido bloqueia (fail-closed, como o resto do framework)**: rejeitada — transformaria
58
+ todo gap de manutenção da tabela em um incidente de produção, para um dado que é explicitamente
59
+ local/estático/não-sincronizado (ver "Fora" do SPEC-029). Documentado aqui como a ÚNICA exceção
60
+ deliberada ao fail-closed padrão, para não ser lida como inconsistência.
61
+ - **Estender `token:economy` in-place com uma seção de custo**: rejeitada — os dois eixos medem coisas
62
+ diferentes (fixture sintética vs. observação real); um comando irmão mantém a distinção honesta.
63
+ - **`Observation` ganha `projectId` para permitir "custo por projeto" literal**: adiada — cada projeto
64
+ já opera seu próprio workspace/DB (`FORJA_WORKSPACE`), então rodar `cost:economy` dentro do workspace
65
+ de um projeto já escopa o relatório a ele. Um campo `projectId` explícito em `Observation` é uma
66
+ mudança de contrato maior que o SPEC-029 não pede; fica para spec própria se a separação por
67
+ workspace se mostrar insuficiente.
68
+
69
+ ## Consequências
70
+
71
+ **Positivas**:
72
+ - `maxCostUsd` é opcional em todo lugar — regras de política existentes continuam funcionando sem
73
+ qualquer mudança (compatibilidade, NFR do SPEC-029).
74
+ - Nenhum pacote do domain core passa a conhecer preços de provider; a tabela pode mudar sem tocar
75
+ `packages/policy` ou `packages/core`.
76
+ - `llm:doctor` e `llm:run` já avisam sobre gaps de preço antes que virem surpresa de fatura.
77
+
78
+ **Negativas / Trade-offs**:
79
+ - Enforcement de `maxCostUsd` só é efetivo quando o CHAMADOR calcula e passa `estimatedCostUsd` —
80
+ capabilities que não passam por essa plumbing (a maioria dos comandos legados do CLI, que ainda não
81
+ passam por `CapabilityRegistry.execute`) não têm o limite aplicado automaticamente.
82
+ - "Preço desconhecido não bloqueia" significa que um `maxCostUsd` agressivo pode ser silenciosamente
83
+ ineficaz contra um provider fora da tabela — mitigado pelo aviso, não pelo bloqueio.
84
+ - `cost:economy` reporta por modelo, não por domínio/projeto explícito dentro de um mesmo workspace
85
+ (ver alternativa adiada acima).
86
+
87
+ ## Rastreamento
88
+
89
+ - Implementação: `packages/policy/src/index.ts`, `packages/core/src/index.ts`,
90
+ `lib/core/model-pricing.ts`, `lib/core/model-pricing.json`, `scripts/llm-fit.ts`,
91
+ `scripts/cost-economy.ts`, `lib/core/registry.ts`
92
+ - Testes: `test/policy.test.js`, `test/policy-registry.integration.test.js`,
93
+ `test/model-pricing.test.js`, `test/cost-economy.test.js`
94
+ - Spec: `specs/cost-aware-autonomy-budget/spec.md` (SPEC-029)
95
+ - ADRs relacionadas: ADR-0074 (LLM Fit Loop / adapters de CLI)
@@ -0,0 +1,116 @@
1
+ # ADR-0078: ForjaJS 3.0 — de framework de agentes a Engineering Control Plane
2
+
3
+ - **Status**: proposed
4
+ - **Data**: 2026-09-01
5
+ - **Autor(es)**: apk
6
+ - **Tags**: architecture, vision, graph, policy, engineering-intelligence
7
+
8
+ ## Contexto
9
+
10
+ A Forja 2.0 prova, em código real (não em documentação), quatro capacidades: um motor de política
11
+ com aprovação supervisionada (`packages/policy`), um runtime com checkpoint e retomada
12
+ (`packages/runtime`), um grafo de conhecimento com evidência e validade temporal
13
+ (`packages/graph`), e um sandbox real via git worktree (`packages/sandbox`,
14
+ `runSandboxedCapability`). `scripts/demo-autonomy.ts` fecha o ciclo de ponta a ponta.
15
+
16
+ A visão recebida propõe estender isso para um "Engineering Control Plane": a Forja passa a
17
+ entender não só código, mas **por que** o software existe (specs, requisitos), **como deveria
18
+ funcionar** (ADRs, arquitetura), **quem/o quê o mudou** (agentes, modelos, runs), e **o que
19
+ aconteceu depois** (incidentes, regressões). Isso é uma mudança de escopo real — de "orquestra
20
+ agentes com processo e memória" para "governa engenharia de software feita por agentes,
21
+ independente de que agente/modelo a fez".
22
+
23
+ A questão que este ADR decide: **isso é uma extensão incremental (2.x) ou uma mudança de versão
24
+ maior (3.0)?**
25
+
26
+ ## Decisão
27
+
28
+ **É ForjaJS 3.0.** Critério: uma mudança de versão maior é justificada quando o **modelo mental**
29
+ do produto muda, não quando a superfície de comando cresce. 2.0 já foi essa mudança uma vez (ADR
30
+ implícito em `docs/vision/FORJA-2.0-VISION.md`: de CLI 1.x para "plataforma local-first"). A
31
+ mudança agora é da mesma ordem: de "orquestra o trabalho de agentes de IA" para "é a fonte de
32
+ verdade de por que o sistema existe e se comporta como deveria, com ou sem IA envolvida" — o grafo
33
+ deixa de ser CodeGraph (código) e passa a ser Engineering Graph (produto + arquitetura + código +
34
+ runtime + histórico). Isso é incompatível com o critério "2.x incremental" porque nenhuma feature
35
+ isolada da visão é 3.0 — é o **conjunto**, com o grafo como eixo central de todas elas, que muda o
36
+ que a Forja *é*.
37
+
38
+ Consequência prática: as extensões de contrato descritas em
39
+ [`docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md`](../../docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md)
40
+ são aditivas (nenhum campo removido, nenhum comando quebrado) — 3.0 aqui é sobre *posicionamento e
41
+ modelo mental*, não sobre breaking changes de API. A Forja continua podendo ser descrita, ao final
42
+ da migração, sem versão nova de `CONTRACT_VERSION` forçada por isso sozinho; se algum sprint
43
+ subsequente exigir de fato um breaking change de contrato, esse será o gatilho para
44
+ `CONTRACT_VERSION = '3.0'`, decidido separadamente quando (e se) acontecer.
45
+
46
+ **Não** construímos nenhuma das 33 features da visão original diretamente. Este ADR autoriza:
47
+
48
+ 1. Um novo bounded context, `packages/engineering/{architecture,risk,provenance,identity}`,
49
+ seguindo a mesma regra de independência de framework de todo `packages/*` hoje (ADR-0020).
50
+ 2. Extensão aditiva de `packages/contracts`: vocabulário de tipos de nó/aresta de engenharia sobre
51
+ o `GraphNode.type`/`GraphEdge.type` já livres (nenhum novo contrato de grafo), `ArchitectureRule`,
52
+ `ChangeRiskAssessment`, `AgentProfile2` (nome provisório).
53
+ 3. Composição, nunca duplicação, de `PolicyEngine`, `GraphLoop`, `SandboxEngine`, `ContextEngine`,
54
+ `EvaluationEngine`, `EventBus` já existentes.
55
+ 4. Uma ordem de implementação em 3 sprints imediatos (Constitution → Risk Engine → Evidence Ledger
56
+ + façade `forja engineer`), com as fases seguintes da visão original (Provenance, Identity,
57
+ Simulation, Learning Loop, Autonomous Maintenance) especificadas só depois que essas três
58
+ estiverem em produção — ver `specs/engineering-intelligence/plan.md`.
59
+
60
+ ## Alternativas consideradas
61
+
62
+ - **Tratar como 2.x incremental** (uma feature de cada vez, sem ADR guarda-chuva) — rejeitada
63
+ porque a visão pede explicitamente um documento de arquitetura e um ADR principal antes de
64
+ qualquer código, e porque o próprio critério acima (mudança de modelo mental, não de superfície)
65
+ não se sustenta como "incremental".
66
+ - **Reescrever o framework do zero em torno do Engineering Graph** — rejeitada explicitamente pela
67
+ visão recebida ("Não: reescreva o framework do zero... remova funcionalidades existentes") e pelo
68
+ gap analysis: nenhuma peça existente precisa ser substituída, só estendida.
69
+ - **Um pacote monolítico `packages/engineering`** (sem sub-diretórios com fronteira própria) —
70
+ rejeitada porque Risk/Architecture/Provenance/Identity têm ritmos de mudança diferentes e
71
+ acoplá-los cedo repete o erro que `packages/core`/`policy`/`runtime` já evitaram ao se separar só
72
+ depois que a fronteira entre eles estava provada em uso real.
73
+ - **Motor de decisão de autonomia paralelo ao `PolicyEngine`** (Risk-Based Autonomy como sistema
74
+ próprio) — rejeitada; `PolicyEngine` já tem o vocabulário certo (`RiskLevel`,
75
+ `approvalRequiredRisks`, `ALLOW_WITH_LIMITS`/`REQUIRE_APPROVAL`) e passa a receber um assessment
76
+ de risco opcional em vez de ganhar um substituto.
77
+
78
+ ## Consequências
79
+
80
+ **Positivas**:
81
+ - Nenhum código existente muda de comportamento até que os sprints da Fase 1 comecem a consumir os
82
+ novos engines — risco de regressão zero na primeira entrega (que é só planejamento).
83
+ - O gap analysis (ver documento de arquitetura) mostra que ~80% dos "insumos" das 33 features já
84
+ existem no código de hoje — o trabalho real é composição e três motores novos, não uma
85
+ reescrita.
86
+ - `drift-sentinel` (SPEC-030) e `cost-aware-autonomy-budget` (SPEC-029), já em implementação nesta
87
+ mesma janela de trabalho, acabam sendo peças legítimas de Fase 1/Fase 3 desta visão maior
88
+ (Architecture Drift Detection e Cost Intelligence, respectivamente) — não é trabalho descartado.
89
+
90
+ **Negativas / Trade-offs**:
91
+ - O escopo total da visão (33 features, 7 fases) é grande demais para qualquer sprint único — este
92
+ ADR autoriza só a fundação (§19 do documento de arquitetura); fases posteriores exigirão ADRs e
93
+ specs próprias quando chegar a vez delas, o que significa esta decisão fica deliberadamente
94
+ incompleta até lá.
95
+ - `AgentProfile2` como nome provisório é uma dívida de nomenclatura assumida conscientemente —
96
+ ver Open Question #1 no documento de arquitetura, a resolver até o fim do Sprint 3.
97
+ - Adicionar um bounded context novo (`packages/engineering`) aumenta a superfície do monorepo;
98
+ mitigado por manter os quatro sub-domínios sem imports cruzados entre si desde o primeiro commit.
99
+
100
+ ## Constraints
101
+
102
+ Regra real, checável hoje (não hipotética) — a primeira que `architecture:compile` (SPEC-033)
103
+ compila deste repositório: `packages/policy` é domínio puro (ADR-0020), nunca deveria depender de
104
+ um driver de persistência concreto.
105
+
106
+ - packages/policy não depende de better-sqlite3
107
+
108
+ ## Rastreamento
109
+
110
+ - Documento de arquitetura: `docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md`
111
+ - Spec master: `specs/engineering-intelligence/spec.md` (SPEC-031)
112
+ - Specs de fundação: `specs/engineering-graph-extensions/` (SPEC-032),
113
+ `specs/architecture-constitution/` (SPEC-033), `specs/change-risk-engine/` (SPEC-034),
114
+ `specs/engineering-evidence-ledger/` (SPEC-035)
115
+ - ADRs relacionadas: ADR-0005 (handoff 7 campos), ADR-0019 (workspace), ADR-0020 (core/registry),
116
+ ADR-0072 (limites de segurança do sandbox), ADR-0074 (LLM Fit Loop)