forjajs 2.0.3 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/.claude/agents/release-auditor.md +19 -10
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +80 -0
  4. package/DOC-MAP.md +9 -0
  5. package/README.md +85 -5
  6. package/README.pt-BR.md +34 -5
  7. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  8. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  9. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  10. package/dist/apps/server/src/forja-nest.module.js +9 -4
  11. package/dist/apps/server/src/main.js +10 -1
  12. package/dist/bin/forja.js +14 -2
  13. package/dist/lib/code-context.js +6 -0
  14. package/dist/lib/core/architecture-gate.d.ts +20 -0
  15. package/dist/lib/core/architecture-gate.js +60 -0
  16. package/dist/lib/core/doc-graph.js +6 -4
  17. package/dist/lib/core/drift-gate.d.ts +18 -0
  18. package/dist/lib/core/drift-gate.js +55 -0
  19. package/dist/lib/core/gates.d.ts +9 -2
  20. package/dist/lib/core/gates.js +13 -2
  21. package/dist/lib/core/health.js +15 -0
  22. package/dist/lib/core/incident-search.d.ts +19 -0
  23. package/dist/lib/core/incident-search.js +32 -0
  24. package/dist/lib/core/model-pricing.d.ts +31 -0
  25. package/dist/lib/core/model-pricing.js +74 -0
  26. package/dist/lib/core/registry.d.ts +248 -0
  27. package/dist/lib/core/registry.js +249 -0
  28. package/dist/lib/core/release.d.ts +247 -0
  29. package/dist/lib/core/release.js +5 -1
  30. package/dist/lib/core/risk-collect.d.ts +19 -0
  31. package/dist/lib/core/risk-collect.js +173 -0
  32. package/dist/lib/drift-sentinel.d.ts +59 -0
  33. package/dist/lib/drift-sentinel.js +126 -0
  34. package/dist/lib/generators/memory-generator.js +8 -6
  35. package/dist/lib/generators/nest-generator.js +24 -10
  36. package/dist/lib/project-upgrade.js +1 -1
  37. package/dist/lib/workspace.d.ts +7 -0
  38. package/dist/lib/workspace.js +34 -5
  39. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  40. package/dist/packages/adapter-git/src/index.js +11 -6
  41. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  42. package/dist/packages/adapter-nest/src/index.js +26 -1
  43. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  44. package/dist/packages/adapter-sqlite/src/index.js +49 -0
  45. package/dist/packages/contracts/src/index.d.ts +33 -0
  46. package/dist/packages/contracts/src/index.js +13 -0
  47. package/dist/packages/core/src/index.d.ts +12 -0
  48. package/dist/packages/core/src/index.js +29 -0
  49. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  50. package/dist/packages/engineering/architecture/src/index.js +131 -0
  51. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  52. package/dist/packages/engineering/evidence/src/index.js +31 -0
  53. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  54. package/dist/packages/engineering/identity/src/index.js +88 -0
  55. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  56. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  57. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  58. package/dist/packages/engineering/provenance/src/index.js +21 -0
  59. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  60. package/dist/packages/engineering/risk/src/index.js +120 -0
  61. package/dist/packages/graph/src/index.d.ts +23 -1
  62. package/dist/packages/graph/src/index.js +88 -15
  63. package/dist/packages/llm/src/index.d.ts +43 -0
  64. package/dist/packages/llm/src/index.js +131 -0
  65. package/dist/packages/mcp/src/index.js +27 -8
  66. package/dist/packages/orchestration/src/index.d.ts +11 -1
  67. package/dist/packages/orchestration/src/index.js +34 -7
  68. package/dist/packages/policy/src/index.d.ts +40 -0
  69. package/dist/packages/policy/src/index.js +39 -4
  70. package/dist/packages/runtime/src/index.js +3 -0
  71. package/dist/packages/sandbox/src/index.d.ts +47 -0
  72. package/dist/packages/sandbox/src/index.js +59 -0
  73. package/dist/packages/validator/src/index.d.ts +8 -0
  74. package/dist/packages/validator/src/index.js +21 -6
  75. package/dist/scripts/adr.d.ts +17 -0
  76. package/dist/scripts/adr.js +152 -0
  77. package/dist/scripts/agent-harness.js +14 -4
  78. package/dist/scripts/agent.d.ts +27 -0
  79. package/dist/scripts/agent.js +249 -0
  80. package/dist/scripts/architecture.d.ts +16 -0
  81. package/dist/scripts/architecture.js +186 -0
  82. package/dist/scripts/cost-economy.d.ts +2 -0
  83. package/dist/scripts/cost-economy.js +79 -0
  84. package/dist/scripts/demo-autonomy.js +15 -8
  85. package/dist/scripts/demo-workspace.d.ts +6 -0
  86. package/dist/scripts/demo-workspace.js +101 -0
  87. package/dist/scripts/drift-check.d.ts +17 -0
  88. package/dist/scripts/drift-check.js +63 -0
  89. package/dist/scripts/engineer.d.ts +20 -0
  90. package/dist/scripts/engineer.js +208 -0
  91. package/dist/scripts/evidence.d.ts +12 -0
  92. package/dist/scripts/evidence.js +55 -0
  93. package/dist/scripts/gates.d.ts +6 -2
  94. package/dist/scripts/gates.js +14 -4
  95. package/dist/scripts/incident.d.ts +19 -0
  96. package/dist/scripts/incident.js +103 -0
  97. package/dist/scripts/llm-fit.js +160 -0
  98. package/dist/scripts/provenance.d.ts +14 -0
  99. package/dist/scripts/provenance.js +114 -0
  100. package/dist/scripts/risk.d.ts +15 -0
  101. package/dist/scripts/risk.js +81 -0
  102. package/dist/scripts/simulate.d.ts +20 -0
  103. package/dist/scripts/simulate.js +150 -0
  104. package/dist/scripts/sync-universal-memory.js +19 -6
  105. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  106. package/docs/llm-fit-loop.md +41 -0
  107. package/docs/modos-de-operacao.md +52 -0
  108. package/docs/produto/factsheet-marketing.md +151 -0
  109. package/docs/produto/roteiro-demo.md +47 -0
  110. package/memory/40-delivery/current-sprint.md +3 -6
  111. package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
  112. package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
  113. package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
  114. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  115. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  116. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  117. package/package.json +9 -2
  118. package/specs/agent-identity-reputation/plan.md +133 -0
  119. package/specs/agent-identity-reputation/spec.md +125 -0
  120. package/specs/agent-identity-reputation/tasks.md +51 -0
  121. package/specs/agent-runtime-monitoring/plan.md +78 -0
  122. package/specs/agent-runtime-monitoring/spec.md +92 -0
  123. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  124. package/specs/ai-code-provenance/plan.md +71 -0
  125. package/specs/ai-code-provenance/spec.md +97 -0
  126. package/specs/ai-code-provenance/tasks.md +39 -0
  127. package/specs/architecture-constitution/plan.md +110 -0
  128. package/specs/architecture-constitution/spec.md +114 -0
  129. package/specs/architecture-constitution/tasks.md +58 -0
  130. package/specs/change-risk-engine/plan.md +130 -0
  131. package/specs/change-risk-engine/spec.md +119 -0
  132. package/specs/change-risk-engine/tasks.md +72 -0
  133. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  134. package/specs/drift-sentinel/spec.md +117 -0
  135. package/specs/engineer-facade-extension/plan.md +71 -0
  136. package/specs/engineer-facade-extension/spec.md +98 -0
  137. package/specs/engineer-facade-extension/tasks.md +36 -0
  138. package/specs/engineering-evidence-ledger/plan.md +121 -0
  139. package/specs/engineering-evidence-ledger/spec.md +90 -0
  140. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  141. package/specs/engineering-graph-extensions/plan.md +92 -0
  142. package/specs/engineering-graph-extensions/spec.md +101 -0
  143. package/specs/engineering-graph-extensions/tasks.md +60 -0
  144. package/specs/engineering-intelligence/spec.md +177 -0
  145. package/specs/learning-loop-incidents/plan.md +59 -0
  146. package/specs/learning-loop-incidents/spec.md +93 -0
  147. package/specs/learning-loop-incidents/tasks.md +36 -0
  148. package/specs/predictive-change-simulation/plan.md +109 -0
  149. package/specs/predictive-change-simulation/spec.md +107 -0
  150. package/specs/predictive-change-simulation/tasks.md +41 -0
  151. package/specs/release-auditor-health/plan.md +88 -0
  152. package/specs/release-auditor-health/spec.md +82 -0
  153. package/specs/release-auditor-health/tasks.md +72 -0
  154. package/specs/smart-agent-routing/plan.md +55 -0
  155. package/specs/smart-agent-routing/spec.md +85 -0
  156. package/specs/smart-agent-routing/tasks.md +26 -0
  157. package/dist/scripts/server-persistence-probe.d.ts +0 -1
  158. package/dist/scripts/server-persistence-probe.js +0 -52
  159. package/dist/scripts/server-persistence-probe.mjs +0 -52
  160. /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
@@ -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 && fs.existsSync(projectsDir)) {
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.