forjajs 2.0.3 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/release-auditor.md +19 -10
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +80 -0
- package/DOC-MAP.md +9 -0
- package/README.md +85 -5
- package/README.pt-BR.md +34 -5
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
- package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
- package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
- package/dist/apps/server/src/forja-nest.module.js +9 -4
- package/dist/apps/server/src/main.js +10 -1
- package/dist/bin/forja.js +14 -2
- package/dist/lib/code-context.js +6 -0
- package/dist/lib/core/architecture-gate.d.ts +20 -0
- package/dist/lib/core/architecture-gate.js +60 -0
- package/dist/lib/core/doc-graph.js +6 -4
- package/dist/lib/core/drift-gate.d.ts +18 -0
- package/dist/lib/core/drift-gate.js +55 -0
- package/dist/lib/core/gates.d.ts +9 -2
- package/dist/lib/core/gates.js +13 -2
- package/dist/lib/core/health.js +15 -0
- package/dist/lib/core/incident-search.d.ts +19 -0
- package/dist/lib/core/incident-search.js +32 -0
- package/dist/lib/core/model-pricing.d.ts +31 -0
- package/dist/lib/core/model-pricing.js +74 -0
- package/dist/lib/core/registry.d.ts +248 -0
- package/dist/lib/core/registry.js +249 -0
- package/dist/lib/core/release.d.ts +247 -0
- package/dist/lib/core/release.js +5 -1
- package/dist/lib/core/risk-collect.d.ts +19 -0
- package/dist/lib/core/risk-collect.js +173 -0
- package/dist/lib/drift-sentinel.d.ts +59 -0
- package/dist/lib/drift-sentinel.js +126 -0
- package/dist/lib/generators/memory-generator.js +8 -6
- package/dist/lib/generators/nest-generator.js +24 -10
- package/dist/lib/project-upgrade.js +1 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +34 -5
- package/dist/packages/adapter-git/src/index.d.ts +1 -1
- package/dist/packages/adapter-git/src/index.js +11 -6
- package/dist/packages/adapter-nest/src/index.d.ts +19 -0
- package/dist/packages/adapter-nest/src/index.js +26 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
- package/dist/packages/adapter-sqlite/src/index.js +49 -0
- package/dist/packages/contracts/src/index.d.ts +33 -0
- package/dist/packages/contracts/src/index.js +13 -0
- package/dist/packages/core/src/index.d.ts +12 -0
- package/dist/packages/core/src/index.js +29 -0
- package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
- package/dist/packages/engineering/architecture/src/index.js +131 -0
- package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
- package/dist/packages/engineering/evidence/src/index.js +31 -0
- package/dist/packages/engineering/identity/src/index.d.ts +57 -0
- package/dist/packages/engineering/identity/src/index.js +88 -0
- package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
- package/dist/packages/engineering/monitoring/src/index.js +40 -0
- package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
- package/dist/packages/engineering/provenance/src/index.js +21 -0
- package/dist/packages/engineering/risk/src/index.d.ts +89 -0
- package/dist/packages/engineering/risk/src/index.js +120 -0
- package/dist/packages/graph/src/index.d.ts +23 -1
- package/dist/packages/graph/src/index.js +88 -15
- package/dist/packages/llm/src/index.d.ts +43 -0
- package/dist/packages/llm/src/index.js +131 -0
- package/dist/packages/mcp/src/index.js +27 -8
- package/dist/packages/orchestration/src/index.d.ts +11 -1
- package/dist/packages/orchestration/src/index.js +34 -7
- package/dist/packages/policy/src/index.d.ts +40 -0
- package/dist/packages/policy/src/index.js +39 -4
- package/dist/packages/runtime/src/index.js +3 -0
- package/dist/packages/sandbox/src/index.d.ts +47 -0
- package/dist/packages/sandbox/src/index.js +59 -0
- package/dist/packages/validator/src/index.d.ts +8 -0
- package/dist/packages/validator/src/index.js +21 -6
- package/dist/scripts/adr.d.ts +17 -0
- package/dist/scripts/adr.js +152 -0
- package/dist/scripts/agent-harness.js +14 -4
- package/dist/scripts/agent.d.ts +27 -0
- package/dist/scripts/agent.js +249 -0
- package/dist/scripts/architecture.d.ts +16 -0
- package/dist/scripts/architecture.js +186 -0
- package/dist/scripts/cost-economy.d.ts +2 -0
- package/dist/scripts/cost-economy.js +79 -0
- package/dist/scripts/demo-autonomy.js +15 -8
- package/dist/scripts/demo-workspace.d.ts +6 -0
- package/dist/scripts/demo-workspace.js +101 -0
- package/dist/scripts/drift-check.d.ts +17 -0
- package/dist/scripts/drift-check.js +63 -0
- package/dist/scripts/engineer.d.ts +20 -0
- package/dist/scripts/engineer.js +208 -0
- package/dist/scripts/evidence.d.ts +12 -0
- package/dist/scripts/evidence.js +55 -0
- package/dist/scripts/gates.d.ts +6 -2
- package/dist/scripts/gates.js +14 -4
- package/dist/scripts/incident.d.ts +19 -0
- package/dist/scripts/incident.js +103 -0
- package/dist/scripts/llm-fit.js +160 -0
- package/dist/scripts/provenance.d.ts +14 -0
- package/dist/scripts/provenance.js +114 -0
- package/dist/scripts/risk.d.ts +15 -0
- package/dist/scripts/risk.js +81 -0
- package/dist/scripts/simulate.d.ts +20 -0
- package/dist/scripts/simulate.js +150 -0
- package/dist/scripts/sync-universal-memory.js +19 -6
- package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
- package/docs/llm-fit-loop.md +41 -0
- package/docs/modos-de-operacao.md +52 -0
- package/docs/produto/factsheet-marketing.md +151 -0
- package/docs/produto/roteiro-demo.md +47 -0
- package/memory/40-delivery/current-sprint.md +3 -6
- package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
- package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
- package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
- package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
- package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
- package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
- package/package.json +9 -2
- package/specs/agent-identity-reputation/plan.md +133 -0
- package/specs/agent-identity-reputation/spec.md +125 -0
- package/specs/agent-identity-reputation/tasks.md +51 -0
- package/specs/agent-runtime-monitoring/plan.md +78 -0
- package/specs/agent-runtime-monitoring/spec.md +92 -0
- package/specs/agent-runtime-monitoring/tasks.md +39 -0
- package/specs/ai-code-provenance/plan.md +71 -0
- package/specs/ai-code-provenance/spec.md +97 -0
- package/specs/ai-code-provenance/tasks.md +39 -0
- package/specs/architecture-constitution/plan.md +110 -0
- package/specs/architecture-constitution/spec.md +114 -0
- package/specs/architecture-constitution/tasks.md +58 -0
- package/specs/change-risk-engine/plan.md +130 -0
- package/specs/change-risk-engine/spec.md +119 -0
- package/specs/change-risk-engine/tasks.md +72 -0
- package/specs/cost-aware-autonomy-budget/spec.md +102 -0
- package/specs/drift-sentinel/spec.md +117 -0
- package/specs/engineer-facade-extension/plan.md +71 -0
- package/specs/engineer-facade-extension/spec.md +98 -0
- package/specs/engineer-facade-extension/tasks.md +36 -0
- package/specs/engineering-evidence-ledger/plan.md +121 -0
- package/specs/engineering-evidence-ledger/spec.md +90 -0
- package/specs/engineering-evidence-ledger/tasks.md +54 -0
- package/specs/engineering-graph-extensions/plan.md +92 -0
- package/specs/engineering-graph-extensions/spec.md +101 -0
- package/specs/engineering-graph-extensions/tasks.md +60 -0
- package/specs/engineering-intelligence/spec.md +177 -0
- package/specs/learning-loop-incidents/plan.md +59 -0
- package/specs/learning-loop-incidents/spec.md +93 -0
- package/specs/learning-loop-incidents/tasks.md +36 -0
- package/specs/predictive-change-simulation/plan.md +109 -0
- package/specs/predictive-change-simulation/spec.md +107 -0
- package/specs/predictive-change-simulation/tasks.md +41 -0
- package/specs/release-auditor-health/plan.md +88 -0
- package/specs/release-auditor-health/spec.md +82 -0
- package/specs/release-auditor-health/tasks.md +72 -0
- package/specs/smart-agent-routing/plan.md +55 -0
- package/specs/smart-agent-routing/spec.md +85 -0
- package/specs/smart-agent-routing/tasks.md +26 -0
- package/dist/scripts/server-persistence-probe.d.ts +0 -1
- package/dist/scripts/server-persistence-probe.js +0 -52
- package/dist/scripts/server-persistence-probe.mjs +0 -52
- /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# ADR-0079: Autonomous Maintenance — postura de prontidão, sem habilitação automática
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-09-01
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: engineering-control-plane, policy, autonomy, sdd
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
A visão original do ForjaJS 3.0 lista "Autonomous Maintenance" (Fase 7) como a fase final do
|
|
11
|
+
roadmap de 33 features, com uma instrução explícita: "só arquitetura preparatória, nunca habilitação
|
|
12
|
+
automática". Os Sprints 1-9 (SPEC-032 a SPEC-041, ADR-0078) já entregaram, de forma independente e
|
|
13
|
+
cada um com sua própria evidência real, todos os componentes que uma decisão de manutenção autônoma
|
|
14
|
+
precisaria consultar:
|
|
15
|
+
|
|
16
|
+
- **Risco** (`RiskEngine`/`assessRisk`, SPEC-034) — score 0-100 explicável de uma mudança.
|
|
17
|
+
- **Arquitetura** (`checkConstitution`, SPEC-033) — se a mudança viola uma regra derivada de ADR.
|
|
18
|
+
- **Reputação do agente** (`computeReputationScore`, SPEC-036) — confiabilidade derivada de
|
|
19
|
+
comportamento real, nunca auto-declarada.
|
|
20
|
+
- **Recomendação de agente** (`recommendAgent`, SPEC-037) — adequação de um agente a um papel.
|
|
21
|
+
- **Simulação preditiva** (`forja simulate`, SPEC-038) — teste+arquitetura+risco num worktree
|
|
22
|
+
isolado, com recomendação `promote`/`review`/`discard`.
|
|
23
|
+
- **Proveniência** (`extractProvenance`, SPEC-039) — quem/qual agente produziu um arquivo.
|
|
24
|
+
- **Anomalia de comportamento** (`detectAnomaly`, SPEC-040) — desvio do comportamento recente de um
|
|
25
|
+
agente contra sua própria linha de base.
|
|
26
|
+
- **Incidentes e sugestão por similaridade** (`incident:similar`, SPEC-041) — conhecimento
|
|
27
|
+
reconsultável de problemas passados.
|
|
28
|
+
|
|
29
|
+
Todos os seis primeiros já têm um ponto de integração real e testado com `PolicyEngine`: `RiskLevel`
|
|
30
|
+
(nativo), `riskScoreRange`/`riskScore` (SPEC-034), `anomalyScoreRange`/`anomalyScore` (SPEC-040) —
|
|
31
|
+
sempre como `number` puro que uma regra de política pode consultar, nunca como um motor de decisão
|
|
32
|
+
paralelo (mesmo princípio repetido em toda a fundação, D3 de SPEC-034).
|
|
33
|
+
|
|
34
|
+
O que falta pra "Autonomous Maintenance" de verdade — um agente detectar um problema, corrigi-lo e
|
|
35
|
+
promover a correção **sem** aprovação humana — não é mais peças de dado. É a composição de tudo
|
|
36
|
+
isso numa decisão de política real que permita `ALLOW`/`ALLOW_WITH_LIMITS` sem `REQUIRE_APPROVAL`
|
|
37
|
+
mesmo em cenários de risco não-trivial. Essa é exatamente a linha que a visão original pede pra não
|
|
38
|
+
cruzar ainda.
|
|
39
|
+
|
|
40
|
+
## Decisão
|
|
41
|
+
|
|
42
|
+
**Fase 7 fica em prontidão arquitetural, não em implementação.** Nenhuma regra de `PolicyEngine`
|
|
43
|
+
neste repositório usa `riskScoreRange`/`anomalyScoreRange` pra conceder `ALLOW`/`ALLOW_WITH_LIMITS`
|
|
44
|
+
sem aprovação — as duas capacidades existem (SPEC-034, SPEC-040) e são consultáveis, mas nenhuma
|
|
45
|
+
regra real as conecta a uma autonomia maior. Compor os sinais já existentes num fluxo de decisão é
|
|
46
|
+
trabalho de composição pura (nenhum motor novo, mesmo padrão de `forja engineer`/`forja simulate`),
|
|
47
|
+
mas a regra de política que permitiria a aplicação automática de uma correção **exige aprovação
|
|
48
|
+
humana explícita antes de existir**, não só antes de rodar.
|
|
49
|
+
|
|
50
|
+
Guardrails que qualquer spec futura de "Autonomous Maintenance" real precisa manter, sem exceção
|
|
51
|
+
(cada um já é um princípio já seguido em alguma spec anterior, não uma invenção desta ADR):
|
|
52
|
+
|
|
53
|
+
1. **Fail-closed em ambiguidade** — dado insuficiente (confidence baixa em qualquer um dos sete
|
|
54
|
+
sinais acima) nunca vira permissão, sempre vira `REQUIRE_APPROVAL`/`human_in_the_loop` (mesmo
|
|
55
|
+
princípio de AC-3 de SPEC-036, AC-2 de SPEC-040).
|
|
56
|
+
2. **Nenhum motor de decisão paralelo** — a decisão de aplicar ou não uma correção continua sendo
|
|
57
|
+
do `PolicyEngine` (regras existentes, aditivas), nunca de um "orquestrador de manutenção" que
|
|
58
|
+
decide por fora da política (mesmo princípio já resolvido pra risco/anomalia, D3 de SPEC-034).
|
|
59
|
+
3. **Simulação antes de qualquer promoção real** — `forja simulate` (SPEC-038) já prova que testar
|
|
60
|
+
uma mudança num worktree isolado antes de decidir é viável e rápido; nenhuma correção autônoma
|
|
61
|
+
deveria pular essa etapa, mesmo com todos os sinais favoráveis.
|
|
62
|
+
4. **Reversibilidade obrigatória** — qualquer aplicação automática precisa de um caminho de
|
|
63
|
+
rollback real (`SandboxEngine.rollback`, já existente) testado antes de a regra existir, não
|
|
64
|
+
depois do primeiro incidente.
|
|
65
|
+
5. **Nenhum LLM como fonte de verdade de decisão crítica** — os sete sinais acima são todos
|
|
66
|
+
determinísticos; se uma spec futura quiser LLM em algum ponto do fluxo, ele entra como sugestão
|
|
67
|
+
revisável (`status: 'proposed'`, `confidence < 1`), nunca como regra `active`/decisão automática
|
|
68
|
+
— mesmo padrão já estabelecido em `architecture:compile` (SPEC-033) e em toda a fundação.
|
|
69
|
+
6. **Auditoria completa e correlacionável** — `AuditRecord`/`Evidence`/`ProvenanceRecord`
|
|
70
|
+
(SPEC-039) já dão o rastro; qualquer aplicação automática precisa gravar evidência suficiente
|
|
71
|
+
pra reconstruir "por que o sistema decidiu isso" sem depender de memória humana.
|
|
72
|
+
|
|
73
|
+
## Alternativas consideradas
|
|
74
|
+
|
|
75
|
+
- **Implementar uma regra de política real que já habilita alguma forma de auto-aplicação de baixo
|
|
76
|
+
risco** (ex.: só para mudanças com `riskScore` muito baixo e `trustLevel` muito alto) — rejeitada
|
|
77
|
+
porque cruzaria exatamente a linha que a visão original pede pra não cruzar nesta fase ("nunca
|
|
78
|
+
habilitação automática"), e porque este workspace não acumulou dado real suficiente (histórico de
|
|
79
|
+
`Observation`/incidentes) pra validar que os limiares escolhidos seriam seguros na prática, não só
|
|
80
|
+
em teoria.
|
|
81
|
+
- **Não escrever nada pra Fase 7** — rejeitada porque a visão original pede explicitamente
|
|
82
|
+
"arquitetar o caminho" mesmo sem habilitar; documentar os guardrails agora, enquanto o desenho de
|
|
83
|
+
cada peça está fresco, é mais barato e mais correto do que reconstruir esse raciocínio do zero
|
|
84
|
+
quando (e se) uma spec futura decidir implementar de verdade.
|
|
85
|
+
|
|
86
|
+
## Consequências
|
|
87
|
+
|
|
88
|
+
**Positivas**:
|
|
89
|
+
- Fecha o roadmap de 33 features da visão original ForjaJS 3.0 até onde é honestamente
|
|
90
|
+
implementável neste workspace — nada fica "esquecido", cada item tem uma decisão explícita
|
|
91
|
+
(implementado, ou por que não).
|
|
92
|
+
- Qualquer spec futura de manutenção autônoma real começa com os guardrails já escritos, em vez de
|
|
93
|
+
precisar redescobri-los.
|
|
94
|
+
|
|
95
|
+
**Negativas / Trade-offs**:
|
|
96
|
+
- Nenhuma automação de manutenção acontece a partir desta ADR — é puramente preparatório, por
|
|
97
|
+
desenho explícito da visão original, não uma limitação técnica.
|
|
98
|
+
|
|
99
|
+
## Rastreamento
|
|
100
|
+
- Implementação: nenhuma (ADR de prontidão/prep — sem código associado, por desenho)
|
|
101
|
+
- Specs relacionadas: SPEC-032 a SPEC-041 (todos os componentes compostos aqui)
|
|
102
|
+
- ADRs relacionadas: ADR-0078 (decisão estrutural 3.0), ADR-0020 (domínio puro de `packages/policy`)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forjajs",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.0.0",
|
|
4
4
|
"description": "ForjaJS é uma plataforma local-first para memória, contexto, governança e execução supervisionada de agentes de desenvolvimento",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -91,7 +91,14 @@
|
|
|
91
91
|
"types:check": "tsc --noEmit",
|
|
92
92
|
"test": "node --test test/*.test.js",
|
|
93
93
|
"demo:autonomy": "node scripts/demo-autonomy.ts",
|
|
94
|
-
"
|
|
94
|
+
"demo:workspace": "node bin/forja.ts demo:workspace",
|
|
95
|
+
"benchmark:context": "node scripts/context-benchmark.ts",
|
|
96
|
+
"llm:profiles:init": "node bin/forja.ts llm:profiles:init",
|
|
97
|
+
"llm:doctor": "node bin/forja.ts llm:doctor",
|
|
98
|
+
"llm:probe": "node bin/forja.ts llm:probe",
|
|
99
|
+
"llm:recommend": "node bin/forja.ts llm:recommend",
|
|
100
|
+
"llm:run": "node bin/forja.ts llm:run",
|
|
101
|
+
"llm:eval": "node bin/forja.ts llm:eval"
|
|
95
102
|
},
|
|
96
103
|
"keywords": [
|
|
97
104
|
"agents",
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Plan: Agent Identity & Reputation
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
Novo sub-domínio `packages/engineering/identity` (autorizado por ADR-0078), puro domínio: só
|
|
10
|
+
`computeReputationScore`, uma função que recebe um `EvaluationReport` (já produzido por
|
|
11
|
+
`packages/evals.EvaluationEngine`, reaproveitado sem reimplementar nenhuma métrica) e devolve um
|
|
12
|
+
`AgentReputationScore`. Persistência de `AgentProfile2` **não precisa de migration nova** —
|
|
13
|
+
`packages/adapter-sqlite` já tem `SqliteJsonRepository` (tabela genérica `forja_records`,
|
|
14
|
+
`collection`+`id`+`payload`) usada por `SqliteRuntimeRunStore`/`RuntimePersistence`; um
|
|
15
|
+
`SqliteAgentProfileStore` fino por cima dela (mesmo padrão) é só mais uma `collection`.
|
|
16
|
+
|
|
17
|
+
## 2. Módulos afetados
|
|
18
|
+
|
|
19
|
+
| Caminho | Mudança | Risco |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `packages/contracts/src/index.ts` | `AgentProfile2` novo (aditivo — `AgentIdentity` intocado) | Baixo |
|
|
22
|
+
| `packages/engineering/identity/src/index.ts` | novo — `computeReputationScore`, thresholds default | Médio — lógica nova, mas pura/testável |
|
|
23
|
+
| `packages/adapter-sqlite/src/index.ts` | `SqliteAgentProfileStore` novo (reaproveita `SqliteJsonRepository`, sem migration nova) | Baixo |
|
|
24
|
+
| `scripts/agent.ts` | novo — `agent:register/list/show/score/history` | Médio — I/O fino sobre engine puro + stores já existentes |
|
|
25
|
+
| `lib/core/registry.ts` | 5 comandos novos | Baixo |
|
|
26
|
+
| `test/agent-identity-reputation.test.js` (novo) | testes puros de `computeReputationScore` | — |
|
|
27
|
+
| `test/agent-cli.test.js` (novo) | fixture isolada, CLI ponta a ponta | — |
|
|
28
|
+
|
|
29
|
+
## 3. Diagrama de fluxo
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
agent:register <id> --role ... ──► SqliteAgentProfileStore.save (sem trustLevel/autonomyLevel)
|
|
33
|
+
│
|
|
34
|
+
agent:score <id> [--domain <d>] │
|
|
35
|
+
│ │
|
|
36
|
+
├─► SqliteObservationStore.list() filtrado por agentId (+ capabilityId===domain)
|
|
37
|
+
│ │
|
|
38
|
+
│ ▼
|
|
39
|
+
├─► EvaluationEngine.evaluate({scope:'agent', scopeId, observations}) [já existente]
|
|
40
|
+
│ │
|
|
41
|
+
│ ▼
|
|
42
|
+
└─► computeReputationScore(report) [packages/engineering/identity, puro]
|
|
43
|
+
│
|
|
44
|
+
▼
|
|
45
|
+
AgentReputationScore (trustLevel, autonomyLevel, confidence, evidenceIds)
|
|
46
|
+
│
|
|
47
|
+
▼
|
|
48
|
+
SqliteAgentProfileStore.save (profile + trustLevel/autonomyLevel/lastScoredAt)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## 4. Contratos (API/CLI/Schema)
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
// packages/contracts/src/index.ts — aditivo
|
|
55
|
+
export interface AgentProfile2 extends AuditFields {
|
|
56
|
+
readonly id: EntityId;
|
|
57
|
+
readonly role: string;
|
|
58
|
+
readonly provider?: string;
|
|
59
|
+
readonly model?: string;
|
|
60
|
+
readonly capabilities: readonly string[];
|
|
61
|
+
readonly architectureDomains: readonly string[];
|
|
62
|
+
readonly limits?: { readonly maxFiles?: number; readonly maxCostUsd?: number; readonly maxDurationMs?: number };
|
|
63
|
+
// Só escritos por `agent:score` (via computeReputationScore) — nunca aceitos em `agent:register`.
|
|
64
|
+
readonly trustLevel?: number; // 0-5
|
|
65
|
+
readonly autonomyLevel?: 'autonomous' | 'autonomous_with_review' | 'supervised' | 'human_in_the_loop';
|
|
66
|
+
readonly lastScoredAt?: ISO8601;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// packages/engineering/identity/src/index.ts
|
|
70
|
+
export interface AgentReputationScore {
|
|
71
|
+
readonly agentId: string;
|
|
72
|
+
readonly domain?: string;
|
|
73
|
+
readonly trustLevel: number;
|
|
74
|
+
readonly autonomyLevel: 'autonomous' | 'autonomous_with_review' | 'supervised' | 'human_in_the_loop';
|
|
75
|
+
readonly confidence: number;
|
|
76
|
+
readonly sampleSize: number;
|
|
77
|
+
readonly metrics: Readonly<Record<string, number>>;
|
|
78
|
+
readonly evidenceIds: readonly string[];
|
|
79
|
+
}
|
|
80
|
+
export interface ReputationThresholds { readonly minSampleSize: number; readonly autonomous: number; readonly autonomousWithReview: number; readonly supervised: number; }
|
|
81
|
+
export const DEFAULT_REPUTATION_THRESHOLDS: ReputationThresholds; // minSampleSize:5, autonomous:4, autonomousWithReview:3, supervised:1 (escala 0-5)
|
|
82
|
+
export function computeReputationScore(report: EvaluationReport, meta: { agentId: string; domain?: string; thresholds?: ReputationThresholds }): AgentReputationScore;
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
agent:register <id> --role <role> [--provider <p>] [--model <m>] [--capabilities <c1,c2>] [--domains <d1,d2>]
|
|
87
|
+
agent:list
|
|
88
|
+
agent:show <id>
|
|
89
|
+
agent:score <id> [--domain <d>]
|
|
90
|
+
agent:history <id>
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## 5. Decisões e alternativas
|
|
94
|
+
|
|
95
|
+
**D1**: `trustLevel` 0-5, fórmula fixa a partir das métricas que `EvaluationEngine` já calcula —
|
|
96
|
+
`0.5·successRate + 0.2·(1-reworkRate) + 0.2·(1-rollbackRate) + 0.1·(1-assertionsWithoutEvidenceRate)`,
|
|
97
|
+
arredondado pra 0-5. Pesos documentados aqui e no código (mesmo princípio de RiskEngine, SPEC-034)
|
|
98
|
+
— nunca "número mágico". Revisitar se dado real mostrar que os pesos não fazem sentido (mesmo kill
|
|
99
|
+
criteria de RiskEngine).
|
|
100
|
+
|
|
101
|
+
**D2**: `agent:register` **não aceita** `--trust-level`/`--autonomy-level` como flag — não é
|
|
102
|
+
validação em runtime, é ausência da opção na CLI. Único jeito de `trustLevel` mudar é
|
|
103
|
+
`computeReputationScore` via `agent:score`. Alternativa rejeitada: aceitar e validar contra
|
|
104
|
+
"não pode ser setado à mão" — mais frágil (alguém pode enganar a validação) que simplesmente nunca
|
|
105
|
+
expor o caminho.
|
|
106
|
+
|
|
107
|
+
**D3**: sem `SqliteAgentProfileStore` novo com migration própria — reaproveita
|
|
108
|
+
`SqliteJsonRepository`/`forja_records` (mesmo padrão de `SqliteRuntimeRunStore`). Zero migration
|
|
109
|
+
nova nesta spec inteira.
|
|
110
|
+
|
|
111
|
+
**D4**: `domain` (do `AgentReputationService.score(agentId, domain?)` do doc de arquitetura) mapeia
|
|
112
|
+
pra um filtro por `Observation.capabilityId` — não é um campo novo em `EvaluationScope` (que já tem
|
|
113
|
+
`'capability'` como scope próprio, mas isso filtraria SÓ por capability, perdendo o filtro por
|
|
114
|
+
agente ao mesmo tempo). Filtro duplo (agentId E capabilityId) é feito no adapter antes de chamar
|
|
115
|
+
`EvaluationEngine.evaluate({observations: <já filtrado>})` — `EvaluationEngine` já aceita
|
|
116
|
+
`observations` pré-filtrado exatamente pra esse caso (parâmetro existente, não uma mudança).
|
|
117
|
+
|
|
118
|
+
## 6. Dependências
|
|
119
|
+
|
|
120
|
+
- `packages/evals.EvaluationEngine` (já existente) — não reimplementado, só consumido.
|
|
121
|
+
- `packages/adapter-sqlite.SqliteObservationStore`/`SqliteJsonRepository` (já existentes).
|
|
122
|
+
|
|
123
|
+
## 7. Rollout
|
|
124
|
+
|
|
125
|
+
- [ ] Feature flag necessária? Não — comandos novos, opt-in por natureza.
|
|
126
|
+
- [ ] Migração de dados existentes? Não (D3).
|
|
127
|
+
- [ ] Doc/persona impactada? README (comandos novos).
|
|
128
|
+
|
|
129
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
130
|
+
|
|
131
|
+
Se `agent:score` sobre dado real (ou amostra sintética documentada, §8 do spec) não corresponder a
|
|
132
|
+
julgamento humano de confiabilidade, os pesos de D1 são revisados antes de qualquer spec futura
|
|
133
|
+
conectar `trustLevel` a decisão de política (§5 "Fora" desta spec, explicitamente adiado).
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Spec: Agent Identity & Reputation
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-036
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 4 (primeiro sprint da Fase 3 da visão original — Agent Identity / Agent
|
|
8
|
+
Reputation / Project Evals / Smart Routing; esta spec cobre as duas primeiras, Smart Routing fica
|
|
9
|
+
para spec própria — ver §5)
|
|
10
|
+
- **ADRs relacionadas**: ADR-0078 (bounded context `packages/engineering/*` já autorizado; nenhuma
|
|
11
|
+
decisão estrutural nova aqui, só mais um sub-domínio dentro do mesmo contexto)
|
|
12
|
+
|
|
13
|
+
> Depende de SPEC-034 (Change Risk Engine — dados reais de risco começam a existir a partir de
|
|
14
|
+
> agora) e reaproveita `packages/evals.EvaluationEngine` (já existente, scope `'agent'`) — a razão
|
|
15
|
+
> pela qual `docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md` §19 recomendou
|
|
16
|
+
> começar a Fase 3 só depois do Sprint 1-3 estar rodando: reputação precisa de comportamento real
|
|
17
|
+
> pra pontuar, não de um motor de decisão novo.
|
|
18
|
+
|
|
19
|
+
## 1. Problema
|
|
20
|
+
|
|
21
|
+
`AgentIdentity` (`packages/contracts`) hoje é efêmero — `{id, name, role, autonomy}` passado a cada
|
|
22
|
+
`PolicyRequest`, sem histórico persistido. Não existe registro de "quais agentes operam neste
|
|
23
|
+
projeto, com quais capabilities, e qual o histórico de confiabilidade de cada um" — cada run começa
|
|
24
|
+
do zero, sem memória de que um agente já causou 3 rollbacks nesta capability ou tem 95% de sucesso
|
|
25
|
+
naquela. `EvaluationEngine.evaluate({scope:'agent', scopeId})` já produz as métricas certas
|
|
26
|
+
(`successRate`, `reworkRate`, `rollbackRate` etc.), mas nada as transforma num score consultável
|
|
27
|
+
nem as persiste como identidade.
|
|
28
|
+
|
|
29
|
+
## 2. Proposta de valor
|
|
30
|
+
|
|
31
|
+
`forja agent:register`/`:list`/`:show`/`:score`/`:history` dão à Forja uma identidade de agente
|
|
32
|
+
persistente com reputação derivada de comportamento real (nunca auto-declarada) — base para, no
|
|
33
|
+
futuro, `PolicyEngine` e `forja engineer` considerarem "este agente já provou que lida bem com este
|
|
34
|
+
tipo de mudança" em vez de tratar todo agente como desconhecido a cada run.
|
|
35
|
+
|
|
36
|
+
## 3. User stories
|
|
37
|
+
|
|
38
|
+
- **Como** governance, **quero** ver o histórico de confiabilidade de um agente antes de ampliar
|
|
39
|
+
sua autonomia, **para que** a decisão seja baseada em comportamento real, não em confiança cega.
|
|
40
|
+
- **Como** desenvolvedor operando múltiplos agentes/projetos, **quero** `agent:list` mostrando quem
|
|
41
|
+
são os agentes registrados e seu nível de confiança atual, **para que** eu saiba a quem atribuir
|
|
42
|
+
o quê sem adivinhar.
|
|
43
|
+
- **Como** sdd-architect, **quero** que `trustLevel` seja sempre derivado de `Observation`s reais
|
|
44
|
+
(nunca um campo que alguém simplesmente edita), **para que** reputação não vire teatro.
|
|
45
|
+
|
|
46
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
47
|
+
|
|
48
|
+
- [x] AC-1: `AgentProfile2` (extensão aditiva de `packages/contracts`, `AgentIdentity` continua
|
|
49
|
+
existindo sem mudança) é persistido via `SqliteAgentProfileStore` (reaproveita
|
|
50
|
+
`SqliteJsonRepository`/`forja_records` já existente — **sem** migration nova, revisado em
|
|
51
|
+
D3 do plan) — `role`/`provider`/`model`/`capabilities`/`architectureDomains`/`limits` são
|
|
52
|
+
dados de registro; `trustLevel`/`autonomyLevel` **nunca** aceitos em `agent:register` — só
|
|
53
|
+
escritos por `agent:score`.
|
|
54
|
+
- [x] AC-2: `computeReputationScore` (função pura, `packages/engineering/identity`) recebe um
|
|
55
|
+
`EvaluationReport` (já produzido por `EvaluationEngine`, reaproveitado sem reimplementar) e
|
|
56
|
+
devolve `AgentReputationScore` — `trustLevel` 0-5, `confidence` proporcional ao tamanho da
|
|
57
|
+
amostra (`observationCount`), nunca escondida.
|
|
58
|
+
- [x] AC-3: sem amostra suficiente (cold start, `observationCount` abaixo de um mínimo
|
|
59
|
+
configurável), `autonomyLevel` cai para `human_in_the_loop` por padrão — fail-closed em
|
|
60
|
+
ambiguidade (mesmo princípio já usado em Architecture Constitution/Risk Engine), nunca
|
|
61
|
+
`autonomous` por falta de dado.
|
|
62
|
+
- [x] AC-4: `forja agent:register/:list/:show/:score [--domain <d>]/:history` funcionais;
|
|
63
|
+
`agent:score` persiste o `trustLevel`/`autonomyLevel` calculado de volta no profile (cache
|
|
64
|
+
da última pontuação, não fonte de verdade paralela — a fonte de verdade continua sendo os
|
|
65
|
+
`Observation`s).
|
|
66
|
+
- [x] AC-5: nenhum comando/contrato existente muda de assinatura; `PolicyEngine`/`RuntimeEngine`
|
|
67
|
+
continuam funcionando com `AgentIdentity` efêmero exatamente como hoje — este sprint não
|
|
68
|
+
acopla nada a `AgentProfile2` ainda (ver §5, Smart Routing/Policy fica para spec própria).
|
|
69
|
+
|
|
70
|
+
## 5. Escopo
|
|
71
|
+
|
|
72
|
+
**Dentro**: `AgentProfile2` + persistência; `computeReputationScore` (motor puro); CLI
|
|
73
|
+
`agent:register/list/show/score/history`.
|
|
74
|
+
|
|
75
|
+
**Fora** (spec própria quando chegar a vez, mesmo princípio de escopo já usado em SPEC-031 §5 —
|
|
76
|
+
"fases seguintes exigem spec própria, não emenda desta"):
|
|
77
|
+
- Smart Agent Routing (estender `scripts/llm-fit.ts`/`llm:recommend` com dados de reputação) — a
|
|
78
|
+
visão original agrupa isso na mesma Fase 3, mas é consumo do que esta spec produz, não parte de
|
|
79
|
+
produzir; melhor com `AgentReputationScore` já rodando contra dado real primeiro.
|
|
80
|
+
- `PolicyEngine`/`forja engineer` passarem a *consultar* `trustLevel`/`AgentReputationScore`
|
|
81
|
+
automaticamente — mesmo raciocínio de SPEC-034 D3 (score é informação, não decisão automática) e
|
|
82
|
+
mesmo motivo de não estar aqui: consumo depende deste sprint já estar em produção.
|
|
83
|
+
- Agent Runtime Monitoring / Behavior Anomaly Engine (Fase 5 da visão original) — comportamento
|
|
84
|
+
*durante* um run, não identidade/reputação entre runs.
|
|
85
|
+
|
|
86
|
+
## 6. NFRs / restrições
|
|
87
|
+
|
|
88
|
+
- Determinístico: `computeReputationScore` é uma função pura sobre métricas já calculadas por
|
|
89
|
+
`EvaluationEngine` — nenhuma chamada de LLM em nenhum ponto.
|
|
90
|
+
- Fail-closed: amostra insuficiente nunca produz `autonomous` (AC-3).
|
|
91
|
+
- `trustLevel` nunca é um campo editável por humano ou agente — só `agent:score` escreve nele, e só
|
|
92
|
+
com o valor que `computeReputationScore` calculou.
|
|
93
|
+
|
|
94
|
+
## 7. Riscos e mitigação
|
|
95
|
+
|
|
96
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
97
|
+
|---|---|---|---|
|
|
98
|
+
| Reputação virar gate automático de autonomia sem revisão humana | Média (é a tentação óbvia) | Alta (agente ruim ganha mais autonomia sozinho) | Este sprint não conecta `trustLevel` a nenhuma decisão de `PolicyEngine` — é só leitura/consulta (§5, "Fora") |
|
|
99
|
+
| Cold start: agente novo sem `Observation` | Alta em projetos novos ou agentes recém-registrados | Baixa (esperado) | AC-3: fail-closed pra `human_in_the_loop`, `confidence` baixa declarada, nunca escondida |
|
|
100
|
+
| `AgentProfile2` divergir de `AgentIdentity` (dois conceitos de "quem é o agente") | Baixa se documentado | Média | `AgentIdentity` continua sendo o tipo usado em `PolicyRequest`/`RuntimeRun` (efêmero, por run); `AgentProfile2` é o registro persistente — dois papéis diferentes, não dois conceitos concorrentes; nota explícita no código |
|
|
101
|
+
|
|
102
|
+
## 8. Métricas de sucesso
|
|
103
|
+
|
|
104
|
+
Registrar pelo menos 1 agente real usado nesta sessão de desenvolvimento (`apk`/o agente que
|
|
105
|
+
implementou os Sprints 1-3), rodar `agent:score` contra os `Observation`s reais já persistidos (se
|
|
106
|
+
existirem neste workspace) ou contra uma amostra sintética documentada como tal, e confirmar que o
|
|
107
|
+
score reflete corretamente sucesso/retrabalho — revisão humana, mesma metodologia usada em SPEC-034
|
|
108
|
+
§8.
|
|
109
|
+
|
|
110
|
+
**Validado**: workspace de desenvolvimento não acumulou `Observation`s reais suficientes ainda
|
|
111
|
+
(`sync:universal`/runtime real não foi exercitado neste ambiente sandboxado) — validado com amostra
|
|
112
|
+
sintética documentada como tal (`test/agent-cli.test.js`, 4 sucessos + 1 falha com rollback):
|
|
113
|
+
`trustLevel` saiu 4/5 (80% de sucesso, 1 rollback em 5) — ordena corretamente entre o caso "0
|
|
114
|
+
Observation" (0/5) e o caso "100% sucesso" (5/5), ambos também cobertos nos testes unitários do
|
|
115
|
+
motor puro. Revalidar com dado real assim que este workspace acumular `Observation`s de verdade.
|
|
116
|
+
|
|
117
|
+
**Achado real corrigido durante a implementação (não adiado)**: a primeira execução de
|
|
118
|
+
`agent:score` contra um agente recém-registrado, **zero** `Observation`, devolveu `trustLevel 3/5`
|
|
119
|
+
— um número "neutro" que sugeria confiabilidade moderada sem nenhuma evidência por trás.
|
|
120
|
+
`EvaluationEngine.rate()` devolve `0` (não `undefined`) pra toda métrica quando não há dado, e a
|
|
121
|
+
fórmula original lia `reworkRate`/`rollbackRate`/`assertionsWithoutEvidenceRate` zerados como "bom
|
|
122
|
+
sinal" — 3/5 do nada. Corrigido em `packages/engineering/identity`: `sampleSize === 0` agora força
|
|
123
|
+
`trustLevel: 0` antes mesmo de aplicar a fórmula, com teste unitário e de CLI cobrindo o caso.
|
|
124
|
+
`autonomyLevel` já caía corretamente pra `human_in_the_loop` via AC-3 mesmo antes da correção — só
|
|
125
|
+
o número exibido é que mentia.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Tasks: Agent Identity & Reputation
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — contrato + engine puro (`computeReputationScore`)
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: M
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `packages/contracts/src/index.ts`, `packages/engineering/identity/src/index.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `AgentProfile2` aditivo, `trustLevel`/`autonomyLevel`/`lastScoredAt` opcionais
|
|
17
|
+
- [ ] `computeReputationScore` implementa a fórmula de D1 do plan
|
|
18
|
+
- [ ] amostra abaixo de `minSampleSize` força `autonomyLevel: 'human_in_the_loop'` (AC-3)
|
|
19
|
+
- [ ] testes unitários (sem `fs`/rede): fórmula com dado real vs. sintético, cold start,
|
|
20
|
+
thresholds customizados, `evidenceIds` passthrough do `EvaluationReport.observationIds`
|
|
21
|
+
|
|
22
|
+
## T2 — persistência (`SqliteAgentProfileStore`) + `scripts/agent.ts`
|
|
23
|
+
- **Owner**: worker
|
|
24
|
+
- **Estimativa**: G
|
|
25
|
+
- **Depende de**: T1
|
|
26
|
+
- **Paths**: `packages/adapter-sqlite/src/index.ts`, `scripts/agent.ts`, `lib/core/registry.ts`
|
|
27
|
+
- **Done quando**:
|
|
28
|
+
- [ ] `SqliteAgentProfileStore` reaproveita `SqliteJsonRepository`, sem migration nova (D3)
|
|
29
|
+
- [ ] `agent:register` não tem flag de `trust-level`/`autonomy-level` (D2)
|
|
30
|
+
- [ ] `agent:score` computa e persiste `trustLevel`/`autonomyLevel`/`lastScoredAt`, filtro por
|
|
31
|
+
`--domain` funcional (D4)
|
|
32
|
+
- [ ] `agent:list`/`:show`/`:history` funcionais
|
|
33
|
+
- [ ] `forja tools:doctor` continua verde
|
|
34
|
+
|
|
35
|
+
## T3 — prova sobre dado real/sintético documentado
|
|
36
|
+
- **Owner**: worker
|
|
37
|
+
- **Estimativa**: P
|
|
38
|
+
- **Depende de**: T2
|
|
39
|
+
- **Paths**: `test/agent-cli.test.js` (novo)
|
|
40
|
+
- **Done quando**:
|
|
41
|
+
- [ ] fixture isolada: registrar agente, seed de `Observation`s sintéticas (documentadas como
|
|
42
|
+
tal — sem `Observation` real suficiente neste workspace), `agent:score` produz resultado
|
|
43
|
+
coerente
|
|
44
|
+
- [ ] cold start (sem `Observation`) produz `human_in_the_loop`, não erro
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Handoffs entre agentes
|
|
49
|
+
|
|
50
|
+
T1 → T2 → T3 sequencial. Sem handoff de papel — spec e plan já aprovados cobrem as decisões de
|
|
51
|
+
produto/arquitetura.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Plan: Agent Runtime Monitoring / Behavior Anomaly Engine
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
Novo sub-domínio `packages/engineering/monitoring`, puro: `detectAnomaly(baseline, recent)`
|
|
10
|
+
compara dois `EvaluationReport` (mesma fonte que `computeReputationScore` consome, SPEC-036) fator
|
|
11
|
+
a fator. `scripts/agent.ts` ganha `agent:monitor` (mesmo script de domínio de SPEC-036/037 — não um
|
|
12
|
+
script novo), que busca `Observation`s reais e monta os dois `EvaluationReport` (linha de base =
|
|
13
|
+
tudo antes da janela; recente = últimas N horas), reaproveitando `EvaluationEngine` sem
|
|
14
|
+
reimplementar nenhuma métrica.
|
|
15
|
+
|
|
16
|
+
`packages/policy` ganha `anomalyScoreRange`/`anomalyScore`, campo `number` puro — mesmo padrão
|
|
17
|
+
exato de `riskScoreRange`/`riskScore` (SPEC-034): nenhum import de `packages/engineering/monitoring`.
|
|
18
|
+
|
|
19
|
+
## 2. Módulos afetados
|
|
20
|
+
|
|
21
|
+
| Caminho | Mudança | Risco |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| `packages/engineering/monitoring/src/index.ts` | novo — `detectAnomaly` | Baixo — comparação pura |
|
|
24
|
+
| `scripts/agent.ts` | `agent:monitor` novo subcomando | Baixo |
|
|
25
|
+
| `packages/policy/src/index.ts` | `anomalyScoreRange`/`anomalyScore` (aditivo) | Baixo |
|
|
26
|
+
| `lib/core/registry.ts` | 1 comando novo | Baixo |
|
|
27
|
+
| `test/agent-runtime-monitoring.test.js` (novo) | unit de `detectAnomaly` | — |
|
|
28
|
+
| `test/policy.test.js` | +teste de `anomalyScoreRange` | — |
|
|
29
|
+
| `test/agent-cli.test.js` | +teste de CLI de `agent:monitor` | — |
|
|
30
|
+
|
|
31
|
+
## 3. Contratos
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// packages/engineering/monitoring/src/index.ts
|
|
35
|
+
export interface AnomalySignal { readonly metric: string; readonly baseline: number; readonly recent: number; readonly delta: number; }
|
|
36
|
+
export interface AnomalyAssessment { readonly agentId: string; readonly score: number; readonly confidence: number; readonly signals: readonly AnomalySignal[]; }
|
|
37
|
+
export function detectAnomaly(agentId: string, baseline: EvaluationReport, recent: EvaluationReport, options?: { minSampleSize?: number }): AnomalyAssessment;
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Fórmula (D1): compara `successRate`, `reworkRate`, `rollbackRate` (as 3 métricas de qualidade já
|
|
41
|
+
usadas em `computeReputationScore`, D1 de SPEC-036 — mesmo vocabulário, não um novo). Para cada
|
|
42
|
+
métrica, `delta = recent - baseline` (sinal importa: `successRate` caindo é ruim, `reworkRate`/
|
|
43
|
+
`rollbackRate` subindo é ruim). `score = min(100, round(100 * (max(0, -deltaSuccessRate) * 0.5 +
|
|
44
|
+
max(0, deltaReworkRate) * 0.25 + max(0, deltaRollbackRate) * 0.25)))`. `confidence` = `min(1,
|
|
45
|
+
min(baseline.observationCount, recent.observationCount) / minSampleSize)` (default `minSampleSize:
|
|
46
|
+
5`, mesmo valor default de `DEFAULT_REPUTATION_THRESHOLDS.minSampleSize` em SPEC-036 — consistência
|
|
47
|
+
entre os dois motores de agente).
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
agent:monitor <id> [--window-hours <n>] # default 24
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
// packages/policy/src/index.ts — extensão aditiva
|
|
55
|
+
export interface PolicyScope { /* ...campos existentes... */ readonly anomalyScoreRange?: readonly [number, number]; }
|
|
56
|
+
export interface PolicyRequest { /* ...campos existentes... */ readonly anomalyScore?: number; }
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## 4. Decisões
|
|
60
|
+
|
|
61
|
+
**D1**: fórmula reaproveita as mesmas 3 métricas de `computeReputationScore` (successRate/
|
|
62
|
+
reworkRate/rollbackRate) — vocabulário consistente entre os dois motores de comportamento de
|
|
63
|
+
agente, em vez de inventar um conjunto de métricas diferente pra "anomalia" vs. "reputação".
|
|
64
|
+
|
|
65
|
+
**D2**: `anomalyScoreRange`/`anomalyScore` seguem exatamente o padrão de `riskScoreRange`/
|
|
66
|
+
`riskScore` (mesmo formato `[number, number]`, mesmo `matches()` em `PolicyEngine`, mesmo raciocínio
|
|
67
|
+
de D3 de SPEC-034: campo `number` puro, não o `AnomalyAssessment` inteiro) — consistência de design
|
|
68
|
+
entre os dois scores que `PolicyEngine` pode consultar.
|
|
69
|
+
|
|
70
|
+
## 5. Rollout
|
|
71
|
+
|
|
72
|
+
Sem migração, sem feature flag.
|
|
73
|
+
|
|
74
|
+
## 6. Kill criteria
|
|
75
|
+
|
|
76
|
+
Já coberto pelo mesmo princípio das specs anteriores — se `detectAnomaly` sinalizar anomalia sem
|
|
77
|
+
correspondência a julgamento humano sobre dado real, os pesos de D1 são revisados antes de
|
|
78
|
+
qualquer regra de política real usar `anomalyScoreRange` (§5 do spec, "Fora").
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Spec: Agent Runtime Monitoring / Behavior Anomaly Engine
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-040
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 8 (fecha a Fase 5 da visão original, junto de SPEC-039)
|
|
8
|
+
- **ADRs relacionadas**: ADR-0078; depende de `packages/evals.EvaluationEngine` (reaproveitado),
|
|
9
|
+
`packages/policy` (extensão aditiva, mesmo padrão de SPEC-034 `riskScoreRange`)
|
|
10
|
+
|
|
11
|
+
> Gap analysis original (`docs/architecture/...` §3): "Não existe. `PolicyEngine` já é o lugar
|
|
12
|
+
> certo pra acoplar (política decide, não o LLM) — Construir, mas *dentro* de Policy, não paralelo."
|
|
13
|
+
> Interpretação (mesma resolvida em SPEC-034 D3 pra risco): "dentro de Policy" não significa o
|
|
14
|
+
> cálculo morar em `packages/policy` — significa que a **decisão** continua sendo do
|
|
15
|
+
> `PolicyEngine`/humano, nunca de um motor de anomalia paralelo. O cálculo é um pacote separado
|
|
16
|
+
> (mesmo padrão de `RiskEngine`), e `PolicyRequest` ganha um campo `number` opcional pra consultá-lo
|
|
17
|
+
> — exatamente a forma que `riskScoreRange`/`riskScore` já tomaram em SPEC-034.
|
|
18
|
+
|
|
19
|
+
## 1. Problema
|
|
20
|
+
|
|
21
|
+
Nada compara o comportamento **recente** de um agente contra sua própria linha de base — um agente
|
|
22
|
+
que de repente começa a falhar mais, gastar mais, ou tocar categorias diferentes de arquivo não
|
|
23
|
+
gera nenhum sinal. `EvaluationEngine` já calcula as taxas certas por escopo, mas só olha pra um
|
|
24
|
+
recorte de dado por vez, nunca compara dois recortes (linha de base vs. recente).
|
|
25
|
+
|
|
26
|
+
## 2. Proposta de valor
|
|
27
|
+
|
|
28
|
+
`forja agent:monitor <id> [--window-hours <n>]` compara os `Observation`s recentes de um agente
|
|
29
|
+
contra sua linha de base histórica e reporta um `AnomalyAssessment` com sinais nomeados — nunca um
|
|
30
|
+
alarme sem explicação, mesmo princípio de `RiskEngine`/`AgentReputationScore`.
|
|
31
|
+
|
|
32
|
+
## 3. User stories
|
|
33
|
+
|
|
34
|
+
- **Como** governance, **quero** saber quando o comportamento recente de um agente se desvia do
|
|
35
|
+
histórico dele, **para que** eu investigue antes que o desvio vire um incidente.
|
|
36
|
+
|
|
37
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
38
|
+
|
|
39
|
+
- [x] AC-1: `detectAnomaly` (função pura, `packages/engineering/monitoring`) recebe dois
|
|
40
|
+
`EvaluationReport` (linha de base + recente, ambos já produzidos por `EvaluationEngine`,
|
|
41
|
+
reaproveitado sem reimplementar nenhuma métrica) e devolve `AnomalyAssessment` — `score`
|
|
42
|
+
0-100, `signals[]` nomeados (quais métricas desviaram e por quanto), nunca um score sem
|
|
43
|
+
explicação.
|
|
44
|
+
- [x] AC-2: amostra insuficiente em qualquer um dos dois recortes (linha de base ou recente) marca
|
|
45
|
+
`confidence` baixa explicitamente — fail-closed/honesto, mesmo princípio de
|
|
46
|
+
`AgentReputationScore`/SPEC-036 AC-3, nunca reporta anomalia alta por falta de dado.
|
|
47
|
+
- [x] AC-3: `forja agent:monitor <id> [--window-hours <n>]` (CLI) — linha de base = todo o histórico
|
|
48
|
+
anterior à janela; recente = últimas `n` horas (default configurável). Reaproveita
|
|
49
|
+
`SqliteObservationStore` (já existente).
|
|
50
|
+
- [x] AC-4: `PolicyScope.anomalyScoreRange`/`PolicyRequest.anomalyScore` (extensão aditiva de
|
|
51
|
+
`packages/policy`, mesmo padrão exato de `riskScoreRange`/`riskScore` em SPEC-034) —
|
|
52
|
+
`packages/policy` nunca importa `packages/engineering/monitoring`; quem calcula o score chama
|
|
53
|
+
`detectAnomaly` antes de montar o `PolicyRequest`, exatamente como já acontece com risco.
|
|
54
|
+
- [x] AC-5: nenhuma aplicação automática — `agent:monitor` nunca chama `PolicyEngine`/bloqueia
|
|
55
|
+
nada sozinho; é leitura, mesmo princípio de `RiskEngine` D3.
|
|
56
|
+
|
|
57
|
+
## 5. Escopo
|
|
58
|
+
|
|
59
|
+
**Dentro**: `detectAnomaly` (motor puro); `agent:monitor` (CLI); extensão aditiva de
|
|
60
|
+
`packages/policy` (campo `number`, não motor paralelo).
|
|
61
|
+
|
|
62
|
+
**Fora**: qualquer regra de política real usando `anomalyScoreRange` neste sprint (só a capacidade
|
|
63
|
+
estrutural, mesmo raciocínio de `riskScoreRange` em SPEC-034 — não é este sprint que decide
|
|
64
|
+
*quando* pausar um agente, só habilita que uma regra futura possa); alertas/notificação automática
|
|
65
|
+
(fica pra quando houver um canal real de notificação, fora de escopo desta fundação); detecção via
|
|
66
|
+
ML/estatística avançada (comparação de taxa determinística e documentada é suficiente e verificável
|
|
67
|
+
— mesmo princípio de "determinístico antes de LLM" já estabelecido em toda a fundação).
|
|
68
|
+
|
|
69
|
+
## 6. NFRs / restrições
|
|
70
|
+
|
|
71
|
+
- Determinístico — nenhum LLM/ML em nenhum ponto; fórmula documentada em código e aqui.
|
|
72
|
+
- Fail-closed: amostra insuficiente nunca produz confiança alta (AC-2).
|
|
73
|
+
- Zero migration SQLite nova.
|
|
74
|
+
|
|
75
|
+
## 7. Riscos e mitigação
|
|
76
|
+
|
|
77
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
78
|
+
|---|---|---|---|
|
|
79
|
+
| Anomalia virar bloqueio automático de agente | Baixa (mesmo padrão já seguido em Risk/Reputation) | Alta se acontecesse | AC-5 explícito; nenhuma regra de política usando o campo é criada nesta spec (§5 "Fora") |
|
|
80
|
+
| Falso positivo por baixa amostra em qualquer um dos dois recortes | Média em agentes novos/pouco usados | Média (alarme sem sentido) | AC-2: confidence baixa declarada, não escondida |
|
|
81
|
+
|
|
82
|
+
## 8. Métricas de sucesso
|
|
83
|
+
|
|
84
|
+
Comparar dois recortes sintéticos documentados como tais (um com comportamento estável, outro com
|
|
85
|
+
degradação clara — ex.: `successRate` caindo de 90% pra 30%) e confirmar que `detectAnomaly` sinaliza
|
|
86
|
+
a anomalia com os `signals[]` corretos — revisão humana, mesma metodologia das specs anteriores.
|
|
87
|
+
|
|
88
|
+
**Validado** (`test/agent-cli.test.js`): amostra sintética documentada como tal (10 `Observation`s
|
|
89
|
+
de linha de base com 90% de sucesso, 10 recentes com 30%) — `agent:monitor` reportou o `signal`
|
|
90
|
+
`successRate: 0.90 → 0.30`, score de anomalia > 0, nunca acionou `PolicyEngine`/bloqueio algum. Caso
|
|
91
|
+
de zero `Observation` reporta corretamente score 0 (sem degradação sem dado, não um alarme
|
|
92
|
+
por falta de dado — mesma honestidade de AC-2/`AgentReputationScore`).
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Tasks: Agent Runtime Monitoring / Behavior Anomaly Engine
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — `detectAnomaly` (motor puro) + `PolicyEngine` extensão
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: M
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `packages/engineering/monitoring/src/index.ts`, `packages/policy/src/index.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `detectAnomaly` implementa a fórmula de D1, `confidence` reflete o menor dos dois tamanhos
|
|
17
|
+
de amostra (AC-2)
|
|
18
|
+
- [ ] `PolicyScope.anomalyScoreRange`/`PolicyRequest.anomalyScore` (D2), `packages/policy`
|
|
19
|
+
continua sem importar `packages/engineering/monitoring`
|
|
20
|
+
- [ ] testes unitários: degradação clara sinaliza corretamente; comportamento estável não
|
|
21
|
+
sinaliza; amostra pequena em qualquer um dos dois recortes reduz confidence
|
|
22
|
+
- [ ] testes de `PolicyEngine.matches` com `anomalyScoreRange`
|
|
23
|
+
|
|
24
|
+
## T2 — `agent:monitor` (CLI) + prova
|
|
25
|
+
- **Owner**: worker
|
|
26
|
+
- **Estimativa**: M
|
|
27
|
+
- **Depende de**: T1
|
|
28
|
+
- **Paths**: `scripts/agent.ts`, `lib/core/registry.ts`, `test/agent-cli.test.js`
|
|
29
|
+
- **Done quando**:
|
|
30
|
+
- [ ] `agent:monitor <id> [--window-hours <n>]` busca `Observation`s reais, monta os dois
|
|
31
|
+
`EvaluationReport` (linha de base/recente), chama `detectAnomaly`
|
|
32
|
+
- [ ] teste de CLI com amostra sintética documentada como tal (degradação clara)
|
|
33
|
+
- [ ] `forja tools:doctor` continua verde
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Handoffs entre agentes
|
|
38
|
+
|
|
39
|
+
T1 → T2 sequencial. Sem handoff de papel.
|