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
|
@@ -4,11 +4,13 @@ import crypto from 'node:crypto';
|
|
|
4
4
|
import Database from 'better-sqlite3';
|
|
5
5
|
import { fileURLToPath } from 'node:url';
|
|
6
6
|
import { ensureSchema, getDbPath } from "./memory-schema.js";
|
|
7
|
-
import { initWorkspace, getProjectsDir, getWorkspaceSpecsDir, getWorkspaceProjectsMemoryDir, } from "../lib/workspace.js";
|
|
7
|
+
import { initWorkspace, getForjaMode, getWorkspaceRoot, getProjectsDir, getWorkspaceSpecsDir, getWorkspaceProjectsMemoryDir, } from "../lib/workspace.js";
|
|
8
8
|
const __filename = fileURLToPath(import.meta.url);
|
|
9
9
|
const __dirname = path.dirname(__filename);
|
|
10
10
|
const root = path.resolve(__dirname, '..');
|
|
11
11
|
initWorkspace();
|
|
12
|
+
const mode = getForjaMode();
|
|
13
|
+
const operationRoot = getWorkspaceRoot();
|
|
12
14
|
const dbPath = getDbPath();
|
|
13
15
|
const args = process.argv.slice(2);
|
|
14
16
|
const projectArgIndex = args.indexOf('--project');
|
|
@@ -233,9 +235,9 @@ function syncFiles(files, projectId = null) {
|
|
|
233
235
|
if (syncGlobal) {
|
|
234
236
|
log('Sincronizando Memória Global...', 'info');
|
|
235
237
|
const globalFiles = [
|
|
236
|
-
...walk(path.join(root, 'memory')),
|
|
237
|
-
...walk(path.join(root, 'docs')),
|
|
238
|
-
...walk(path.join(root, 'prompts')),
|
|
238
|
+
...walk(path.join(mode === 'embedded' ? operationRoot : root, 'memory')),
|
|
239
|
+
...walk(path.join(mode === 'embedded' ? operationRoot : root, 'docs')),
|
|
240
|
+
...walk(path.join(mode === 'embedded' ? operationRoot : root, 'prompts')),
|
|
239
241
|
];
|
|
240
242
|
syncFiles(globalFiles);
|
|
241
243
|
syncSpecSummaries();
|
|
@@ -243,7 +245,18 @@ if (syncGlobal) {
|
|
|
243
245
|
}
|
|
244
246
|
// 2. Sincronizar Projetos do Workspace
|
|
245
247
|
const projectsDir = getProjectsDir();
|
|
246
|
-
if (syncProjects &&
|
|
248
|
+
if (syncProjects && mode === 'embedded') {
|
|
249
|
+
const projectName = path.basename(operationRoot);
|
|
250
|
+
upsertProject.run(projectName, operationRoot, now);
|
|
251
|
+
const pid = getProjectId.get(projectName).id;
|
|
252
|
+
syncFiles([
|
|
253
|
+
...walk(path.join(operationRoot, 'memory')),
|
|
254
|
+
...walk(path.join(operationRoot, 'docs')),
|
|
255
|
+
...walk(path.join(operationRoot, 'specs')),
|
|
256
|
+
...walk(path.join(operationRoot, 'design-md')),
|
|
257
|
+
], pid);
|
|
258
|
+
}
|
|
259
|
+
else if (syncProjects && fs.existsSync(projectsDir)) {
|
|
247
260
|
const projects = fs.readdirSync(projectsDir, { withFileTypes: true })
|
|
248
261
|
.filter(e => e.isDirectory())
|
|
249
262
|
.filter(e => !onlyProject || e.name === onlyProject);
|
|
@@ -265,7 +278,7 @@ if (syncProjects && fs.existsSync(projectsDir)) {
|
|
|
265
278
|
}
|
|
266
279
|
// 3. Sincronizar fichas de projetos no workspace memory/30-projects
|
|
267
280
|
const workspaceProjectsMemoryDir = getWorkspaceProjectsMemoryDir();
|
|
268
|
-
if (fs.existsSync(workspaceProjectsMemoryDir)) {
|
|
281
|
+
if (mode === 'studio' && fs.existsSync(workspaceProjectsMemoryDir)) {
|
|
269
282
|
const fichaFiles = walk(workspaceProjectsMemoryDir);
|
|
270
283
|
syncFiles(fichaFiles);
|
|
271
284
|
}
|
|
@@ -0,0 +1,442 @@
|
|
|
1
|
+
# ForjaJS 3.0 — Engineering Intelligence / Engineering Twin — Architecture
|
|
2
|
+
|
|
3
|
+
- **Status**: draft — primeira entrega (auditoria + arquitetura proposta), sem implementação
|
|
4
|
+
- **Autor**: apk (com assistência do Forja Engineer via Claude)
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
- **ADR principal**: [ADR-0078](../../memory/90-decisions/0078-forjajs-3-engineering-control-plane.md)
|
|
7
|
+
- **Spec master**: [SPEC-031 — Engineering Intelligence](../../specs/engineering-intelligence/spec.md)
|
|
8
|
+
|
|
9
|
+
> Este documento é o produto da "primeira entrega" pedida antes de qualquer código: auditoria do
|
|
10
|
+
> estado atual, gap analysis, arquitetura proposta e plano de sprints. Nenhuma das 33 features
|
|
11
|
+
> listadas na visão original foi implementada a partir deste documento — ele existe para decidir
|
|
12
|
+
> **o que construir e em que ordem**, não para documentar o que já foi construído.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. Current State — o que a Forja já é
|
|
17
|
+
|
|
18
|
+
A Forja 2.0 já é, hoje, uma plataforma real (não um protótipo) com os seguintes componentes
|
|
19
|
+
verificados em código, não em documentação:
|
|
20
|
+
|
|
21
|
+
| Pacote | O que já faz | Linhas (aprox.) |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| `packages/contracts` | Contratos versionados (`CONTRACT_VERSION = '2.0'`), `KnowledgeStatus`, `PolicyEffect`, `ExecutionState`, `SandboxState`, `GraphNode`/`GraphEdge`/`Evidence`, `RuntimeRun`, `ApprovalRequest`, `Sprint`/`Task`/`Handoff`, `Observation`, `ControlPlaneMetrics`, `EvaluationReport`, e (desde a auditoria de 2026-08-31) `isPathWithinRoot` | ~145 |
|
|
24
|
+
| `packages/graph` | **GraphLoop**: nós/arestas com `status: verified\|inferred\|hypothesis\|contradicted\|unknown`, validade temporal (`validFrom`/`validTo`), evidência ligada a aresta, `path()`/`impact()`/`contradictions()`/`agenda()`/`contextRecords()`. `GraphIndexer.sync()` é idempotente por checksum de fonte. `extractDeterministicRelations()` extrai `DEPENDS_ON`/`CALLS`/`IMPLEMENTS`/`DERIVED_FROM` (ADR)/`CONTAINS` (task)/`ASSIGNED_TO` (agent)/`VALIDATES` (test) por regex determinístico — **sem LLM**. Desde a auditoria, `status: 'verified'` só é aceito de fontes de evidência confiáveis (allowlist configurável) | ~410 |
|
|
25
|
+
| `packages/policy` | `PolicyEngine`: regras com `scope` (agente/role/capability/projeto/ambiente/risco/categoria/`pathPrefixes`), efeitos `ALLOW\|ALLOW_WITH_LIMITS\|REQUIRE_APPROVAL\|DENY`, `limits` (`maxTokens`/`maxFiles`/`maxDurationMs`/`maxRetries`, agora **aplicados de verdade**, não só computados), `ApprovalLedger` com resolução por `correlationId` (aprovar uma vez resolve o retry, não fica pedindo pra sempre) | ~230 |
|
|
26
|
+
| `packages/core` | `CapabilityRegistry`: registro de capabilities com `definition` (risco, side effects, permissões, timeout, retry), `execute()` chama `policy.authorize()` antes do handler, aplica `decision.limits` | ~240 |
|
|
27
|
+
| `packages/runtime` | `RuntimeEngine`: máquina de estados (`created→planning→running→awaiting_approval→validating→completed\|blocked\|failed`), checkpoint/retomada via SQLite, limites globais (`maxSteps`/`maxTokens`/`maxFiles`/`maxDurationMs`/`maxRetries`) | ~345 |
|
|
28
|
+
| `packages/validator` | `DeterministicValidator`: agrega checks/critérios de aceite, computa `scope` automaticamente contra `allowedFiles` do plano, **exige evidência para qualquer "passed"** (desde a auditoria) | ~95 |
|
|
29
|
+
| `packages/orchestration` | `SprintEngine`/`TaskEngine`/`HandoffEngine`: sprint→task→handoff com 7 campos obrigatórios (ADR-0005), guarda de concorrência otimista, teto de handoffs por `correlationId` | ~265 |
|
|
30
|
+
| `packages/sandbox` | `SandboxEngine`: máquina de estados `created→prepared→executing→validating→ready_to_promote→promoted\|rejected\|rolled_back→destroyed`. Desde hoje, `runSandboxedCapability()` empacota o ciclo completo em uma chamada reutilizável | ~220 |
|
|
31
|
+
| `packages/adapter-git` | `GitWorktreeBackend` (isolamento real via `git worktree`), `GitPatchApplier`, `SpawnCommandRunner` sem herdar env por padrão | ~150 |
|
|
32
|
+
| `packages/adapter-sqlite` | Stores SQLite para cada engine acima — memória, aprovações, sandbox, runtime, orquestração, auditoria, observações, grafo | ~300 |
|
|
33
|
+
| `packages/adapter-nest` | Adapter HTTP local (`ForjaNestAdapter`), autenticação **fail-closed a loopback** quando sem token (desde a auditoria) | ~130 |
|
|
34
|
+
| `packages/context` | `ContextEngine`: seleciona candidatos por relevância, deduplica por checksum, respeita orçamento de tokens, cacheia | ~175 |
|
|
35
|
+
| `packages/mcp` | Servidor MCP com ferramentas `forja_capability_execute`, `forja_handoff_create`, `forja_context_build`, `forja_memory_query`, `forja_graph_query`, `forja_code_impact`, `forja_task_next`, `forja_spec_check`, `forja_test_run`, `forja_execution_validate` — todas passam por `authorize()` desde a auditoria | ~260 |
|
|
36
|
+
| `packages/plugin-sdk` | `PluginRegistry`, manifesto com `permissions` explícitas, `PluginContext` que aplica `requirePermission()` antes de qualquer chamada ao host | ~90 |
|
|
37
|
+
| `packages/observability` | `ObservabilityRecorder`, `ControlPlane` (métricas agregadas: runs, sucesso, tokens, custo, evidência) | ~155 |
|
|
38
|
+
| `packages/events` | `EventBus` com idempotência, dead-letter, offsets — já é o barramento de eventos do sistema | ~150 |
|
|
39
|
+
| `packages/evals` | `EvaluationEngine`: agrega `Observation[]` em `EvaluationReport` por escopo (`run\|agent\|task\|sprint\|capability\|model\|strategy\|workspace`) | ~75 |
|
|
40
|
+
| `packages/planner` | `DeterministicPlanner`: decompõe objetivo em plano com dependências, risco, orçamento — **sem LLM** | ~90 |
|
|
41
|
+
| `apps/cli` | CLI real (`bin/forja.ts`) roteando ~50 comandos; nenhuma capability registrada aqui escreve em arquivos de projeto (todas são leitura, `context_run_record`, `handoff_record` ou `graph_write` — bookkeeping do framework, não edição de código) | — |
|
|
42
|
+
| `apps/server` | NestJS + REST/SSE, controle de acesso, fecha SQLite no shutdown | — |
|
|
43
|
+
| `apps/dashboard` | Next.js, proxy autenticado para o server, sem lógica de autorização própria | — |
|
|
44
|
+
| `apps/worker` | Processo separado para jobs longos | — |
|
|
45
|
+
| `scripts/demo-autonomy.ts` | **Prova end-to-end real** do ciclo completo: contexto → plano → política → aprovação humana → sandbox real (git worktree) → validação → promoção → grafo → sprint/task/handoff → evento — hoje o único lugar que fecha o círculo inteiro | — |
|
|
46
|
+
|
|
47
|
+
**O que isso significa**: a Forja já tem — implementados e testados, não apenas desenhados — quatro
|
|
48
|
+
das cinco peças que a visão de "Engineering Control Plane" precisa: um motor de política com
|
|
49
|
+
aprovação, um runtime supervisionado com checkpoint, um grafo de conhecimento com evidência e
|
|
50
|
+
validade temporal, e um sandbox real. **O que falta não é reinventar essas peças — é estender o
|
|
51
|
+
grafo para cobrir engenharia (não só código) e construir três motores novos por cima delas**
|
|
52
|
+
(Constitution, Risk, Provenance) mais um pouco de identidade/reputação de agente.
|
|
53
|
+
|
|
54
|
+
## 2. Target State — o que a visão pede
|
|
55
|
+
|
|
56
|
+
Resumo dos 33 blocos da visão, agrupados pelas 5 perguntas que a Forja deveria conseguir responder
|
|
57
|
+
de forma estruturada e auditável ao final da evolução (ver §12 do documento original):
|
|
58
|
+
|
|
59
|
+
1. **Por que o código existe** → Engineering Graph liga código a SPEC/ADR/Requirement.
|
|
60
|
+
2. **A mudança viola a arquitetura** → Architecture Constitution + `architecture:check`.
|
|
61
|
+
3. **Qual o risco** → Change Risk Engine + Risk-Based Autonomy (integrado ao Policy Engine já
|
|
62
|
+
existente, não um sistema paralelo).
|
|
63
|
+
4. **Quem/o quê mudou isso** → AI Code Provenance (`forja blame`) + Agent Identity.
|
|
64
|
+
5. **A Forja aprende com o passado** → Learning Loop + Incident Graph + Agent Reputation.
|
|
65
|
+
|
|
66
|
+
## 3. Gap Analysis
|
|
67
|
+
|
|
68
|
+
| Capacidade pedida | Situação real | Classificação |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| Engineering Graph (nós Code/ADR/Spec/Agent/Run/Test/Incident/PR) | `GraphLoop` já é um grafo genérico com evidência e validade temporal; só faltam os **tipos de nó/aresta** de engenharia (ADR, SPEC, Agent, Run, Incident, PR) e os extratores que os populam | **Estender**, não recriar |
|
|
71
|
+
| Architecture Constitution | Não existe. `extractDeterministicRelations` já prova que extração determinística de ADR funciona (regex por `ADR-\d{4}`) — é a base para extrair `## Constraints` de forma determinística | **Construir**, reaproveitando o extrator |
|
|
72
|
+
| Architecture Drift Detection (`architecture:check`) | `specs/drift-sentinel` (em implementação nesta mesma sessão) já resolve a versão genérica ("uma relação verificada parou de ser reproduzida") — Architecture Drift é esse mesmo motor aplicado especificamente a regras da Constitution | **Compor** drift-sentinel + Constitution, não duplicar |
|
|
73
|
+
| Change Risk Engine | Não existe motor de score. Mas todos os insumos já existem: `GraphLoop.impact()` (blast radius), `EvaluationReport`/`Observation` (taxa histórica de falha), `PolicyEngine` (categoria/risco por regra) | **Construir**, compondo dados existentes |
|
|
74
|
+
| Risk-Based Autonomy | `PolicyEngine` já tem `ALLOW\|ALLOW_WITH_LIMITS\|REQUIRE_APPROVAL\|DENY` e `approvalRequiredRisks` configurável por `RiskLevel` | **Estender** `RiskLevel`/regras, não criar motor de decisão paralelo |
|
|
75
|
+
| Predictive Change Simulation (`forja simulate`) | `SandboxEngine` + `GitWorktreeBackend` + `runSandboxedCapability` (hoje) já são exatamente "aplicar em worktree isolado, testar, decidir promover ou descartar" | **Compor** sandbox + risk engine + architecture:check |
|
|
76
|
+
| ADR Graph / Decision Impact | `extractDeterministicRelations` já cria nós `ADR` e aresta `DERIVED_FROM` a partir de `ADR-\d{4}` no texto | **Estender** com status (`accepted/proposed/deprecated/superseded`) e `adr:impact` usando `GraphLoop.impact()` que já existe |
|
|
77
|
+
| `forja engineer` (façade) | Nada equivalente hoje — mas é literalmente uma composição de `ContextEngine` + `DeterministicPlanner` + `GraphLoop` + Risk Engine (novo) + `PolicyEngine`, todos já existentes | **Construir só a façade**, proibido reimplementar qualquer peça |
|
|
78
|
+
| Agent Identity | `AgentIdentity` já existe como tipo (`id`, `role`, `autonomy`) mas é efêmero — não é uma entidade persistida com histórico | **Estender** o contrato + persistência, não trocar o conceito |
|
|
79
|
+
| Agent Reputation / Project Evals | `EvaluationEngine`/`EvaluationReport` já agregam `Observation[]` por `scope: 'agent' \| 'model' \| ...` — a agregação existe, falta só o *report* voltado a reputação e o comando `agent:score` | **Estender**, não recriar |
|
|
80
|
+
| Smart Agent Routing | `scripts/llm-fit.ts`/`llm:recommend`/`llm:profiles` já fazem roteamento determinístico por papel/tarefa sem custo de rede ("LLM Fit Loop", ADR-0074) — é precisamente o esqueleto de Smart Routing | **Estender** com dados de reputação, não substituir |
|
|
81
|
+
| AI Code Provenance (`forja blame`) | `Observation` já tem `model`, `agentId`, `runId`, `inputHash`, `contextRefs` — falta ligar linha de código a `Observation`, o que exige um novo tipo de aresta no grafo (`GENERATED_BY`) | **Construir**, dado que os campos-fonte já existem |
|
|
82
|
+
| AI-SBOM | Não existe, mas é um relatório derivado do grafo de provenance — nenhuma nova fonte de dado, só agregação | **Construir** por cima do grafo |
|
|
83
|
+
| Agent Runtime Monitoring / Anomaly Engine | Não existe. `PolicyEngine` já é o lugar certo para acoplar (política decide, não o LLM) | **Construir**, mas *dentro* de Policy, não paralelo |
|
|
84
|
+
| Learning Loop / Incident → Knowledge | Não existe. `GraphLoop` + evidência já dão a base; falta o tipo de nó `Incident` e o fluxo de sugestão (nunca aplicação automática) | **Construir**, reaproveitando grafo + approvals |
|
|
85
|
+
| Autonomous Maintenance | Não existe nada além da base (`RuntimeEngine` + `PolicyEngine` + `SandboxEngine` já provam o ciclo supervisionado de ponta a ponta via `demo-autonomy.ts`) | **Fase 7** — arquitetar o caminho, não habilitar agora |
|
|
86
|
+
| Engineering API (`packages/engineering`, etc.) | Não existe como pacote — mas o padrão "domain core sem framework" já é a convenção de todo `packages/*` hoje | **Construir seguindo o padrão existente** |
|
|
87
|
+
| Provider-agnostic model layer | Já existe: `packages/llm` roteia por CLI adapter, sem acoplamento a um provider | **Nada a fazer** — só não violar |
|
|
88
|
+
|
|
89
|
+
**Conclusão do gap analysis**: nenhuma das 33 features exige reescrever nada que já existe. Todas
|
|
90
|
+
se apoiam em três extensões de contrato (tipos de nó/aresta no grafo, campos em `AgentIdentity`,
|
|
91
|
+
campos em `PolicyRule`) e quatro motores novos (Constitution, Risk, Provenance, Identity/Reputation)
|
|
92
|
+
que **compõem** engines existentes em vez de duplicá-las.
|
|
93
|
+
|
|
94
|
+
## 4. Bounded Contexts propostos
|
|
95
|
+
|
|
96
|
+
Novo pacote: **`packages/engineering`** — não um pacote monolítico, mas um diretório com
|
|
97
|
+
sub-bounded-contexts próprios, cada um seguindo a mesma regra que já rege `packages/core`,
|
|
98
|
+
`packages/policy` etc.: **framework-independent, importa só `packages/contracts` e (quando preciso)
|
|
99
|
+
`packages/graph`**.
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
packages/engineering/
|
|
103
|
+
architecture/ ArchitectureEngine — compila Constitution, roda architecture:check
|
|
104
|
+
risk/ RiskEngine — score de mudança, fórmula configurável
|
|
105
|
+
provenance/ ProvenanceEngine — liga código a Observation/Run/Agent
|
|
106
|
+
identity/ AgentIdentityService, AgentReputationService
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Por que um pacote com sub-diretórios e não quatro pacotes `@forja/architecture`,
|
|
110
|
+
`@forja/risk`, etc.? Porque os quatro comportam contratos e regras de negócio da MESMA camada
|
|
111
|
+
(bounded contexts irmãos, não em cadeia de dependência um do outro) e crescem juntos nas mesmas
|
|
112
|
+
sprints (Fase 1). Divergir em pacotes separados antes de qualquer um deles estabilizar é
|
|
113
|
+
over-engineering — `packages/policy`/`packages/core`/`packages/runtime` só viraram pacotes
|
|
114
|
+
separados depois que a fronteira entre eles já estava provada em uso real (ADR-0020). Fica como
|
|
115
|
+
critério explícito de follow-up: se `engineering/risk` crescer a ponto de precisar de sua própria
|
|
116
|
+
release/versão independente de `engineering/architecture`, aí sim vira `packages/risk` — decisão
|
|
117
|
+
adiada de propósito, não ignorada.
|
|
118
|
+
|
|
119
|
+
`packages/engineering` depende de `packages/contracts` e `packages/graph` (para ler/escrever nós de
|
|
120
|
+
engenharia). **Não depende de `packages/policy`** — é o inverso: `PolicyEngine` opcionalmente
|
|
121
|
+
consulta um `RiskEngine` via uma interface pequena (`RiskAssessor`), não o contrário, preservando a
|
|
122
|
+
direção de dependência do ADR-0020 (`policy` não sabe de `engineering`; `engineering` não sabe de
|
|
123
|
+
`policy` — quem os compõe é a camada de aplicação, ex.: `forja engineer`).
|
|
124
|
+
|
|
125
|
+
## 5. Arquitetura proposta
|
|
126
|
+
|
|
127
|
+
```text
|
|
128
|
+
packages/contracts
|
|
129
|
+
│
|
|
130
|
+
packages/graph ◄──────────────┐
|
|
131
|
+
│ │
|
|
132
|
+
packages/engineering │
|
|
133
|
+
(architecture, risk, │
|
|
134
|
+
provenance, identity) │
|
|
135
|
+
│ │
|
|
136
|
+
┌────────────┼────────────┐ │
|
|
137
|
+
│ │ │ │
|
|
138
|
+
packages/policy packages/planner │ │
|
|
139
|
+
│ │ │ │
|
|
140
|
+
└────────────┼────────────┘ │
|
|
141
|
+
│ │
|
|
142
|
+
packages/orchestration │
|
|
143
|
+
│ │
|
|
144
|
+
packages/runtime │
|
|
145
|
+
│ │
|
|
146
|
+
apps/cli · apps/server · packages/mcp ──────┘
|
|
147
|
+
(adapters — cada um compõe os engines,
|
|
148
|
+
nenhum reimplementa lógica)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`packages/engineering` senta **entre** `graph` e `policy`/`planner`, na mesma posição de domínio
|
|
152
|
+
independente de framework descrita em `docs/architecture/FORJA-2.0-ARCHITECTURE.md` — mesma direção
|
|
153
|
+
de dependência (interfaces externas → adapters → application → domain core), estendida com uma
|
|
154
|
+
camada de domínio a mais.
|
|
155
|
+
|
|
156
|
+
## 6. Data Model — extensões de contrato
|
|
157
|
+
|
|
158
|
+
Em `packages/contracts/src/index.ts`, aditivo (nunca remove campo existente — SPEC-012/`noImplicitAny`
|
|
159
|
+
já provou que este repo trata mudança de contrato como ratchet, não como reescrita):
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
// Novos tipos de nó de engenharia — reaproveitam GraphNode.type (string livre) e
|
|
163
|
+
// GraphNode.status (KnowledgeStatus) já existentes. Não é um novo contrato de nó,
|
|
164
|
+
// é um VOCABULÁRIO de `type` documentado — igual o extractDeterministicRelations
|
|
165
|
+
// já faz hoje com 'Project'|'Document'|'File'|'Symbol'|'ADR'|'Task'|'Agent'|'Test'.
|
|
166
|
+
export const ENGINEERING_NODE_TYPES = [
|
|
167
|
+
'ADR', 'SPEC', 'Requirement', 'BusinessRule', // já parcial (ADR)
|
|
168
|
+
'Module', 'Class', 'Function', 'API', 'Worker', 'Table', // já parcial (File/Symbol)
|
|
169
|
+
'Agent', 'Model', 'Run', 'Context', 'Tool', 'Capability', // Agent já existe
|
|
170
|
+
'Test', 'Evaluation', 'Failure', 'Incident', // Test já existe
|
|
171
|
+
'Commit', 'Branch', 'PullRequest', 'Release',
|
|
172
|
+
'Approval', 'Policy', 'Risk', 'Evidence',
|
|
173
|
+
] as const;
|
|
174
|
+
|
|
175
|
+
export const ENGINEERING_EDGE_TYPES = [
|
|
176
|
+
'implements', 'depends_on', 'calls', 'imports', 'reads', 'writes', // parcial (DEPENDS_ON/CALLS)
|
|
177
|
+
'defined_by', 'governed_by', 'violates', 'supersedes',
|
|
178
|
+
'generated_by', 'reviewed_by', 'approved_by',
|
|
179
|
+
'tested_by', 'failed_by',
|
|
180
|
+
'changed_by', 'introduced_by', 'fixed_by',
|
|
181
|
+
'affects', 'impacts', 'observed_in', 'deployed_in',
|
|
182
|
+
] as const;
|
|
183
|
+
|
|
184
|
+
// Identidade de agente persistente — hoje AgentIdentity é efêmero (só id/role/autonomy).
|
|
185
|
+
export interface AgentProfile2 extends AuditFields {
|
|
186
|
+
readonly id: EntityId; // forja://agents/<slug>
|
|
187
|
+
readonly role: string;
|
|
188
|
+
readonly provider?: string;
|
|
189
|
+
readonly model?: string;
|
|
190
|
+
readonly capabilities: readonly string[];
|
|
191
|
+
readonly trustLevel: number; // 0-5, derivado por AgentReputationService — nunca setado à mão
|
|
192
|
+
readonly autonomyLevel: 'autonomous' | 'autonomous_with_review' | 'supervised' | 'human_in_the_loop';
|
|
193
|
+
readonly architectureDomains: readonly string[];
|
|
194
|
+
readonly limits?: { readonly maxFiles?: number; readonly maxCostUsd?: number; readonly maxDurationMs?: number };
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// Regra de Architecture Constitution
|
|
198
|
+
export interface ArchitectureRule {
|
|
199
|
+
readonly id: string;
|
|
200
|
+
readonly source: string; // ex.: 'memory/90-decisions/0042-....md'
|
|
201
|
+
readonly sourceType: 'adr' | 'spec' | 'manual';
|
|
202
|
+
readonly status: 'active' | 'superseded' | 'proposed';
|
|
203
|
+
readonly scope: { readonly paths: readonly string[] };
|
|
204
|
+
readonly constraint: ArchitectureConstraint;
|
|
205
|
+
readonly severity: 'info' | 'low' | 'medium' | 'high' | 'critical';
|
|
206
|
+
readonly rationale: string;
|
|
207
|
+
readonly confidence: number; // 1.0 para regra explícita; < 1.0 só quando sourceType sugere via LLM e AINDA não foi aprovada por humano
|
|
208
|
+
}
|
|
209
|
+
export type ArchitectureConstraint =
|
|
210
|
+
| { readonly kind: 'forbid_import'; readonly patterns: readonly string[] }
|
|
211
|
+
| { readonly kind: 'require_dependency'; readonly symbols: readonly string[] }
|
|
212
|
+
| { readonly kind: 'forbid_dependency'; readonly symbols: readonly string[] };
|
|
213
|
+
|
|
214
|
+
// Risk score — nunca mágico, sempre com fatores nomeados (ver SPEC-035)
|
|
215
|
+
export interface ChangeRiskAssessment {
|
|
216
|
+
readonly score: number; // 0-100
|
|
217
|
+
readonly confidence: number; // 0-1
|
|
218
|
+
readonly factors: readonly { readonly name: string; readonly weight: number; readonly value: number; readonly evidenceIds: readonly EntityId[] }[];
|
|
219
|
+
readonly recommendedControls: readonly string[];
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Nenhum desses tipos precisa de tabela SQLite nova além do que `adapter-sqlite` já tem para
|
|
224
|
+
`GraphNode`/`GraphEdge`/`Evidence` — `ArchitectureRule` e `ChangeRiskAssessment` são **derivados em
|
|
225
|
+
tempo de leitura** (compilados/computados), não persistidos como fonte de verdade primária; o que
|
|
226
|
+
é persistido é o artefato compilado (`.context/architecture/constitution.json`, versionado em git,
|
|
227
|
+
não em SQLite — decisão explícita, ver §9).
|
|
228
|
+
|
|
229
|
+
## 7. Engineering Graph Model — nós e arestas novos, concretamente
|
|
230
|
+
|
|
231
|
+
Extração determinística (sem LLM) a partir de fontes já lidas hoje pelo `GraphIndexer`:
|
|
232
|
+
|
|
233
|
+
| Documento fonte | Extrator | Nó(s) produzido(s) | Aresta(s) |
|
|
234
|
+
|---|---|---|---|
|
|
235
|
+
| `memory/90-decisions/NNNN-*.md` | já existe (`ADR-\d{4}` regex) — **estender** para ler `## Constraints` como lista determinística | `ADR` (com `status` do frontmatter, hoje ignorado — precisa passar a ler) | `governed_by` do módulo em `scope.paths` para o ADR |
|
|
236
|
+
| `specs/*/spec.md` | novo, mesmo padrão regex (`SPEC-\d{3}`, `## Escopo`) | `SPEC` | `implements` do módulo pra SPEC; `derived_from` da SPEC pro ADR referenciado |
|
|
237
|
+
| `.context/forja-runs.jsonl` / SQLite `runtime_*` | novo — já é dado estruturado, não precisa regex | `Run`, `Agent` (já existe), `Capability` (já existe via `GraphExecutionMemory`) | `generated_by` |
|
|
238
|
+
| `git log` (via `adapter-git`, já usado por `code:sync`) | novo, reaproveita `SpawnCommandRunner` já existente | `Commit` | `changed_by`, `introduced_by` |
|
|
239
|
+
| `test/*.test.js` | já parcial (`describe`/`it`/`test` regex existe) | `Test` (já existe) | `tested_by` |
|
|
240
|
+
|
|
241
|
+
**Importante — nada disso precisa de LLM.** O padrão do `extractDeterministicRelations` já provou
|
|
242
|
+
(código em produção, testado) que regex + parsing estruturado cobre ADR/SPEC/Task/Test/Agent/ADR.
|
|
243
|
+
LLM entra só como **sugestão opcional** de regra ambígua (§8), nunca como fonte de verdade do grafo.
|
|
244
|
+
|
|
245
|
+
## 8. Architecture Constitution — design
|
|
246
|
+
|
|
247
|
+
Pipeline: `memory/90-decisions/*.md` (fonte legível por humano) → parser determinístico de
|
|
248
|
+
`## Constraints` (mesma técnica regex do extrator de grafo) → `ArchitectureRule[]` → compilado em
|
|
249
|
+
`.context/architecture/constitution.json` (versionado em git, revisável em PR como qualquer outro
|
|
250
|
+
artefato gerado — mesmo padrão de `.context/forja-runs.jsonl`).
|
|
251
|
+
|
|
252
|
+
Comandos propostos (nenhum existe ainda — nomenclatura sem prefixo `forja`, ver §12):
|
|
253
|
+
|
|
254
|
+
- `architecture:compile` — ADRs → `constitution.json` (determinístico)
|
|
255
|
+
- `architecture:check` — `constitution.json` vs. CodeGraph vs. código atual
|
|
256
|
+
- `architecture:status` — resumo: N regras ativas, última compilação
|
|
257
|
+
- `architecture:explain <rule-id>` — por que essa regra existe, qual ADR, qual severidade
|
|
258
|
+
|
|
259
|
+
`architecture:compile` **nunca** usa LLM para gerar uma regra `active` diretamente. Fluxo com LLM
|
|
260
|
+
(opcional, Fase 6+): quando um ADR tem `## Constraints` mal-formado ou ambíguo, o parser
|
|
261
|
+
determinístico produz uma regra com `confidence < 1.0` e `status: 'proposed'`; só passa a `active`
|
|
262
|
+
depois de `architecture:approve <rule-id>` (comando proposto, ver §12; reaproveita `ApprovalLedger` — **não** um sistema
|
|
263
|
+
de aprovação paralelo).
|
|
264
|
+
|
|
265
|
+
`architecture:check` reaproveita o mesmo motor de "isso que era verdade parou de ser" que o
|
|
266
|
+
`drift:check` (SPEC-030, em implementação nesta sessão) já constrói — arquitetura é um caso
|
|
267
|
+
particular de drift: a fonte é `constitution.json` em vez de um documento livre, e a comparação é
|
|
268
|
+
contra imports/dependências reais (via `CodeGraph`/`extractDeterministicRelations`, que já produz
|
|
269
|
+
arestas `DEPENDS_ON`) em vez de contra uma relação semântica textual qualquer.
|
|
270
|
+
|
|
271
|
+
## 9. Change Risk Engine — design
|
|
272
|
+
|
|
273
|
+
Fórmula inicial, documentada e com pesos configuráveis (nunca hardcoded sem explicação — pedido
|
|
274
|
+
explícito da visão):
|
|
275
|
+
|
|
276
|
+
```ts
|
|
277
|
+
interface RiskFactor { readonly name: string; readonly weight: number; readonly compute: (input: RiskInput) => number /* 0-1 */; }
|
|
278
|
+
|
|
279
|
+
const DEFAULT_RISK_FACTORS: readonly RiskFactor[] = [
|
|
280
|
+
{ name: 'blast_radius', weight: 0.20, compute: /* GraphLoop.impact(origin).nodes.length, normalizado */ },
|
|
281
|
+
{ name: 'architecture_violations', weight: 0.20, compute: /* count de architecture:check reprovado no diff */ },
|
|
282
|
+
{ name: 'security_sensitivity',weight: 0.15, compute: /* categorias 'secrets'|'database'|'deployment' tocadas, já vocabulário de PolicyCategory */ },
|
|
283
|
+
{ name: 'historical_failure_rate', weight: 0.15, compute: /* EvaluationReport do domínio/capability afetado */ },
|
|
284
|
+
{ name: 'test_confidence', weight: 0.10, compute: /* cobertura de teste dos arquivos afetados, inverso */ },
|
|
285
|
+
{ name: 'reversibility', weight: 0.10, compute: /* migration/schema change = baixa reversibilidade */ },
|
|
286
|
+
{ name: 'deployment_complexity', weight: 0.10, compute: /* número de serviços/apps afetados */ },
|
|
287
|
+
];
|
|
288
|
+
|
|
289
|
+
score = round(100 * Σ(factor.weight * factor.compute(input)))
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Todo fator carrega `evidenceIds` (nós/arestas do grafo, `Observation`s) — nunca um número solto.
|
|
293
|
+
`confidence` do assessment é a fração de fatores que tiveram dado real disponível (ex.: sem
|
|
294
|
+
histórico de falha nesse domínio ainda → esse fator entra com peso mas confiança reduzida,
|
|
295
|
+
declarado, não escondido).
|
|
296
|
+
|
|
297
|
+
Integração com `PolicyEngine` (§ visão original, Feature 4): **sem** motor de decisão paralelo.
|
|
298
|
+
`RiskLevel` (`'low'|'medium'|'high'|'critical'`) já é o vocabulário do `PolicyRule.scope.risks` e
|
|
299
|
+
de `approvalRequiredRisks` — a mudança é permitir que `PolicyRequest` opcionalmente carregue um
|
|
300
|
+
`riskScore: ChangeRiskAssessment` calculado por `RiskEngine` (interface pequena, injetada, igual
|
|
301
|
+
`request.policy` já é injetado hoje), e que uma regra de política possa referenciar faixas de score
|
|
302
|
+
(`scope.riskScoreRange?: [number, number]`) além de `risks: RiskLevel[]`. As faixas 0-25/26-50/51-
|
|
303
|
+
75/76-100 sugeridas na visão viram os **valores default** de configuração, nunca constantes fixas
|
|
304
|
+
no código — mesmo princípio já usado em `RuntimeLimits`/`PolicyLimits` (default object, sempre
|
|
305
|
+
sobrescrevível).
|
|
306
|
+
|
|
307
|
+
## 10. Engineering Evidence Ledger
|
|
308
|
+
|
|
309
|
+
Não é um sistema novo — é `Evidence`/`AuditRecord` (já existem em `packages/contracts`) mais
|
|
310
|
+
`SqliteAuditStore`/`SqliteObservationStore` (já existem em `packages/adapter-sqlite`), com um
|
|
311
|
+
formato de **exportação** append-only por run (o JSON de exemplo na visão — `run/intent/agent/risk/
|
|
312
|
+
architectureCheck/tests/approvals/commit`) construído a partir de dados que já são gravados hoje em
|
|
313
|
+
tabelas separadas. O trabalho real aqui é uma **view agregada**, não uma nova fonte de dado.
|
|
314
|
+
|
|
315
|
+
## 11. API Contracts (packages/engineering)
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
// packages/engineering/architecture/src/index.ts
|
|
319
|
+
export interface ArchitectureEngine {
|
|
320
|
+
compile(sources: { adrs: readonly string[]; specs: readonly string[] }): readonly ArchitectureRule[];
|
|
321
|
+
check(rules: readonly ArchitectureRule[], graph: GraphLoop): ArchitectureCheckReport;
|
|
322
|
+
explain(ruleId: string, rules: readonly ArchitectureRule[]): ArchitectureRuleExplanation;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
// packages/engineering/risk/src/index.ts
|
|
326
|
+
export interface RiskEngine {
|
|
327
|
+
assess(input: RiskInput): ChangeRiskAssessment;
|
|
328
|
+
}
|
|
329
|
+
// Consumido opcionalmente por PolicyEngine via uma interface local pequena — PolicyEngine não
|
|
330
|
+
// importa @forja/engineering-risk, só uma interface estrutural (mesmo padrão de CapabilityPolicy
|
|
331
|
+
// hoje: PolicyEngine satisfaz a interface por forma, não por import direto).
|
|
332
|
+
|
|
333
|
+
// packages/engineering/provenance/src/index.ts
|
|
334
|
+
export interface ProvenanceEngine {
|
|
335
|
+
recordGeneration(input: { readonly files: readonly string[]; readonly lines?: readonly [number, number][]; readonly runId: RunId; readonly agentId: EntityId }): void;
|
|
336
|
+
blame(file: string, lineRange?: readonly [number, number]): readonly ProvenanceRecord[];
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
// packages/engineering/identity/src/index.ts
|
|
340
|
+
export interface AgentIdentityService { register(profile: AgentProfileInput): AgentProfile2; get(id: EntityId): AgentProfile2 | undefined; }
|
|
341
|
+
export interface AgentReputationService { score(agentId: EntityId, domain?: string): AgentReputationScore; }
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Cada um é **puro domínio** (sem `fs`/`spawnSync`/rede) — os adapters (`apps/cli`, `packages/mcp`,
|
|
345
|
+
`apps/server`) é que ligam a fontes reais (arquivos ADR, git log, SQLite).
|
|
346
|
+
|
|
347
|
+
## 12. CLI Plan
|
|
348
|
+
|
|
349
|
+
Sem explosão de comandos — agrupado por domínio, uma façade principal (`engineer`) por cima do
|
|
350
|
+
resto. **Nenhum comando abaixo existe ainda** — esta é a superfície proposta para os Sprints 1-3;
|
|
351
|
+
por isso a tabela usa nome do comando sem o prefixo `forja`/`npm run` (convenção deste repositório
|
|
352
|
+
para citação de comando *proposto*, não real — ver `lib/core/doc-graph.ts`, `DOC_SURFACES`: `docs/`
|
|
353
|
+
é superfície que orienta o agente *agora*, então só cita comando que já existe no registry;
|
|
354
|
+
comando proposto pertence à spec que o define, referenciada na coluna "Spec").
|
|
355
|
+
|
|
356
|
+
| Domínio | Comando proposto | Spec |
|
|
357
|
+
|---|---|---|
|
|
358
|
+
| Façade | `engineer "<objetivo>"` — compõe tudo abaixo | SPEC-035 |
|
|
359
|
+
| Arquitetura | `architecture:compile` / `:check` / `:status` / `:explain <rule-id>` / `:approve <rule-id>` | SPEC-033 |
|
|
360
|
+
| Risco | `risk:assess "<mudança>"` / `:explain <assessment-id>` | SPEC-034 |
|
|
361
|
+
| ADR | `adr:list` / `:show <id>` / `:impact <id>` / `:graph` | SPEC-032 |
|
|
362
|
+
| Agente | `agent:list` / `:show` / `:score` / `:history` | Fase 3 (fora desta spec master) |
|
|
363
|
+
| Proveniência | `provenance:blame <arquivo>` / `:generate` (AI-SBOM) | Fase 5 (fora desta spec master) |
|
|
364
|
+
| Outros | `simulate "<mudança>"`, `explain <alvo>`, `timeline` | Fases 4/2 (fora desta spec master) |
|
|
365
|
+
|
|
366
|
+
`eval:*`, `route`, `learn:*`, `watch` ficam para Fases 3/6/7 — não fazem parte da primeira entrega
|
|
367
|
+
de comandos (P0).
|
|
368
|
+
|
|
369
|
+
## 13. Events
|
|
370
|
+
|
|
371
|
+
Novos eventos no `EventBus` já existente (`packages/events`), sem barramento paralelo:
|
|
372
|
+
|
|
373
|
+
```text
|
|
374
|
+
architecture.compiled architecture.violation_detected
|
|
375
|
+
change.risk_assessed
|
|
376
|
+
agent.identity_registered agent.reputation_updated
|
|
377
|
+
provenance.recorded
|
|
378
|
+
simulation.completed
|
|
379
|
+
incident.detected learning.proposed
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
## 14. Persistence
|
|
383
|
+
|
|
384
|
+
SQLite local-first, como todo o resto do framework. `constitution.json` é a única exceção
|
|
385
|
+
deliberada (artefato versionado em git, não em SQLite) — mesma categoria de `.context/forja-runs.jsonl`:
|
|
386
|
+
precisa ser revisável em PR por humano, não só consultável por comando.
|
|
387
|
+
|
|
388
|
+
## 15. Security
|
|
389
|
+
|
|
390
|
+
Segue os princípios já estabelecidos e reforçados pela auditoria de 2026-08-31: local-first,
|
|
391
|
+
fail-closed em ambiguidade, LLM nunca é fonte de verdade para segurança crítica (Constitution:
|
|
392
|
+
regra `active` só de parser determinístico ou aprovação humana explícita — nunca de sugestão de
|
|
393
|
+
LLM direto).
|
|
394
|
+
|
|
395
|
+
## 16. Policy Integration
|
|
396
|
+
|
|
397
|
+
Detalhado em §9. Resumo: `RiskEngine` é consumido por `PolicyEngine`, nunca o substitui.
|
|
398
|
+
|
|
399
|
+
## 17. Migration Strategy / Compatibility
|
|
400
|
+
|
|
401
|
+
Toda extensão de contrato é aditiva (campos opcionais). Nenhum comando existente muda de
|
|
402
|
+
comportamento. `ENGINEERING_NODE_TYPES`/`ENGINEERING_EDGE_TYPES` são vocabulário adicional sobre o
|
|
403
|
+
`type: string` já livre de `GraphNode`/`GraphEdge` — zero migração de dado existente necessária.
|
|
404
|
+
|
|
405
|
+
## 18. Test Strategy
|
|
406
|
+
|
|
407
|
+
Mesmo padrão do resto do repo: `node --test`, sem mocking framework, fixtures de fake
|
|
408
|
+
store/backend (ver `test/sandbox.test.js` para o padrão de referência). `ArchitectureEngine`/
|
|
409
|
+
`RiskEngine` são puros — testáveis sem I/O. Testes negativos obrigatórios para: regra de
|
|
410
|
+
Constitution mal-formada, risco com fator sem dado (confidence reduzida, não erro), Constitution
|
|
411
|
+
compilada de ADR sem `## Constraints` (vazio, não crash).
|
|
412
|
+
|
|
413
|
+
## 19. Release Plan
|
|
414
|
+
|
|
415
|
+
Ver `specs/engineering-intelligence/plan.md` para o detalhamento em sprints — resumo:
|
|
416
|
+
|
|
417
|
+
- **Sprint 1**: `packages/engineering/architecture` (Constitution compile/check/explain) +
|
|
418
|
+
extração de `ADR`/`SPEC` no grafo.
|
|
419
|
+
- **Sprint 2**: `packages/engineering/risk` (RiskEngine) + integração `PolicyEngine`.
|
|
420
|
+
- **Sprint 3**: Evidence Ledger (view agregada) + `forja engineer` (façade mínima, sem routing/
|
|
421
|
+
identity ainda).
|
|
422
|
+
- Fases 2-7 da visão original ficam para specs subsequentes, quebradas quando Sprint 1-3 estiver
|
|
423
|
+
em produção e puder informar as decisões de design das fases seguintes (Agent Identity, em
|
|
424
|
+
particular, se beneficia de já ter dados reais de `RiskEngine`/`ArchitectureEngine` rodando).
|
|
425
|
+
|
|
426
|
+
## 20. Riscos
|
|
427
|
+
|
|
428
|
+
| Risco | Mitigação |
|
|
429
|
+
|---|---|
|
|
430
|
+
| `packages/engineering` virar um monólito acoplado | Sub-diretórios com fronteira de interface clara desde o dia 1 (§4); nenhum dos quatro importa os outros três diretamente |
|
|
431
|
+
| Risk score "mágico" sem explicação | Fórmula documentada em código E neste doc (§9); todo `ChangeRiskAssessment` carrega `factors[]` com `evidenceIds` |
|
|
432
|
+
| Architecture Constitution virar fonte de falso-positivo (ruído) | Reaproveita a mesma mitigação já desenhada para drift-sentinel: comparação por relação semântica (import/depend), não por hash de texto |
|
|
433
|
+
| Confundir sugestão de LLM com regra ativa | `confidence`/`status: 'proposed'` obrigatórios em qualquer regra não-determinística; `active` só por parser ou aprovação humana |
|
|
434
|
+
|
|
435
|
+
## 21. Open Questions
|
|
436
|
+
|
|
437
|
+
1. `AgentProfile2` é um nome provisório — o contrato final substitui ou convive com
|
|
438
|
+
`AgentIdentity` atual? (Decisão de ADR-0078, marcada como aberta até Sprint 3.)
|
|
439
|
+
2. `constitution.json` versionado em git — e se dois branches compilarem regras conflitantes?
|
|
440
|
+
Fica para o design de `architecture:compile` (Sprint 1), não bloqueia a arquitetura geral.
|
|
441
|
+
3. Onde mora o limite entre "Change Risk Engine" e "Policy Engine" quando os dois crescerem —
|
|
442
|
+
revisar depois que `RiskEngine` tiver uso real (Sprint 2 retro).
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# LLM Fit Loop
|
|
2
|
+
|
|
3
|
+
O Forja integra CLIs de LLM sem receber, persistir ou imprimir credenciais. Um perfil descreve apenas
|
|
4
|
+
o adapter local, a finalidade e a fronteira de privacidade. Cada execução gera uma observação SQLite;
|
|
5
|
+
o roteamento continua explícito e recomendado por evidência, nunca automático no MVP.
|
|
6
|
+
|
|
7
|
+
## Primeiro uso
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
forja workspace:init
|
|
11
|
+
forja llm:profiles:init
|
|
12
|
+
forja llm:doctor
|
|
13
|
+
forja llm:probe codex
|
|
14
|
+
forja llm:recommend --role sdd-architect --task architecture
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Edite `<workspace>/.context/llm-profiles.json` para habilitar somente os adapters realmente instalados.
|
|
18
|
+
`command` aceita um executável; argumentos fixos vão em `commandArgs`. O processo é criado com
|
|
19
|
+
`shell: false` e o Forja não lê API keys.
|
|
20
|
+
|
|
21
|
+
## Execução e evidência
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
forja llm:run --profile codex --task specs/pagamentos/spec.md --context .context/sprint-pack.md
|
|
25
|
+
forja llm:eval --scope model --id codex:default
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`llm:run` calcula hashes e tokens estimados, mas não salva o prompt ou a resposta no banco. Salva
|
|
29
|
+
modelo, duração, resultado, comando, referências de contexto e métricas no armazenamento de
|
|
30
|
+
observações. `llm:eval` usa regras determinísticas do `EvaluationEngine` para medir sucesso,
|
|
31
|
+
retrabalho, custo, tempo e uso de contexto.
|
|
32
|
+
|
|
33
|
+
## Segurança e escopo
|
|
34
|
+
|
|
35
|
+
- O adapter padrão do Codex é `read-only`; mudanças de arquivos continuam no runtime/sandbox
|
|
36
|
+
supervisionado do Forja.
|
|
37
|
+
- `llm:probe` só executa `--version`; não consome tokens nem envia conteúdo do projeto.
|
|
38
|
+
- Recomendações são ordenadas por compatibilidade declarada e observações locais. O operador escolhe
|
|
39
|
+
o perfil; não existe failover automático nem chamada direta a APIs nesta versão.
|
|
40
|
+
- O dashboard pode editar e exibir perfis, mas não executa modelos. A antiga rota de execução retorna
|
|
41
|
+
`USE_FORJA_LLM_RUN`; use o CLI para que policy, auditoria e observabilidade sejam aplicadas.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Modos de Operação
|
|
2
|
+
|
|
3
|
+
ForjaJS possui dois caminhos de uso. Eles não compartilham dados por acidente.
|
|
4
|
+
|
|
5
|
+
## Embedded: dentro de um projeto consumidor
|
|
6
|
+
|
|
7
|
+
Quando `forja` é invocado em um diretório com `package.json` fora do repositório do framework, o modo
|
|
8
|
+
é `embedded`. Memória, SQLite, specs, contexto, perfis LLM e auditoria ficam no próprio projeto:
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
meu-app/
|
|
12
|
+
memory/sqlite/universal.db
|
|
13
|
+
specs/
|
|
14
|
+
.context/
|
|
15
|
+
forja-runs.jsonl
|
|
16
|
+
llm-profiles.json
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx forja llm:profiles:init
|
|
21
|
+
npx forja sync:universal
|
|
22
|
+
npx forja spec:new pagamentos
|
|
23
|
+
npx forja gsd:plan pagamentos "Aprovar pagamentos de alto valor"
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Use `FORJA_MODE=embedded` para forçar esse comportamento em um diretório sem `package.json`.
|
|
27
|
+
|
|
28
|
+
## Studio: fora de um projeto
|
|
29
|
+
|
|
30
|
+
O studio administra vários projetos num workspace externo. Os comandos de catálogo entram nesse modo
|
|
31
|
+
automaticamente: `workspace:init`, `project:new`, `project:list`, `project:upgrade`,
|
|
32
|
+
`workspace:project:check`, `init:project` e `demo:workspace`.
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
forja workspace:init
|
|
36
|
+
forja project:new meu-produto --ai claude,codex
|
|
37
|
+
forja project:list
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
O workspace é resolvido por `FORJA_WORKSPACE`, `~/.forjarc.json` ou `~/forja-workspace`. Use
|
|
41
|
+
`FORJA_MODE=studio` para forçar o modo externo em automações.
|
|
42
|
+
|
|
43
|
+
## Regra de decisão
|
|
44
|
+
|
|
45
|
+
| Situação | Modo | Onde ficam os dados |
|
|
46
|
+
| --- | --- | --- |
|
|
47
|
+
| Dependência instalada e comando executado na raiz do app | embedded | no próprio app |
|
|
48
|
+
| CLI global para criar/listar projetos | studio | workspace externo |
|
|
49
|
+
| `FORJA_WORKSPACE` definido | studio | path indicado pela variável |
|
|
50
|
+
| `FORJA_MODE` definido | explícito | conforme o modo escolhido |
|
|
51
|
+
|
|
52
|
+
O modo selecionado aparece como `project-cwd` ou `FORJA_WORKSPACE` nos diagnósticos do Forja.
|