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.
- package/.claude/agents/release-auditor.md +19 -10
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +80 -0
- package/DOC-MAP.md +9 -0
- package/README.md +85 -5
- package/README.pt-BR.md +34 -5
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
- package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
- package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
- package/dist/apps/server/src/forja-nest.module.js +9 -4
- package/dist/apps/server/src/main.js +10 -1
- package/dist/bin/forja.js +14 -2
- package/dist/lib/code-context.js +6 -0
- package/dist/lib/core/architecture-gate.d.ts +20 -0
- package/dist/lib/core/architecture-gate.js +60 -0
- package/dist/lib/core/doc-graph.js +6 -4
- package/dist/lib/core/drift-gate.d.ts +18 -0
- package/dist/lib/core/drift-gate.js +55 -0
- package/dist/lib/core/gates.d.ts +9 -2
- package/dist/lib/core/gates.js +13 -2
- package/dist/lib/core/health.js +15 -0
- package/dist/lib/core/incident-search.d.ts +19 -0
- package/dist/lib/core/incident-search.js +32 -0
- package/dist/lib/core/model-pricing.d.ts +31 -0
- package/dist/lib/core/model-pricing.js +74 -0
- package/dist/lib/core/registry.d.ts +248 -0
- package/dist/lib/core/registry.js +249 -0
- package/dist/lib/core/release.d.ts +247 -0
- package/dist/lib/core/release.js +5 -1
- package/dist/lib/core/risk-collect.d.ts +19 -0
- package/dist/lib/core/risk-collect.js +173 -0
- package/dist/lib/drift-sentinel.d.ts +59 -0
- package/dist/lib/drift-sentinel.js +126 -0
- package/dist/lib/generators/memory-generator.js +8 -6
- package/dist/lib/generators/nest-generator.js +24 -10
- package/dist/lib/project-upgrade.js +1 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +34 -5
- package/dist/packages/adapter-git/src/index.d.ts +1 -1
- package/dist/packages/adapter-git/src/index.js +11 -6
- package/dist/packages/adapter-nest/src/index.d.ts +19 -0
- package/dist/packages/adapter-nest/src/index.js +26 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
- package/dist/packages/adapter-sqlite/src/index.js +49 -0
- package/dist/packages/contracts/src/index.d.ts +33 -0
- package/dist/packages/contracts/src/index.js +13 -0
- package/dist/packages/core/src/index.d.ts +12 -0
- package/dist/packages/core/src/index.js +29 -0
- package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
- package/dist/packages/engineering/architecture/src/index.js +131 -0
- package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
- package/dist/packages/engineering/evidence/src/index.js +31 -0
- package/dist/packages/engineering/identity/src/index.d.ts +57 -0
- package/dist/packages/engineering/identity/src/index.js +88 -0
- package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
- package/dist/packages/engineering/monitoring/src/index.js +40 -0
- package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
- package/dist/packages/engineering/provenance/src/index.js +21 -0
- package/dist/packages/engineering/risk/src/index.d.ts +89 -0
- package/dist/packages/engineering/risk/src/index.js +120 -0
- package/dist/packages/graph/src/index.d.ts +23 -1
- package/dist/packages/graph/src/index.js +88 -15
- package/dist/packages/llm/src/index.d.ts +43 -0
- package/dist/packages/llm/src/index.js +131 -0
- package/dist/packages/mcp/src/index.js +27 -8
- package/dist/packages/orchestration/src/index.d.ts +11 -1
- package/dist/packages/orchestration/src/index.js +34 -7
- package/dist/packages/policy/src/index.d.ts +40 -0
- package/dist/packages/policy/src/index.js +39 -4
- package/dist/packages/runtime/src/index.js +3 -0
- package/dist/packages/sandbox/src/index.d.ts +47 -0
- package/dist/packages/sandbox/src/index.js +59 -0
- package/dist/packages/validator/src/index.d.ts +8 -0
- package/dist/packages/validator/src/index.js +21 -6
- package/dist/scripts/adr.d.ts +17 -0
- package/dist/scripts/adr.js +152 -0
- package/dist/scripts/agent-harness.js +14 -4
- package/dist/scripts/agent.d.ts +27 -0
- package/dist/scripts/agent.js +249 -0
- package/dist/scripts/architecture.d.ts +16 -0
- package/dist/scripts/architecture.js +186 -0
- package/dist/scripts/cost-economy.d.ts +2 -0
- package/dist/scripts/cost-economy.js +79 -0
- package/dist/scripts/demo-autonomy.js +15 -8
- package/dist/scripts/demo-workspace.d.ts +6 -0
- package/dist/scripts/demo-workspace.js +101 -0
- package/dist/scripts/drift-check.d.ts +17 -0
- package/dist/scripts/drift-check.js +63 -0
- package/dist/scripts/engineer.d.ts +20 -0
- package/dist/scripts/engineer.js +208 -0
- package/dist/scripts/evidence.d.ts +12 -0
- package/dist/scripts/evidence.js +55 -0
- package/dist/scripts/gates.d.ts +6 -2
- package/dist/scripts/gates.js +14 -4
- package/dist/scripts/incident.d.ts +19 -0
- package/dist/scripts/incident.js +103 -0
- package/dist/scripts/llm-fit.js +160 -0
- package/dist/scripts/provenance.d.ts +14 -0
- package/dist/scripts/provenance.js +114 -0
- package/dist/scripts/risk.d.ts +15 -0
- package/dist/scripts/risk.js +81 -0
- package/dist/scripts/simulate.d.ts +20 -0
- package/dist/scripts/simulate.js +150 -0
- package/dist/scripts/sync-universal-memory.js +19 -6
- package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
- package/docs/llm-fit-loop.md +41 -0
- package/docs/modos-de-operacao.md +52 -0
- package/docs/produto/factsheet-marketing.md +151 -0
- package/docs/produto/roteiro-demo.md +47 -0
- package/memory/40-delivery/current-sprint.md +3 -6
- package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
- package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
- package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
- package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
- package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
- package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
- package/package.json +9 -2
- package/specs/agent-identity-reputation/plan.md +133 -0
- package/specs/agent-identity-reputation/spec.md +125 -0
- package/specs/agent-identity-reputation/tasks.md +51 -0
- package/specs/agent-runtime-monitoring/plan.md +78 -0
- package/specs/agent-runtime-monitoring/spec.md +92 -0
- package/specs/agent-runtime-monitoring/tasks.md +39 -0
- package/specs/ai-code-provenance/plan.md +71 -0
- package/specs/ai-code-provenance/spec.md +97 -0
- package/specs/ai-code-provenance/tasks.md +39 -0
- package/specs/architecture-constitution/plan.md +110 -0
- package/specs/architecture-constitution/spec.md +114 -0
- package/specs/architecture-constitution/tasks.md +58 -0
- package/specs/change-risk-engine/plan.md +130 -0
- package/specs/change-risk-engine/spec.md +119 -0
- package/specs/change-risk-engine/tasks.md +72 -0
- package/specs/cost-aware-autonomy-budget/spec.md +102 -0
- package/specs/drift-sentinel/spec.md +117 -0
- package/specs/engineer-facade-extension/plan.md +71 -0
- package/specs/engineer-facade-extension/spec.md +98 -0
- package/specs/engineer-facade-extension/tasks.md +36 -0
- package/specs/engineering-evidence-ledger/plan.md +121 -0
- package/specs/engineering-evidence-ledger/spec.md +90 -0
- package/specs/engineering-evidence-ledger/tasks.md +54 -0
- package/specs/engineering-graph-extensions/plan.md +92 -0
- package/specs/engineering-graph-extensions/spec.md +101 -0
- package/specs/engineering-graph-extensions/tasks.md +60 -0
- package/specs/engineering-intelligence/spec.md +177 -0
- package/specs/learning-loop-incidents/plan.md +59 -0
- package/specs/learning-loop-incidents/spec.md +93 -0
- package/specs/learning-loop-incidents/tasks.md +36 -0
- package/specs/predictive-change-simulation/plan.md +109 -0
- package/specs/predictive-change-simulation/spec.md +107 -0
- package/specs/predictive-change-simulation/tasks.md +41 -0
- package/specs/release-auditor-health/plan.md +88 -0
- package/specs/release-auditor-health/spec.md +82 -0
- package/specs/release-auditor-health/tasks.md +72 -0
- package/specs/smart-agent-routing/plan.md +55 -0
- package/specs/smart-agent-routing/spec.md +85 -0
- package/specs/smart-agent-routing/tasks.md +26 -0
- package/dist/scripts/server-persistence-probe.d.ts +0 -1
- package/dist/scripts/server-persistence-probe.js +0 -52
- package/dist/scripts/server-persistence-probe.mjs +0 -52
- /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
|
-
|
|
16
|
-
|
|
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)
|