forjajs 2.0.3 → 3.0.0

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