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,119 @@
|
|
|
1
|
+
# Spec: Change Risk Engine
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-034
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 2
|
|
8
|
+
- **ADRs relacionadas**: ADR-0078; depende de SPEC-032 (blast radius via grafo) e SPEC-033
|
|
9
|
+
(violação de arquitetura como fator de risco)
|
|
10
|
+
|
|
11
|
+
## 1. Problema
|
|
12
|
+
|
|
13
|
+
Hoje, o único sinal de risco de uma mudança é o `risk: RiskLevel` estático declarado na
|
|
14
|
+
`CapabilityDefinition` (`low|medium|high|critical`) — um valor fixo por capability, não calculado a
|
|
15
|
+
partir da mudança real (quantos arquivos, quantos módulos afetados, se viola arquitetura, se o
|
|
16
|
+
domínio tem histórico de falha). Duas mudanças na mesma capability podem ter risco real muito
|
|
17
|
+
diferente e recebem o mesmo tratamento de política.
|
|
18
|
+
|
|
19
|
+
## 2. Proposta de valor
|
|
20
|
+
|
|
21
|
+
`forja risk:assess "<mudança>"` produz um score 0-100 explicável (fatores nomeados, com evidência),
|
|
22
|
+
que o Policy Engine pode opcionalmente consultar para calibrar a exigência de aprovação além do
|
|
23
|
+
`risk` estático da capability.
|
|
24
|
+
|
|
25
|
+
## 3. User stories
|
|
26
|
+
|
|
27
|
+
- **Como** governance, **quero** um score de risco com fatores visíveis, **para que** eu confie
|
|
28
|
+
na exigência de aprovação em vez de tratá-la como arbitrária.
|
|
29
|
+
- **Como** desenvolvedor, **quero** `risk:explain` mostrando exatamente por que um score saiu alto,
|
|
30
|
+
**para que** eu saiba o que reduzir (mais teste? menos arquivos? revisão de arquitetura?) antes
|
|
31
|
+
de tentar de novo.
|
|
32
|
+
|
|
33
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
34
|
+
|
|
35
|
+
- [x] AC-1: `RiskEngine.assess(input): ChangeRiskAssessment` (interface pura, sem I/O) implementa a
|
|
36
|
+
fórmula documentada em `docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md`
|
|
37
|
+
§9, com os 7 fatores nomeados e pesos default configuráveis.
|
|
38
|
+
- [x] AC-2: cada fator do assessment carrega `evidenceIds` (nós/arestas do grafo, `Observation`s
|
|
39
|
+
históricas) — nenhum score sem rastro de onde veio.
|
|
40
|
+
- [x] AC-3: `confidence` do assessment reflete a fração de fatores com dado real disponível — um
|
|
41
|
+
projeto sem histórico de falha ainda produz um score, mas com confiança visivelmente menor,
|
|
42
|
+
nunca escondida.
|
|
43
|
+
- [x] AC-4: `forja risk:assess [ref]` (CLI, ver D1 do plan — ref de git, não prosa livre) e
|
|
44
|
+
`forja risk:explain <assessment-id>` funcionais.
|
|
45
|
+
- [x] AC-5: interface `RiskAssessor`/`RiskEngine` pequena e opcional — `packages/policy` nunca
|
|
46
|
+
importa `packages/engineering/risk`; `PolicyRequest.riskScore` é um `number` puro (D3 do
|
|
47
|
+
plan), não o assessment inteiro.
|
|
48
|
+
- [x] AC-6: faixas de autonomia (0-25 autonomous / 26-50 autonomous_with_review / 51-75 supervised
|
|
49
|
+
/ 76-100 human_in_the_loop, sugeridas na visão original) são **configuração default**, nunca
|
|
50
|
+
constante fixa no código — mesmo padrão já usado por `RuntimeLimits`/`PolicyLimits`.
|
|
51
|
+
|
|
52
|
+
## 5. Escopo
|
|
53
|
+
|
|
54
|
+
**Dentro**: os 7 fatores documentados em §9 do doc de arquitetura; interface pura `RiskEngine`;
|
|
55
|
+
CLI `risk:assess`/`risk:explain`; interface de consumo opcional pelo Policy Engine.
|
|
56
|
+
|
|
57
|
+
**Fora**: aplicação automática de `REQUIRE_APPROVAL`/`DENY` a partir do score sem uma regra de
|
|
58
|
+
política explícita configurada para isso (o score informa a decisão, não a toma sozinho — decisão
|
|
59
|
+
de política continua sendo do `PolicyEngine`, nunca do `RiskEngine`); UI/heatmap de risco (Fase
|
|
60
|
+
posterior).
|
|
61
|
+
|
|
62
|
+
## 6. NFRs / restrições
|
|
63
|
+
|
|
64
|
+
- Determinístico onde possível; nenhum fator depende de chamada de LLM.
|
|
65
|
+
- `RiskEngine` não tem efeito colateral — é uma função pura sobre dados já coletados em outro
|
|
66
|
+
lugar (grafo, `Observation`, `architecture:check`).
|
|
67
|
+
- Fórmula e pesos vivem em um único lugar documentado (código + este spec) — nunca duplicados.
|
|
68
|
+
|
|
69
|
+
## 7. Riscos e mitigação
|
|
70
|
+
|
|
71
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
72
|
+
|---|---|---|---|
|
|
73
|
+
| Score virar "número mágico" que ninguém entende | Alta se mal implementado | Alta (perde toda a confiança) | AC-2/AC-3 obrigam evidência e confidence em todo assessment, sem exceção |
|
|
74
|
+
| Pesos default não fazerem sentido para todo tipo de projeto | Alta | Média | Pesos configuráveis por projeto desde o dia 1 (AC-1), não hardcoded |
|
|
75
|
+
| Cold start: projeto novo sem `Observation` histórica | Alta em projetos novos | Baixa (é esperado) | `confidence` reduzida é a resposta correta, não um erro ou bloqueio |
|
|
76
|
+
|
|
77
|
+
## 8. Métricas de sucesso
|
|
78
|
+
|
|
79
|
+
Rodar `risk:assess` sobre 5 mudanças históricas reais deste repositório (ex.: a extração do
|
|
80
|
+
`isPathWithinRoot`, a correção do policy approval bypass) produz scores que, em revisão humana,
|
|
81
|
+
ordenam corretamente do menos para o mais arriscado.
|
|
82
|
+
|
|
83
|
+
**Validado**: `risk:assess <ref>` rodado contra 5 commits reais deste repositório (grafo real,
|
|
84
|
+
`.context/architecture/constitution.json` real, sem fixture):
|
|
85
|
+
|
|
86
|
+
| Commit | Descrição | Score |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| `6f220ed` | refatoração: extrai runner de capability sandboxed reutilizável | 7 |
|
|
89
|
+
| `a950711` | fix de segurança pontual (1 arquivo): argument-injection em `code:impact` | 11 |
|
|
90
|
+
| `1a49682` | docs: remove citação de comando ainda não implementado | 13 |
|
|
91
|
+
| `fdab8e3` | feature nova: `drift:check` (SPEC-030) | 13 |
|
|
92
|
+
| `f678d37` | fix de segurança multi-arquivo: auth do proxy do dashboard, DB shutdown handler | 19 |
|
|
93
|
+
|
|
94
|
+
Ordem (revisão humana, apk): o fix de segurança multi-arquivo fica corretamente no topo; a
|
|
95
|
+
refatoração autocontida (menor blast radius, nada ainda depende do novo helper) fica corretamente
|
|
96
|
+
no fundo. Ordem aceita — sem redesenho de pesos necessário (kill criteria do apêndice de
|
|
97
|
+
`specs/engineering-intelligence/spec.md` não disparado).
|
|
98
|
+
|
|
99
|
+
**Achado real (limitação documentada, não corrigida — heurística determinística, não regressão de
|
|
100
|
+
AC)**: `security_sensitivity` não pegou `f678d37` como sensível, apesar de o commit mexer em
|
|
101
|
+
autenticação (`apps/dashboard/app/api/forja/guard.ts`) e desligamento de banco
|
|
102
|
+
(`apps/server/src/main.ts`). A heurística de `scripts/risk.ts` (`inferSensitiveCategories`) casa só
|
|
103
|
+
substring de path (`secret|credential|\.env`, `adapter-sqlite|migration|database`,
|
|
104
|
+
`deploy|\.github/workflows|Dockerfile`) — nenhum desses arquivos tem esses termos no caminho, então
|
|
105
|
+
o fator não disparou. É determinístico (cumpre a NFR de "nenhum fator depende de LLM") mas tem
|
|
106
|
+
recall baixo para segurança que não está em path óbvio. Não corrigido aqui: exigiria uma heurística
|
|
107
|
+
mais rica (ex.: casar contra `PolicyCategory` já inferida do `capabilityId`/handler tocado, não só
|
|
108
|
+
o path do arquivo) — candidato a uma spec própria de refinamento, fora do escopo desta fundação.
|
|
109
|
+
|
|
110
|
+
**Melhoria posterior (não a correção estrutural completa, uma redução da superfície mais óbvia de
|
|
111
|
+
falso-negativo)**: `SENSITIVE_PATTERNS` (`lib/core/risk-collect.ts`, movida de `scripts/risk.ts` no
|
|
112
|
+
Sprint 6) ganhou `auth|guard|session|token` na categoria `secrets` e `shutdown` na categoria
|
|
113
|
+
`database` — termos adjacentes a controle de acesso/ciclo de vida de credencial e conexão que a
|
|
114
|
+
lista original não cobria. Revalidado contra o mesmo `f678d37`: `security_sensitivity` agora
|
|
115
|
+
detecta `secrets, database` (antes: nenhuma), score final `19/100 → 29/100`, banda de autonomia
|
|
116
|
+
`autonomous → autonomous_with_review` — mais correto pro que o commit de fato fez. **A limitação
|
|
117
|
+
estrutural continua real**: qualquer lista fixa de palavras-chave tem recall limitado por natureza;
|
|
118
|
+
a correção estrutural sugerida na nota original (casar contra `PolicyCategory` inferida do
|
|
119
|
+
handler/capability tocado) segue não implementada e fora do escopo desta fundação.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Tasks: Change Risk Engine
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — engine puro: fórmula + confidence + bandas de autonomia
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: G
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `packages/engineering/risk/src/index.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `assessRisk` implementa os 7 fatores com os pesos default de §9 do doc de arquitetura
|
|
17
|
+
(soma 1.0), pesos sobrescrevíveis via `options.weights`
|
|
18
|
+
- [ ] `confidence` = fração de fatores com `hasRealData: true` (AC-3)
|
|
19
|
+
- [ ] `autonomyBand` usa `AutonomyBandThresholds` configurável, default 25/50/75 (AC-6)
|
|
20
|
+
- [ ] cada `RiskFactorResult` carrega `evidenceIds` (passthrough do `RiskInput`, nunca inventado
|
|
21
|
+
pelo engine) — AC-2
|
|
22
|
+
- [ ] testes unitários (sem `fs`/rede): fator sem dado real reduz `confidence` mas não quebra o
|
|
23
|
+
score; pesos customizados mudam o resultado; as 4 bandas de autonomia nos limites exatos
|
|
24
|
+
(25/26/50/51/75/76)
|
|
25
|
+
|
|
26
|
+
## T2 — `scripts/risk.ts`: coleta real + `risk:assess`/`risk:explain`
|
|
27
|
+
- **Owner**: worker
|
|
28
|
+
- **Estimativa**: M
|
|
29
|
+
- **Depende de**: T1
|
|
30
|
+
- **Paths**: `scripts/risk.ts`, `lib/core/registry.ts`
|
|
31
|
+
- **Done quando**:
|
|
32
|
+
- [ ] blast radius via `GraphLoop.impact()` sobre o grafo real (reindexado como
|
|
33
|
+
`adr:*`/`architecture:*` já fazem)
|
|
34
|
+
- [ ] violações de arquitetura via `checkConstitution` sobre `constitution.json` (SPEC-033),
|
|
35
|
+
escopadas aos arquivos alterados
|
|
36
|
+
- [ ] taxa histórica de falha via `SqliteObservationStore.list()` filtrado por `files`
|
|
37
|
+
(cold start = `undefined`, não 0 mentiroso)
|
|
38
|
+
- [ ] `risk:assess [ref]` grava `.context/risk/<id>.json` (D2 do plan) e imprime
|
|
39
|
+
`explainAssessment`
|
|
40
|
+
- [ ] `risk:explain <id>` lê o arquivo de volta
|
|
41
|
+
- [ ] `forja tools:doctor` continua verde (comandos documentados no README)
|
|
42
|
+
|
|
43
|
+
## T3 — integração opcional com Policy Engine
|
|
44
|
+
- **Owner**: worker
|
|
45
|
+
- **Estimativa**: P
|
|
46
|
+
- **Depende de**: T1
|
|
47
|
+
- **Paths**: `packages/policy/src/index.ts`, `test/policy.test.js`
|
|
48
|
+
- **Done quando**:
|
|
49
|
+
- [ ] `PolicyScope.riskScoreRange`/`PolicyRequest.riskScore` (D3 do plan — `number`, não o
|
|
50
|
+
assessment inteiro)
|
|
51
|
+
- [ ] `PolicyEngine.matches()` respeita `riskScoreRange` quando presente, sem quebrar nenhuma
|
|
52
|
+
regra existente que não o declara (campo opcional)
|
|
53
|
+
- [ ] `packages/policy` continua sem importar `packages/engineering/risk` (AC-5, checável por
|
|
54
|
+
`grep -r "engineering-risk\|engineering/risk" packages/policy/src`)
|
|
55
|
+
|
|
56
|
+
## T4 — prova sobre dado real
|
|
57
|
+
- **Owner**: worker
|
|
58
|
+
- **Estimativa**: P
|
|
59
|
+
- **Depende de**: T2
|
|
60
|
+
- **Paths**: `test/risk-cli.test.js` (novo)
|
|
61
|
+
- **Done quando**:
|
|
62
|
+
- [ ] fixture git isolada com 2+ pacotes, uma mudança que toca 1 arquivo: `risk:assess` produz
|
|
63
|
+
score+fatores+confidence coerentes com os dados da fixture (blast radius > 0, sem histórico
|
|
64
|
+
→ `historical_failure_rate.hasRealData === false`)
|
|
65
|
+
- [ ] `risk:explain <id>` recupera o mesmo assessment
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Handoffs entre agentes
|
|
70
|
+
|
|
71
|
+
T1 → (T2, T3 em paralelo, ambas só dependem de T1) → T4. Sem handoff de papel — spec e plan já
|
|
72
|
+
aprovados cobrem as decisões de produto/arquitetura.
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Spec: orçamento de autonomia por custo real (cost-aware autonomy budget)
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-029
|
|
4
|
+
- **Status**: done — AC-1 a AC-6 implementados. Nota de escopo: AC-5 ("por domínio/projeto") foi entregue como custo agregado por MODELO dentro do workspace/DB do projeto (cada projeto já opera seu próprio workspace via `FORJA_WORKSPACE`), não como um campo `projectId` explícito em `Observation` — ver ADR-0077, seção "Alternativas consideradas", para o porquê.
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-08-31
|
|
7
|
+
- **Sprint alvo**: <a definir>
|
|
8
|
+
- **ADRs relacionadas**: ADR-0074 (LLM Fit Loop / adapters de CLI), ADR-0077 (esta spec — orçamento de autonomia por custo real) — este spec estende `PolicyLimits`, que acabou de ganhar enforcement real em `CapabilityRegistry.execute` (auditoria de segurança 2026-08-31)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
`token:economy` **mede e prova** economia de tokens (~40-60% vs. exploração fria), e o LLM Fit Loop já
|
|
13
|
+
roteia entre múltiplos providers por papel/tarefa. Mas nenhum dos dois fala a língua que realmente
|
|
14
|
+
importa pra quem paga a conta: **dinheiro**. Um profile `codex:default` e um `claude:opus` podem gastar
|
|
15
|
+
o mesmo número de tokens e custar ordens de magnitude diferentes. `PolicyLimits` (`maxTokens`,
|
|
16
|
+
`maxFiles`, `maxDurationMs`, `maxRetries`) não tem noção de custo — uma regra de política não consegue
|
|
17
|
+
dizer "esta categoria de trabalho não pode passar de $2 por execução", mesmo que consiga dizer "não
|
|
18
|
+
pode passar de 5000 tokens". Para quem opera múltiplos produtos/clientes ao mesmo tempo (o usuário
|
|
19
|
+
principal do Forja, por definição do próprio README), isso significa descobrir o estouro de custo só
|
|
20
|
+
na fatura do provider — depois do fato, não antes.
|
|
21
|
+
|
|
22
|
+
## 2. Proposta de valor
|
|
23
|
+
|
|
24
|
+
Toda decisão de política pode declarar um teto de custo real em dólares (`maxCostUsd`), aplicado no
|
|
25
|
+
mesmo ponto onde `maxFiles`/`maxTokens` já são aplicados. `token:economy` ganha uma dimensão de custo
|
|
26
|
+
real (`cost:economy`), calculada a partir de uma tabela de preço por provider — local, versionada no
|
|
27
|
+
repo, sem chamada de rede. **"Economia de tokens" vira "economia de custo"**, mensurável e limitável.
|
|
28
|
+
|
|
29
|
+
## 3. User stories
|
|
30
|
+
|
|
31
|
+
- **Como** consultor rodando produtos de múltiplos clientes ao mesmo tempo, **quero** definir um teto
|
|
32
|
+
de gasto por sprint ou por categoria de risco, **para que** um agente autônomo não estoure orçamento
|
|
33
|
+
usando um provider caro sem eu perceber até tarde.
|
|
34
|
+
- **Como** dono de um projeto pequeno, **quero** ver quanto cada sprint custou de verdade (não só em
|
|
35
|
+
tokens), **para que** eu decida racionalmente qual provider vale o custo pra qual tipo de tarefa.
|
|
36
|
+
- **Como** governance, **quero** que uma execução seja bloqueada (não só logada) quando ultrapassa o
|
|
37
|
+
teto de custo, **para que** o limite seja um freio real, não uma métrica de retrovisor.
|
|
38
|
+
|
|
39
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
40
|
+
|
|
41
|
+
- [x] AC-1: `PolicyLimits` ganha `maxCostUsd?: number`; uma regra `ALLOW_WITH_LIMITS` pode declará-lo.
|
|
42
|
+
`packages/policy/src/index.ts`.
|
|
43
|
+
- [x] AC-2: `CapabilityRegistry.execute` (função `checkLimits`, já existente) recusa a chamada com
|
|
44
|
+
`POLICY_LIMIT_EXCEEDED` quando o custo projetado da execução ultrapassa `maxCostUsd` — mesmo
|
|
45
|
+
padrão hoje usado para `maxFiles`/`maxTokens`. `packages/core/src/index.ts` (`CapabilityExecutionRequest.estimatedCostUsd`,
|
|
46
|
+
calculado pelo chamador — ver ADR-0077).
|
|
47
|
+
- [x] AC-3: existe uma tabela de preço por provider/modelo (`$/1K tokens` input e output, separados),
|
|
48
|
+
versionada em arquivo próprio (`lib/core/model-pricing.json`), carregada localmente — sem
|
|
49
|
+
rede. Loader/validador em `lib/core/model-pricing.ts`.
|
|
50
|
+
- [x] AC-4: quando o provider/modelo de uma execução não está na tabela de preço, a execução **não é
|
|
51
|
+
bloqueada** (fail-open para o enforcement de custo especificamente — divergente do resto do
|
|
52
|
+
framework, e por isso citado explicitamente aqui): ela prossegue e um aviso é registrado
|
|
53
|
+
(`llm:doctor` e o próprio `llm:run` avisam em stderr) pedindo para a tabela ser atualizada. Preço
|
|
54
|
+
desconhecido não vira bloqueio de trabalho legítimo. `llm:doctor` também sinaliza preço `stale`
|
|
55
|
+
(> 90 dias sem revisão).
|
|
56
|
+
- [x] AC-5: `cost:economy` — comando novo (não seção em `token:economy`; ver ADR-0077 para o porquê) —
|
|
57
|
+
reporta custo real acumulado por modelo a partir das observações reais do workspace/projeto
|
|
58
|
+
atual. Narrowing: agregação é por modelo dentro do workspace do projeto, não por um campo
|
|
59
|
+
`projectId` explícito em `Observation` (o workspace já é o limite de projeto — ver ADR-0077).
|
|
60
|
+
- [x] AC-6: `Observation.cost` passa a ser populado com o custo real calculado por `forja llm:run`
|
|
61
|
+
quando o preço é conhecido (permanece `0`, como antes desta spec, quando o preço é desconhecido —
|
|
62
|
+
o aviso descrito no AC-4 cobre esse caso).
|
|
63
|
+
|
|
64
|
+
## 5. Escopo
|
|
65
|
+
|
|
66
|
+
**Dentro**:
|
|
67
|
+
- Extensão de `PolicyLimits`/`PolicyDecision.limits` com `maxCostUsd`.
|
|
68
|
+
- Enforcement em `CapabilityRegistry.checkLimits`.
|
|
69
|
+
- Tabela de preço local, estática, versionada.
|
|
70
|
+
- Cálculo de custo real a partir de tokens de entrada/saída já capturados em `Observation`.
|
|
71
|
+
- Relatório de custo no CLI (`token:economy` estendido ou `cost:economy` novo).
|
|
72
|
+
|
|
73
|
+
**Fora** (explícito, evita scope creep):
|
|
74
|
+
- Integração com billing/API de faturamento real dos providers (Anthropic, OpenAI, etc.) — a tabela é
|
|
75
|
+
estática e mantida manualmente/por PR, não sincronizada automaticamente.
|
|
76
|
+
- Orçamento preditivo ("quanto vai custar antes de rodar") — este spec é sobre limitar e reportar
|
|
77
|
+
custo real medido, não estimar custo futuro.
|
|
78
|
+
- Alertas proativos (Slack, e-mail) — fica para uma spec de notificação, se algum dia existir.
|
|
79
|
+
|
|
80
|
+
## 6. NFRs / restrições
|
|
81
|
+
|
|
82
|
+
- **Local-first**: nenhuma chamada de rede para obter preço — a tabela vive no repo.
|
|
83
|
+
- **Fail-open por design em um ponto específico**: preço desconhecido não bloqueia (ver AC-4) — é a
|
|
84
|
+
única exceção deliberada ao princípio "autonomia supervisionada por padrão"; deve ficar documentada
|
|
85
|
+
como tal na ADR que resultar deste spec, para não ser lida como inconsistência.
|
|
86
|
+
- **Compatibilidade**: `maxCostUsd` é opcional em todo lugar — regras de política existentes sem esse
|
|
87
|
+
campo continuam funcionando exatamente como hoje.
|
|
88
|
+
|
|
89
|
+
## 7. Riscos e mitigação
|
|
90
|
+
|
|
91
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
92
|
+
|---|---|---|---|
|
|
93
|
+
| Tabela de preço desatualizada (provider muda preço) | Alta (preços de LLM mudam com frequência) | Média — custo reportado fica impreciso, não custo real cobrado | Preço tem campo `asOf` (data); `llm:doctor` avisa quando `asOf` está velho demais (ex. > 90 dias) |
|
|
94
|
+
| Confundir "custo estimado" com "custo real cobrado" | Média | Média — decisão de negócio baseada em número errado | Nomear explicitamente nos relatórios ("estimativa baseada em tabela local, não fatura") |
|
|
95
|
+
| Escopo crescer para virar um mini sistema de billing | Média | Alta (vira outro projeto) | Este spec para deliberadamente no cálculo local — qualquer integração com billing real vira spec própria |
|
|
96
|
+
|
|
97
|
+
## 8. Métricas de sucesso
|
|
98
|
+
|
|
99
|
+
30 dias após o release: um usuário consegue responder "quanto cada projeto/sprint custou de verdade
|
|
100
|
+
em dólares" sem sair do Forja e sem abrir o painel de billing de nenhum provider — e pelo menos uma
|
|
101
|
+
execução real foi bloqueada (ou teria sido, em modo relatório) por estourar `maxCostUsd` antes de gerar
|
|
102
|
+
uma surpresa na fatura.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Spec: Drift Sentinel — verificação contínua de que o verificado continua verdade
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-030
|
|
4
|
+
- **Status**: implementing
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-08-31
|
|
7
|
+
- **Sprint alvo**: <a definir>
|
|
8
|
+
- **Implementação**: `lib/drift-sentinel.ts` (motor), `scripts/drift-check.ts` (CLI, `forja drift:check
|
|
9
|
+
[--domain <d>]`), `lib/core/drift-gate.ts` + `lib/core/gates.ts`/`scripts/gates.ts`
|
|
10
|
+
(`check:all --with-drift`, AC-5). AC-1 a AC-4 completos, com testes em
|
|
11
|
+
`test/drift-sentinel.test.js`. AC-5 implementado com escopo reduzido: em vez de restruturar
|
|
12
|
+
`runGates`/`CHECKS` para rodar `drift:check` in-process, o gate opt-in chama o comando real via
|
|
13
|
+
subprocess (mesmo padrão de `lib/core/release.ts`/`project-smoke.ts`) e traduz o resultado —
|
|
14
|
+
mantém `check:all` desacoplado do wiring do grafo (SQLite/git) sem tocar o contrato do runner de
|
|
15
|
+
checks. Não marcado `done` porque a métrica de sucesso do §8 (drift genuíno encontrado em projeto
|
|
16
|
+
real, confirmado por humano, 30 dias após o release) ainda não foi observada — só dogfooding
|
|
17
|
+
local contra o próprio monorepo, que não achou drift real algum ainda.
|
|
18
|
+
- **ADRs relacionadas**: nenhuma ainda — nasce da auditoria de segurança de 2026-08-31, que corrigiu
|
|
19
|
+
`packages/graph` para que `status: 'verified'` só venha de fontes de evidência confiáveis
|
|
20
|
+
(`deterministic-extractor`, `sandbox.*`). Este spec é a continuação natural: **verified é um
|
|
21
|
+
instantâneo, não uma garantia permanente.**
|
|
22
|
+
|
|
23
|
+
## 1. Problema
|
|
24
|
+
|
|
25
|
+
O GraphLoop agora distingue de verdade `verified` de `inferred`/`hypothesis` (a auditoria fechou o
|
|
26
|
+
buraco onde qualquer chamador podia se autodeclarar "verificado"). Mas isso resolve só metade do
|
|
27
|
+
problema: **um nó ou aresta `verified` continua marcado `verified` para sempre**, mesmo que o código
|
|
28
|
+
que o originou tenha mudado depois. `GraphIndexer.sync` já é idempotente por checksum de fonte
|
|
29
|
+
(`apply()` pula quando `sourceChecksum` não mudou) — ou seja, **o mecanismo para detectar "isso
|
|
30
|
+
mudou" já existe**. O que falta é: quando um documento muda, nada hoje sinaliza que as
|
|
31
|
+
arestas/evidências antigas derivadas dele podem estar obsoletas até a próxima reindexação, e nada
|
|
32
|
+
compara a nova extração contra a ADR/spec que descrevia o estado anterior. Uma ADR pode descrever uma
|
|
33
|
+
decisão que o código não implementa mais há três sprints, e nada no Forja aponta a divergência — ela
|
|
34
|
+
só aparece quando um humano tropeça nela.
|
|
35
|
+
|
|
36
|
+
## 2. Proposta de valor
|
|
37
|
+
|
|
38
|
+
Um novo comando, `forja drift:check`, reindexa (via `GraphIndexer.sync`, já existente) e classifica
|
|
39
|
+
cada documento em três estados: **inalterado**, **mudou e a extração continua consistente com as
|
|
40
|
+
relações registradas**, ou **mudou e uma relação antes `verified` não é mais reproduzível a partir do
|
|
41
|
+
conteúdo atual** — este último caso é o "drift" que importa: uma ADR, um `DEPENDS_ON`, um `IMPLEMENTS`
|
|
42
|
+
que já foi verdade e hoje não é mais, sem que nada tenha formalmente revogado essa relação.
|
|
43
|
+
|
|
44
|
+
## 3. User stories
|
|
45
|
+
|
|
46
|
+
- **Como** sdd-architect, **quero** saber quando uma ADR descreve algo que o código não faz mais,
|
|
47
|
+
**para que** eu não continue arquitetando em cima de uma premissa que já morreu.
|
|
48
|
+
- **Como** governance, **quero** um relatório de "quantos documentos divergiram desde a última
|
|
49
|
+
verificação", **para que** drift vire um item de rotina (tipo `gsd:check`), não uma surpresa.
|
|
50
|
+
- **Como** consultor com dezenas de projetos gerados pelo Forja, **quero** rodar `drift:check` em lote
|
|
51
|
+
antes de retomar um projeto que não toco há meses, **para que** eu recupere contexto real em vez de
|
|
52
|
+
confiar cegamente em specs/ADRs antigas.
|
|
53
|
+
|
|
54
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
55
|
+
|
|
56
|
+
- [x] AC-1: `forja drift:check [--domain <d>]` roda `GraphIndexer.sync` e, para cada `GraphMutation`
|
|
57
|
+
cujo `sourceChecksum` mudou desde a última indexação, compara as arestas que o documento
|
|
58
|
+
produzia **antes** com as que produz **agora**. *(`checkDrift` em `lib/drift-sentinel.ts`
|
|
59
|
+
reimplementa o laço de `GraphIndexer.sync` — mesma extração + `GraphLoop.apply` — em vez de
|
|
60
|
+
chamá-lo por dentro, porque `sync()` não expõe o "antes" por documento; nenhum dos dois ganhou
|
|
61
|
+
contrato novo, como o §5 já antecipava.)*
|
|
62
|
+
- [x] AC-2: uma aresta que existia com `status: 'verified'` e não é mais produzida pela extração atual
|
|
63
|
+
do mesmo `sourceKey` é marcada `stale` (reaproveitando `validTo` — GraphLoop já suporta validade
|
|
64
|
+
temporal — em vez de inventar um estado novo em `KnowledgeStatus`, que é um contrato versionado
|
|
65
|
+
e não deve crescer sem necessidade real). *(A proveniência "quais arestas este sourceKey
|
|
66
|
+
produziu" também não ganhou campo novo em `GraphEdge` — é derivada do `locator` da evidência,
|
|
67
|
+
`${sourceKey}:${line}`, que `extractDeterministicRelations` já grava.)*
|
|
68
|
+
- [x] AC-3: o comando imprime um relatório: N documentos verificados, M sem mudança, K com drift
|
|
69
|
+
detectado (lista de `sourceKey` + quais relações ficaram `stale`).
|
|
70
|
+
- [x] AC-4: `drift:check` é determinístico e não usa LLM — é extração + diff, igual ao
|
|
71
|
+
`extractDeterministicRelations` que já existe. Nenhuma dependência nova de rede ou modelo.
|
|
72
|
+
- [x] AC-5: `gsd:check`/`check:all` ganham um modo opcional (`--with-drift`, não obrigatório por
|
|
73
|
+
padrão) que inclui `drift:check` na bateria — opcional porque rodar em todo commit seria caro
|
|
74
|
+
demais para repos grandes; ver NFRs. *(Escopo reduzido — ver `Implementação` no cabeçalho: gate
|
|
75
|
+
via subprocess, não integração in-process em `runGates`.)*
|
|
76
|
+
|
|
77
|
+
## 5. Escopo
|
|
78
|
+
|
|
79
|
+
**Dentro**:
|
|
80
|
+
- Comando `drift:check`, reaproveitando `GraphIndexer`/`GraphLoop`/`extractDeterministicRelations`
|
|
81
|
+
como estão (nenhuma mudança de contrato nesses três é necessária além de expor o "antes vs. depois"
|
|
82
|
+
que `apply()` já computa internamente e hoje descarta).
|
|
83
|
+
- Marcação de arestas obsoletas via `validTo` (mecanismo já existente).
|
|
84
|
+
- Relatório CLI.
|
|
85
|
+
|
|
86
|
+
**Fora** (explícito, evita scope creep):
|
|
87
|
+
- **Corrigir automaticamente** o código ou a ADR — o comando só sinaliza; decidir qual lado (código ou
|
|
88
|
+
documento) está desatualizado é julgamento humano ou de agente, não deste comando.
|
|
89
|
+
- Rodar em CI/pre-commit por padrão — fica opt-in (ver AC-5) até haver medição de custo em repos
|
|
90
|
+
grandes.
|
|
91
|
+
- Drift semântico ("a ADR ainda é logicamente verdadeira mas o código foi refatorado") — este spec
|
|
92
|
+
cobre só drift **estrutural**, detectável pelo mesmo extrator determinístico que já indexa o grafo.
|
|
93
|
+
|
|
94
|
+
## 6. NFRs / restrições
|
|
95
|
+
|
|
96
|
+
- **Performance**: `drift:check` não pode ser mais caro que rodar `code:index` duas vezes (é
|
|
97
|
+
essencialmente isso) — sem chamada de LLM, custo é I/O + regex, já provado barato pelo indexador
|
|
98
|
+
existente.
|
|
99
|
+
- **Falso positivo em refactors cosméticos**: renomear uma variável sem mudar a relação semântica não
|
|
100
|
+
deve gerar drift — mitigado porque o extrator já trabalha por relação (`DEPENDS_ON`, `CALLS`,
|
|
101
|
+
`IMPLEMENTS`...), não por hash de linha inteira; um rename que preserva a relação preserva a aresta.
|
|
102
|
+
- **Determinismo antes de LLM** (princípio já declarado na visão do Forja 2.0): este comando não
|
|
103
|
+
introduz nenhuma dependência de modelo.
|
|
104
|
+
|
|
105
|
+
## 7. Riscos e mitigação
|
|
106
|
+
|
|
107
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
108
|
+
|---|---|---|---|
|
|
109
|
+
| Ruído: muito drift cosmético reportado, comando vira "grito de lobo" | Média | Alta (ninguém mais lê o relatório) | Escopo restrito a relações semânticas, não hash de conteúdo bruto (ver NFR acima); medir taxa de falso positivo no dogfooding antes do GO |
|
|
110
|
+
| Confundir `stale` com `contradicted` (que já existe e significa outra coisa — conflito ativo) | Baixa | Média | AC-2 usa `validTo`, não reaproveita `contradicted`; documentar a diferença explicitamente no plan |
|
|
111
|
+
| Escopo crescer para "corrigir automaticamente" | Média | Alta (autonomia não supervisionada mexendo em ADR) | Fora de escopo explícito (§5); qualquer autocorreção é uma spec futura, com gate de aprovação próprio |
|
|
112
|
+
|
|
113
|
+
## 8. Métricas de sucesso
|
|
114
|
+
|
|
115
|
+
30 dias após o release: rodar `drift:check` num projeto real e ativo (não um fixture) resulta em pelo
|
|
116
|
+
menos um drift genuíno encontrado que um humano confirma como real (não falso positivo) — provando que
|
|
117
|
+
o sinal vale o custo de rodar.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Plan: `forja engineer` — compor recomendação de agente + incidentes parecidos
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
`rankIncidentsByQuery`/`incidentRecords`/`titleOf` (hoje locais a `scripts/incident.ts`) mudam pra
|
|
10
|
+
`lib/core/incident-search.ts` — **não** ficam exportadas de `scripts/incident.ts` (revisado durante
|
|
11
|
+
a implementação, D3): um script tem `main()` executado incondicionalmente ao ser importado (mesmo
|
|
12
|
+
padrão de todo `scripts/*.ts` deste repositório), então `scripts/engineer.ts` importando de
|
|
13
|
+
`scripts/incident.ts` rodaria o `main()` de `incident.ts` como efeito colateral, processando o
|
|
14
|
+
`argv` de `engineer` como se fosse de `incident`. `lib/core/risk-collect.ts` já resolveu exatamente
|
|
15
|
+
esse problema pra `risk`/`engineer`/`simulate` — mesma solução aqui. `scripts/incident.ts` passa a
|
|
16
|
+
*importar* de `lib/core/incident-search.ts`, não a exportar pra ele.
|
|
17
|
+
|
|
18
|
+
`scripts/engineer.ts` importa as três funções + `recommendAgent`/`SqliteAgentProfileStore` (já
|
|
19
|
+
usados em `scripts/agent.ts`, agora também aqui) e adiciona duas seções ao `EngineerReport`.
|
|
20
|
+
|
|
21
|
+
## 2. Módulos afetados
|
|
22
|
+
|
|
23
|
+
| Caminho | Mudança | Risco |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| `lib/core/incident-search.ts` (novo) | `rankIncidentsByQuery`/`incidentRecords`/`titleOf`, extraídas de `scripts/incident.ts` | Baixo — mesmo padrão já usado por `risk-collect.ts` |
|
|
26
|
+
| `scripts/incident.ts` | passa a importar de `lib/core/incident-search.ts` em vez de definir localmente — comportamento idêntico (refactor puro) | Baixo |
|
|
27
|
+
| `scripts/engineer.ts` | `--role <role>` novo flag; 2 seções novas no relatório | Baixo — só composição |
|
|
28
|
+
| `test/incident-cli.test.js` | nenhuma mudança esperada (comportamento de `incident:similar` idêntico) | — |
|
|
29
|
+
| `test/engineer-cli.test.js` | +testes das 2 seções novas | — |
|
|
30
|
+
|
|
31
|
+
## 3. Contratos
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// lib/core/incident-search.ts
|
|
35
|
+
export interface RankedIncident { readonly record: GraphNode; readonly relevance: number; }
|
|
36
|
+
export function rankIncidentsByQuery(records: readonly GraphNode[], query: string): readonly RankedIncident[];
|
|
37
|
+
export function incidentRecords(store: SqliteGraphStore): readonly GraphNode[];
|
|
38
|
+
export function titleOf(node: GraphNode): string;
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
engineer "<objetivo>" [--ref <ref>] [--role <role>] [--json]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`EngineerReport` ganha:
|
|
46
|
+
```ts
|
|
47
|
+
readonly recommendedAgents?: readonly { readonly agentId: string; readonly score: number; readonly reasons: readonly string[] }[]; // só com --role
|
|
48
|
+
readonly similarIncidents: readonly { readonly id: string; readonly title: string; readonly relevance: number }[]; // sempre presente, [] se vazio
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## 4. Decisões
|
|
52
|
+
|
|
53
|
+
**D1**: seção de incidentes usa o **objetivo inteiro** como busca (mesmo texto livre já usado por
|
|
54
|
+
`ContextEngine.build`/`GraphLoop.contextRecords` na mesma função) — não um `--query` separado, pra
|
|
55
|
+
não multiplicar flags sem necessidade real; o objetivo já É a busca mais natural.
|
|
56
|
+
|
|
57
|
+
**D2**: `rankIncidentsByQuery` extraída sem alterar `incident:similar` de comportamento — mesmo
|
|
58
|
+
teste de CLI (`test/incident-cli.test.js`) continua valendo como prova de regressão do refactor.
|
|
59
|
+
|
|
60
|
+
**D3** (revisada durante a implementação): a extração vai pra `lib/core/incident-search.ts`, não
|
|
61
|
+
fica exportada de `scripts/incident.ts` como a primeira versão deste plan previa — ver §1, motivo
|
|
62
|
+
completo é o mesmo já documentado no cabeçalho do próprio arquivo novo.
|
|
63
|
+
|
|
64
|
+
## 5. Rollout
|
|
65
|
+
|
|
66
|
+
Sem migração, sem feature flag.
|
|
67
|
+
|
|
68
|
+
## 6. Kill criteria
|
|
69
|
+
|
|
70
|
+
Já coberto pelo princípio geral — se as duas seções novas não ajudarem na prática (§8), removê-las
|
|
71
|
+
é mais barato que mantê-las: nenhuma outra spec depende delas.
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Spec: `forja engineer` — compor recomendação de agente + incidentes parecidos
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-042
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 10 (extensão de composição — todos os Sprints 4-9 da Fase 3-6 já entregam
|
|
8
|
+
sinais que `forja engineer`, de SPEC-035/Sprint 3, ainda não compõe)
|
|
9
|
+
- **ADRs relacionadas**: ADR-0078; depende de SPEC-035 (`forja engineer`), SPEC-037
|
|
10
|
+
(`recommendAgent`), SPEC-041 (`incident:similar`) — todos reaproveitados sem mudança
|
|
11
|
+
|
|
12
|
+
> `forja engineer` (SPEC-035) foi implementada no Sprint 3, antes de `recommendAgent` (SPEC-037,
|
|
13
|
+
> Sprint 5) e `incident:similar` (SPEC-041, Sprint 9) existirem. AC-2 de SPEC-035 já definia a
|
|
14
|
+
> façade como composição extensível ("nenhuma lógica de negócio nova... qualquer decisão real
|
|
15
|
+
> continua nos engines que ela chama") — esta spec é literalmente isso: compor dois sinais que já
|
|
16
|
+
> existem e que a proposta de valor original de `forja engineer` (SPEC-031 §2: "uma única pergunta
|
|
17
|
+
> que já traga arquitetura, risco, ADRs relevantes e fluxo recomendado") já pedia implicitamente,
|
|
18
|
+
> mas que não existiam ainda no Sprint 3.
|
|
19
|
+
|
|
20
|
+
## 1. Problema
|
|
21
|
+
|
|
22
|
+
`forja engineer "<objetivo>"` já compõe contexto, ADRs relevantes, `architecture:check` e risco —
|
|
23
|
+
mas não sugere qual agente registrado é mais adequado pro objetivo, nem mostra incidentes passados
|
|
24
|
+
parecidos, mesmo essas duas capacidades já existindo (`agent:recommend`, `incident:similar`) e
|
|
25
|
+
sendo exatamente o tipo de sinal que orienta o início de um trabalho.
|
|
26
|
+
|
|
27
|
+
## 2. Proposta de valor
|
|
28
|
+
|
|
29
|
+
`forja engineer "<objetivo>" [--role <role>]` passa a incluir, quando aplicável: ranking de agentes
|
|
30
|
+
registrados adequados ao `--role` informado (reaproveita `recommendAgent`, SPEC-037), e incidentes
|
|
31
|
+
passados parecidos com o objetivo (reaproveita a busca por palavra-chave de `incident:similar`,
|
|
32
|
+
SPEC-041) — sem nenhuma lógica nova, só mais composição, exatamente como AC-4 de SPEC-035 já exigia.
|
|
33
|
+
|
|
34
|
+
## 3. User stories
|
|
35
|
+
|
|
36
|
+
- **Como** desenvolvedor/orquestrador, **quero** que `forja engineer` já sugira quem trabalhar e o
|
|
37
|
+
que já aconteceu de parecido, **para que** eu não precise rodar `agent:recommend`/
|
|
38
|
+
`incident:similar` manualmente depois de já ter rodado `engineer`.
|
|
39
|
+
|
|
40
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
41
|
+
|
|
42
|
+
- [x] AC-1: `forja engineer "<objetivo>" --role <role>` inclui uma seção de agentes recomendados
|
|
43
|
+
(reaproveita `recommendAgent`, SPEC-037, sem reimplementar a fórmula de scoring). Sem
|
|
44
|
+
`--role`, a seção não aparece — nunca inventa um papel que o usuário não informou.
|
|
45
|
+
- [x] AC-2: `forja engineer "<objetivo>"` sempre inclui uma seção de incidentes parecidos
|
|
46
|
+
(reaproveita o matching por palavra-chave de `incident:similar`, SPEC-041, exportado do
|
|
47
|
+
mesmo módulo — sem duplicar a lógica de scoring). Vazio quando não há incidente parecido, não
|
|
48
|
+
erro.
|
|
49
|
+
- [x] AC-3: nenhuma lógica nova além de composição/formatação (mesmo princípio de AC-4 de
|
|
50
|
+
SPEC-035) — `recommendAgent`/o matching de incidentes continuam sendo a única fonte de
|
|
51
|
+
verdade de cada score.
|
|
52
|
+
- [x] AC-4: `--json` inclui as duas seções novas estruturadas; texto legível mostra as duas.
|
|
53
|
+
|
|
54
|
+
## 5. Escopo
|
|
55
|
+
|
|
56
|
+
**Dentro**: extensão aditiva de `scripts/engineer.ts` + mover o matching de incidentes de
|
|
57
|
+
`scripts/incident.ts` pra `lib/core/incident-search.ts` (mesmo padrão de `risk-collect.ts`) pra
|
|
58
|
+
reaproveitamento sem duplicar.
|
|
59
|
+
|
|
60
|
+
**Fora**: incluir `detectAnomaly` (SPEC-040) na composição — não se encaixa na mesma pergunta
|
|
61
|
+
("por onde eu começo") que `forja engineer` responde; anomalia é sobre comportamento contínuo de UM
|
|
62
|
+
agente já em operação, não sobre iniciar um objetivo novo (nota já registrada em ADR-0079). Fica de
|
|
63
|
+
fora por não ser a mesma pergunta, não por limitação técnica.
|
|
64
|
+
|
|
65
|
+
## 6. NFRs / restrições
|
|
66
|
+
|
|
67
|
+
- Zero lógica de scoring nova — só import + composição.
|
|
68
|
+
- Zero migration/persistência nova.
|
|
69
|
+
|
|
70
|
+
## 7. Riscos e mitigação
|
|
71
|
+
|
|
72
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
73
|
+
|---|---|---|---|
|
|
74
|
+
| `forja engineer` virar um monólito de composição frágil (toda spec futura quer adicionar uma seção) | Média a longo prazo | Baixa agora (só mais 2 seções) | Mesmo padrão de AC-4/AC-3 de SPEC-035 continua valendo — cada seção nova precisa ser genuinamente "por onde eu começo", não qualquer sinal disponível (ver §5 "Fora" sobre anomalia) |
|
|
75
|
+
|
|
76
|
+
## 8. Métricas de sucesso
|
|
77
|
+
|
|
78
|
+
Rodar `forja engineer` com `--role` sobre os agentes já registrados nos testes de SPEC-037, e sobre
|
|
79
|
+
os incidentes já registrados nos testes de SPEC-041 (reaproveitados como fixture), e confirmar que
|
|
80
|
+
as duas seções aparecem corretamente — revisão humana, mesma metodologia das specs anteriores.
|
|
81
|
+
|
|
82
|
+
**Validado** (`test/engineer-cli.test.js`): agente + incidente reais de fixtures das specs
|
|
83
|
+
anteriores; `engineer --role developer` mostrou a recomendação certa; `engineer "npm hangs..."`
|
|
84
|
+
achou o incidente correspondente e ignorou o não relacionado; sem `--role`, a seção de agentes
|
|
85
|
+
corretamente não aparece; sem nenhum incidente registrado, seção vazia sem erro.
|
|
86
|
+
|
|
87
|
+
**Achados reais corrigidos durante a implementação (não adiados)**:
|
|
88
|
+
|
|
89
|
+
1. **Importar de `scripts/incident.ts` executaria seu `main()` como efeito colateral** (todo
|
|
90
|
+
`scripts/*.ts` roda incondicionalmente ao ser importado, mesmo padrão que motivou
|
|
91
|
+
`lib/core/risk-collect.ts` em SPEC-034/038) — capturado no design antes de qualquer código ser
|
|
92
|
+
escrito, corrigido movendo `rankIncidentsByQuery`/`incidentRecords`/`titleOf` pra
|
|
93
|
+
`lib/core/incident-search.ts` (D3 do plan, revisão de D1/D2 originais).
|
|
94
|
+
2. **Bug de parsing de argumentos**: a primeira versão do parser de `--role` computava
|
|
95
|
+
`roleIndex + 1` incondicionalmente (0 quando `roleIndex === -1`), engolindo o próprio objetivo
|
|
96
|
+
sempre que `--role` não era passado — reproduzido imediatamente ao testar manualmente
|
|
97
|
+
(`forja engineer "<objetivo>"` sem flags devolvia "Uso: ..."). Corrigido: cada índice só entra
|
|
98
|
+
no conjunto de "consumidos" quando a flag correspondente foi de fato encontrada.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Tasks: `forja engineer` — compor recomendação de agente + incidentes parecidos
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — extrair matching de incidentes + compor em `forja engineer`
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: M
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `scripts/incident.ts`, `scripts/engineer.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `rankIncidentsByQuery`/`incidentRecords` exportados, `incident:similar` inalterado em
|
|
17
|
+
comportamento (testes existentes continuam verdes)
|
|
18
|
+
- [ ] `forja engineer --role <role>` inclui agentes recomendados; sem `--role`, seção ausente
|
|
19
|
+
- [ ] `forja engineer` sempre inclui incidentes parecidos (vazio, não erro, se nenhum)
|
|
20
|
+
- [ ] `--json` estrutura as duas seções
|
|
21
|
+
|
|
22
|
+
## T2 — prova
|
|
23
|
+
- **Owner**: worker
|
|
24
|
+
- **Estimativa**: P
|
|
25
|
+
- **Depende de**: T1
|
|
26
|
+
- **Paths**: `test/engineer-cli.test.js`, `test/incident-cli.test.js` (verificação de não-regressão)
|
|
27
|
+
- **Done quando**:
|
|
28
|
+
- [ ] teste com agente registrado + `--role` mostra a recomendação certa
|
|
29
|
+
- [ ] teste com incidente registrado que casa com o objetivo aparece na seção
|
|
30
|
+
- [ ] `test/incident-cli.test.js` continua 100% verde (prova do refactor D2)
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Handoffs entre agentes
|
|
35
|
+
|
|
36
|
+
T1 → T2 sequencial. Sem handoff de papel.
|