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,71 @@
|
|
|
1
|
+
# Plan: AI Code Provenance + AI-SBOM
|
|
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/provenance` (autorizado por ADR-0078), puro: só
|
|
10
|
+
`extractProvenance(run)`, mapeamento de `RuntimeRun.changedFiles` para `ProvenanceRecord[]`.
|
|
11
|
+
Persistência via `SqliteProvenanceStore` (reaproveita `SqliteJsonRepository`, mesmo padrão zero-
|
|
12
|
+
migration de `SqliteAgentProfileStore`/`SqliteRuntimeRunStore`). `scripts/provenance.ts` é o
|
|
13
|
+
adapter: `provenance:record <run-id>` (lê o `RuntimeRun` via `SqliteRuntimeRunStore.get`, já
|
|
14
|
+
existente), `blame <file>`, `sbom`.
|
|
15
|
+
|
|
16
|
+
## 2. Módulos afetados
|
|
17
|
+
|
|
18
|
+
| Caminho | Mudança | Risco |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `packages/engineering/provenance/src/index.ts` | novo — `extractProvenance` | Baixo — mapeamento puro |
|
|
21
|
+
| `packages/adapter-sqlite/src/index.ts` | `SqliteProvenanceStore` novo (reaproveita `SqliteJsonRepository`) | Baixo |
|
|
22
|
+
| `scripts/provenance.ts` | novo — `provenance:record`/`blame`/`sbom` | Baixo |
|
|
23
|
+
| `lib/core/registry.ts` | 3 comandos novos | Baixo |
|
|
24
|
+
| `test/provenance.test.js` (novo) | unit + CLI | — |
|
|
25
|
+
|
|
26
|
+
## 3. Contratos
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
// packages/engineering/provenance/src/index.ts
|
|
30
|
+
export interface ProvenanceRecord {
|
|
31
|
+
readonly file: string;
|
|
32
|
+
readonly runId: string;
|
|
33
|
+
readonly agentId: string;
|
|
34
|
+
readonly model?: string;
|
|
35
|
+
readonly lines?: readonly [number, number][]; // sempre undefined nesta spec — ver AC-2
|
|
36
|
+
readonly recordedAt: string;
|
|
37
|
+
}
|
|
38
|
+
export function extractProvenance(run: RuntimeRun): readonly ProvenanceRecord[];
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
provenance:record <run-id>
|
|
43
|
+
blame <file>
|
|
44
|
+
sbom [--json]
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## 4. Decisões
|
|
48
|
+
|
|
49
|
+
**D1**: `blame`/`sbom` são comandos de topo (não `provenance:blame`/`provenance:sbom`) — a visão
|
|
50
|
+
original e o CLI plan (`docs/architecture/...` §12) já citam `provenance:blame`/`:generate`, mas
|
|
51
|
+
"blame" e "sbom" como conceitos são suficientemente autoexplicativos e usados fora do namespace
|
|
52
|
+
`provenance:` em outras ferramentas (`git blame`, SBOM genérico) — manter `provenance:record` (a
|
|
53
|
+
ação de escrita, menos ambígua com prefixo) e deixar as duas leituras mais usadas sem prefixo,
|
|
54
|
+
espelhando `engineer`/`simulate` (façades/comandos de leitura frequente também sem prefixo de
|
|
55
|
+
domínio).
|
|
56
|
+
|
|
57
|
+
**D2**: `SqliteRuntimeRunStore` não ganha `list()` nesta spec — `blame`/`sbom` enumeram via
|
|
58
|
+
`SqliteProvenanceStore.list()` (nova, mas só ela é necessária); `SqliteRuntimeRunStore.get(runId)`
|
|
59
|
+
já existente basta pra `provenance:record <run-id>` (busca um run específico por id). Adicionar
|
|
60
|
+
`list()` a `SqliteRuntimeRunStore` sem um consumidor real seria antecipar uso hipotético — evitado
|
|
61
|
+
por princípio (CLAUDE.md/instruções da sessão: não adicionar abstração além do que a tarefa exige).
|
|
62
|
+
|
|
63
|
+
## 5. Rollout
|
|
64
|
+
|
|
65
|
+
Sem migração, sem feature flag.
|
|
66
|
+
|
|
67
|
+
## 6. Kill criteria
|
|
68
|
+
|
|
69
|
+
Já coberto pelo mesmo princípio das specs anteriores — se `blame`/`sbom` confundirem usuários por
|
|
70
|
+
prometerem granularidade de linha, revisar a UX (não os dados, que já são honestos por construção
|
|
71
|
+
via AC-2) antes de qualquer extensão futura.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Spec: AI Code Provenance + AI-SBOM
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-039
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 7 (Fase 5 da visão original)
|
|
8
|
+
- **ADRs relacionadas**: ADR-0078; depende de `RuntimeRun`/`AgentIdentity` (`packages/contracts`,
|
|
9
|
+
já existentes) e `SqliteRuntimeRunStore` (já existente)
|
|
10
|
+
|
|
11
|
+
> Gap analysis original (`docs/architecture/...` §3): "`Observation` já tem `model`, `agentId`,
|
|
12
|
+
> `runId`, `inputHash`, `contextRefs` — falta só ligar linha de código a `Observation`... Construir,
|
|
13
|
+
> dado que os campos-fonte já existem." `RuntimeRun.changedFiles`+`RuntimeRun.agent` têm exatamente
|
|
14
|
+
> o dado necessário pra provenance em **granularidade de arquivo** — a granularidade que este
|
|
15
|
+
> repositório de fato coleta hoje.
|
|
16
|
+
|
|
17
|
+
## 1. Problema
|
|
18
|
+
|
|
19
|
+
Nada liga "este arquivo mudou neste run" a "quem/qual agente produziu essa mudança" de forma
|
|
20
|
+
consultável — `RuntimeRun` já grava `changedFiles`+`agent` por run, mas essa informação fica presa
|
|
21
|
+
em cada `RuntimeRun` isolado, sem uma view "quem tocou este arquivo, ao longo do tempo" nem um
|
|
22
|
+
relatório agregado de proveniência do código gerado por IA.
|
|
23
|
+
|
|
24
|
+
## 2. Proposta de valor
|
|
25
|
+
|
|
26
|
+
`forja provenance:record <run-id>` extrai proveniência (arquivo↔agente↔run) de um `RuntimeRun` já
|
|
27
|
+
persistido; `forja blame <file>` mostra o histórico de quem tocou um arquivo; `forja sbom` agrega
|
|
28
|
+
tudo num relatório por agente/modelo — um "AI-SBOM" honesto sobre o que já foi coletado, não uma
|
|
29
|
+
promessa de rastreamento que o sistema não tem dado pra sustentar.
|
|
30
|
+
|
|
31
|
+
## 3. User stories
|
|
32
|
+
|
|
33
|
+
- **Como** governance, **quero** saber quais agentes/modelos tocaram um arquivo, **para que** eu
|
|
34
|
+
saiba a quem perguntar ou o que revisar com mais cuidado.
|
|
35
|
+
- **Como** compliance/auditoria, **quero** um relatório agregado de proveniência do código gerado
|
|
36
|
+
por IA neste projeto, **para que** eu tenha uma resposta estruturada, não "não sabemos".
|
|
37
|
+
|
|
38
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
39
|
+
|
|
40
|
+
- [x] AC-1: `extractProvenance` (função pura, `packages/engineering/provenance`) recebe um
|
|
41
|
+
`RuntimeRun` e devolve `ProvenanceRecord[]` (um por arquivo em `changedFiles`) — nenhum dado
|
|
42
|
+
inventado além do que o run já registrou.
|
|
43
|
+
- [x] AC-2: granularidade é **arquivo**, não linha — `ProvenanceRecord.lines` existe no tipo (mesmo
|
|
44
|
+
shape do `ProvenanceEngine.recordGeneration` desenhado no doc de arquitetura §11) mas fica
|
|
45
|
+
`undefined` nesta spec, porque nenhuma fonte de dado real deste repositório rastreia hunks de
|
|
46
|
+
linha por run hoje. Nunca fingir granularidade de linha que não existe (mesmo princípio de
|
|
47
|
+
"nunca escondida" já usado em `AgentReputationScore.confidence`).
|
|
48
|
+
- [x] AC-3: `forja provenance:record <run-id>` persiste os `ProvenanceRecord`s de um `RuntimeRun`
|
|
49
|
+
já existente (`SqliteRuntimeRunStore.get`, já existente) — sem tocar em `RuntimeEngine`, sem
|
|
50
|
+
novo ponto de coleta automática (essa integração é spec própria futura, ver §5).
|
|
51
|
+
- [x] AC-4: `forja blame <file>` lista os registros de proveniência de um arquivo, mais recentes
|
|
52
|
+
primeiro.
|
|
53
|
+
- [x] AC-5: `forja sbom [--json]` agrega todos os registros por **agente** (contagem de arquivos,
|
|
54
|
+
lista de arquivos) — derivado inteiramente do que já foi gravado, sem nova fonte de verdade.
|
|
55
|
+
Não agrega por modelo: `AgentIdentity` (o tipo real de `RuntimeRun.agent`) não carrega um
|
|
56
|
+
campo de modelo de LLM hoje — `ProvenanceRecord.model` fica declarado no tipo mas sempre
|
|
57
|
+
`undefined`, mesmo raciocínio de AC-2 pra `lines`.
|
|
58
|
+
|
|
59
|
+
## 5. Escopo
|
|
60
|
+
|
|
61
|
+
**Dentro**: `extractProvenance` (motor puro); `SqliteProvenanceStore` (reaproveita
|
|
62
|
+
`SqliteJsonRepository`, sem migration nova — mesmo padrão de `SqliteAgentProfileStore`);
|
|
63
|
+
`provenance:record`/`blame`/`sbom` (CLI).
|
|
64
|
+
|
|
65
|
+
**Fora** (spec própria futura, mesmo princípio de escopo já usado nas specs anteriores):
|
|
66
|
+
- Coleta automática de proveniência no fim de todo `RuntimeRun` (integração com `RuntimeEngine`) —
|
|
67
|
+
esta spec só extrai de runs já persistidos, sob demanda; automatizar a coleta é uma mudança no
|
|
68
|
+
caminho crítico do runtime, merece spec própria com sua própria análise de risco.
|
|
69
|
+
- Granularidade de linha (`git blame`-like) — exigiria uma fonte de dado nova (hunks de diff por
|
|
70
|
+
run) que não existe hoje; ver AC-2.
|
|
71
|
+
- AI-SBOM em formato padrão da indústria (CycloneDX/SPDX) — o relatório desta spec é interno,
|
|
72
|
+
formato próprio; adotar um formato padrão é decisão separada, não bloqueante pra esta fundação.
|
|
73
|
+
|
|
74
|
+
## 6. NFRs / restrições
|
|
75
|
+
|
|
76
|
+
- Determinístico — nenhum LLM em nenhum ponto.
|
|
77
|
+
- `ProvenanceRecord` nunca afirma granularidade de linha sem dado real (AC-2).
|
|
78
|
+
- Zero migration SQLite nova (mesmo padrão de SPEC-036).
|
|
79
|
+
|
|
80
|
+
## 7. Riscos e mitigação
|
|
81
|
+
|
|
82
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
83
|
+
|---|---|---|---|
|
|
84
|
+
| `forja blame`/`sbom` prometerem granularidade de linha que não existe | Média (nome "blame" sugere `git blame`) | Média (confiança quebrada quando descoberto) | AC-2 explícito; saída de `blame` deixa claro que é por arquivo, não por linha |
|
|
85
|
+
| `provenance:record` divergir do `RuntimeRun` original se rodado depois de mudanças | Baixa | Baixa | `RuntimeRun` é imutável após completar (mesmo padrão já estabelecido); `provenance:record` sempre lê o estado atual, idempotente por natureza |
|
|
86
|
+
|
|
87
|
+
## 8. Métricas de sucesso
|
|
88
|
+
|
|
89
|
+
Rodar `provenance:record` sobre 1+ `RuntimeRun` real ou sintético documentado como tal, e confirmar
|
|
90
|
+
que `blame`/`sbom` refletem corretamente o que foi gravado — revisão humana, mesma metodologia das
|
|
91
|
+
specs anteriores.
|
|
92
|
+
|
|
93
|
+
**Validado** (`test/provenance-cli.test.js`): `RuntimeRun` sintético documentado como tal (este
|
|
94
|
+
workspace de desenvolvimento ainda não acumulou runs reais suficientes, mesma situação já
|
|
95
|
+
registrada em SPEC-036 §8) com 2 arquivos alterados — `provenance:record` gravou os 2 registros,
|
|
96
|
+
`blame` de cada arquivo mostrou o agente/run corretos, `sbom` agregou corretamente por agente.
|
|
97
|
+
Regravar o mesmo run é idempotente (chave `runId:file`), não duplica.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Tasks: AI Code Provenance + AI-SBOM
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — `extractProvenance` (motor puro) + `SqliteProvenanceStore` + CLI
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: M
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `packages/engineering/provenance/src/index.ts`, `packages/adapter-sqlite/src/index.ts`,
|
|
15
|
+
`scripts/provenance.ts`, `lib/core/registry.ts`
|
|
16
|
+
- **Done quando**:
|
|
17
|
+
- [ ] `extractProvenance` mapeia `RuntimeRun.changedFiles` → `ProvenanceRecord[]`, `lines`
|
|
18
|
+
sempre `undefined` (AC-2)
|
|
19
|
+
- [ ] `provenance:record <run-id>` lê o run real (`SqliteRuntimeRunStore.get`), persiste via
|
|
20
|
+
`SqliteProvenanceStore` (zero migration nova)
|
|
21
|
+
- [ ] `blame <file>` / `sbom [--json]` funcionais
|
|
22
|
+
- [ ] `forja tools:doctor` continua verde
|
|
23
|
+
- [ ] testes unitários de `extractProvenance` (sem `fs`/rede)
|
|
24
|
+
|
|
25
|
+
## T2 — prova sobre dado real/sintético documentado
|
|
26
|
+
- **Owner**: worker
|
|
27
|
+
- **Estimativa**: P
|
|
28
|
+
- **Depende de**: T1
|
|
29
|
+
- **Paths**: `test/provenance-cli.test.js` (novo)
|
|
30
|
+
- **Done quando**:
|
|
31
|
+
- [ ] fixture isolada: seed de 1+ `RuntimeRun` (sintético documentado como tal, §8 do spec),
|
|
32
|
+
`provenance:record` + `blame` + `sbom` ponta a ponta
|
|
33
|
+
- [ ] `blame` de um arquivo nunca tocado devolve vazio, não erro
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Handoffs entre agentes
|
|
38
|
+
|
|
39
|
+
T1 → T2 sequencial. Sem handoff de papel.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Plan: Architecture Constitution — ADRs como regras executáveis
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
Novo bounded context `packages/engineering/architecture` (autorizado por ADR-0078), puro domínio
|
|
10
|
+
(sem `fs`/rede — só parsing de string e comparação de listas), consumido por um script CLI
|
|
11
|
+
(`scripts/architecture.ts`) que faz a ponte com `fs` (ler ADRs) e `GraphLoop` (ler arestas
|
|
12
|
+
`DEPENDS_ON` reais). Vocabulário de frase reconhecida é pequeno e fixo (3 padrões: proibir
|
|
13
|
+
import, exigir dependência, proibir dependência) — qualquer linha de `## Constraints` fora desse
|
|
14
|
+
vocabulário vira regra `proposed` com `confidence < 1`, nunca `active` (AC-1).
|
|
15
|
+
|
|
16
|
+
## 2. Módulos afetados
|
|
17
|
+
|
|
18
|
+
| Caminho | Mudança | Risco |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `packages/engineering/architecture/src/index.ts` | novo — `parseConstraintLine`, `compileConstitution`, `checkConstitution`, `explainRule` | Médio — lógica nova, mas pura/testável |
|
|
21
|
+
| `scripts/architecture.ts` | novo — `architecture:compile/check/status/explain/approve` | Baixo — I/O fino sobre o engine puro |
|
|
22
|
+
| `lib/core/registry.ts` | 5 comandos novos | Baixo |
|
|
23
|
+
| `packages/policy` (não muda código) — `ApprovalLedger` reaproveitado por `architecture:approve` | leitura/escrita via API já existente | Baixo |
|
|
24
|
+
| `memory/90-decisions/0078-*.md` | ganha `## Constraints` real (1 regra) — primeira prova de que o parser funciona sobre dado real do próprio repositório | — |
|
|
25
|
+
| `test/architecture-constitution.test.js` (novo) | testes do parser + compile + check (incluindo violação injetada em unidade, não em arquivo real) | — |
|
|
26
|
+
|
|
27
|
+
## 3. Diagrama de fluxo
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
memory/90-decisions/*.md (## Constraints)
|
|
31
|
+
│
|
|
32
|
+
▼
|
|
33
|
+
parseConstraintLine (determinístico, vocabulário fixo)
|
|
34
|
+
│
|
|
35
|
+
▼
|
|
36
|
+
compileConstitution ──► .context/architecture/constitution.json (versionado em git)
|
|
37
|
+
│
|
|
38
|
+
▼
|
|
39
|
+
checkConstitution (recebe rules + edges DEPENDS_ON já extraídas pelo GraphLoop existente)
|
|
40
|
+
│
|
|
41
|
+
▼
|
|
42
|
+
ArchitectureCheckReport (compliant/violations, severidade, remediação sugerida)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## 4. Contratos (API/CLI/Schema)
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
// packages/engineering/architecture/src/index.ts
|
|
49
|
+
export type ArchitectureConstraintKind = 'forbid_import' | 'require_dependency' | 'forbid_dependency';
|
|
50
|
+
export interface ArchitectureConstraint { readonly kind: ArchitectureConstraintKind; readonly target: string; }
|
|
51
|
+
export interface ArchitectureRule {
|
|
52
|
+
readonly id: string;
|
|
53
|
+
readonly source: string; // ex.: 'memory/90-decisions/0078-....md'
|
|
54
|
+
readonly status: 'active' | 'proposed';
|
|
55
|
+
readonly scope: { readonly paths: readonly string[] };
|
|
56
|
+
readonly constraint: ArchitectureConstraint;
|
|
57
|
+
readonly severity: 'info' | 'low' | 'medium' | 'high' | 'critical';
|
|
58
|
+
readonly rationale: string; // texto original da linha
|
|
59
|
+
readonly confidence: number; // 1 = padrão reconhecido; < 1 = ambíguo, fica proposed
|
|
60
|
+
}
|
|
61
|
+
export interface DependencyEdge { readonly fromPath: string; readonly targetLabel: string; }
|
|
62
|
+
export interface ArchitectureViolation { readonly ruleId: string; readonly severity: ArchitectureRule['severity']; readonly file: string; readonly target: string; readonly source: string; readonly remediation: string; }
|
|
63
|
+
export interface ArchitectureCheckReport { readonly compliant: number; readonly violations: readonly ArchitectureViolation[]; }
|
|
64
|
+
|
|
65
|
+
export function parseConstraintLine(line: string): { constraint: ArchitectureConstraint; scopeRaw: string; confidence: number } | undefined;
|
|
66
|
+
export function compileConstitution(adrs: readonly { source: string; content: string }[]): readonly ArchitectureRule[];
|
|
67
|
+
export function checkConstitution(rules: readonly ArchitectureRule[], edges: readonly DependencyEdge[]): ArchitectureCheckReport;
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
architecture:compile
|
|
72
|
+
architecture:check
|
|
73
|
+
architecture:status
|
|
74
|
+
architecture:explain <rule-id>
|
|
75
|
+
architecture:approve <rule-id>
|
|
76
|
+
```
|
|
77
|
+
(sem prefixo `forja` — nenhum existe ainda, mesma convenção já usada em SPEC-032/doc de arquitetura)
|
|
78
|
+
|
|
79
|
+
## 5. Decisões e alternativas
|
|
80
|
+
|
|
81
|
+
**D1**: `ArchitectureRule`/`ArchitectureConstraint` vivem em `packages/engineering/architecture`,
|
|
82
|
+
não em `packages/contracts`. O documento de arquitetura original (§6) sugeriu `packages/contracts`
|
|
83
|
+
— revisado aqui: nenhum outro pacote hoje precisa desses tipos além do próprio engine de
|
|
84
|
+
arquitetura e seu adapter CLI; colocá-los no contracts compartilhado cedo demais repetiria o erro
|
|
85
|
+
que ADR-0078 já evita para o pacote como um todo (acoplamento prematuro). Revisitar se
|
|
86
|
+
`packages/engineering/risk` (SPEC-034) precisar do mesmo vocabulário.
|
|
87
|
+
|
|
88
|
+
**D2**: vocabulário de frase fixo em português, 3 padrões (`não depende de` / `usa` / `não
|
|
89
|
+
acessa`), scope e target devem conter `/` (parecer caminho) para confidence=1. Alternativa
|
|
90
|
+
rejeitada: NLP/heurística mais permissiva — rejeitada explicitamente por AC-1 e pelo risco #1 do
|
|
91
|
+
spec (falso positivo em massa).
|
|
92
|
+
|
|
93
|
+
## 6. Dependências
|
|
94
|
+
|
|
95
|
+
- SPEC-032 (nós ADR com `documentStatus`) — usado por `architecture:status` para não compilar
|
|
96
|
+
regra de ADR `superseded`/`deprecated` (verificação leve, não bloqueante se o dado não estiver
|
|
97
|
+
disponível).
|
|
98
|
+
- `packages/policy.ApprovalLedger` — reaproveitado por `architecture:approve`.
|
|
99
|
+
|
|
100
|
+
## 7. Rollout
|
|
101
|
+
|
|
102
|
+
- [ ] Feature flag necessária? Não — comando novo, opt-in por natureza (ninguém chama sem saber).
|
|
103
|
+
- [ ] Migração de dados existentes? Não.
|
|
104
|
+
- [ ] Doc/persona impactada? README (comandos novos), `docs/architecture/`.
|
|
105
|
+
|
|
106
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
107
|
+
|
|
108
|
+
Já registrado no `plan.md`-equivalente da spec master (`specs/engineering-intelligence/spec.md`,
|
|
109
|
+
apêndice): mais falso-positivo que sinal real sobre este próprio repositório após o Sprint 1
|
|
110
|
+
manda redesenhar o motor antes de avançar.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Spec: Architecture Constitution — ADRs como regras executáveis
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-033
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 1
|
|
8
|
+
- **ADRs relacionadas**: ADR-0078; depende de SPEC-032 (nós ADR) e reaproveita o motor de
|
|
9
|
+
comparação "isso que era verdade parou de ser" desenhado em `specs/drift-sentinel/spec.md`
|
|
10
|
+
(SPEC-030).
|
|
11
|
+
|
|
12
|
+
## 1. Problema
|
|
13
|
+
|
|
14
|
+
Uma decisão registrada em ADR (`memory/90-decisions/NNNN-*.md`) hoje só é verificada por um
|
|
15
|
+
humano lembrar de reler o documento. Nada impede que o código viole uma restrição arquitetural
|
|
16
|
+
documentada dias, semanas ou meses atrás, sem que ninguém perceba — a mesma classe de problema que
|
|
17
|
+
`drift-sentinel` resolve para relações genéricas do grafo, aqui aplicada especificamente a
|
|
18
|
+
restrições de arquitetura.
|
|
19
|
+
|
|
20
|
+
## 2. Proposta de valor
|
|
21
|
+
|
|
22
|
+
ADRs com uma seção `## Constraints` em formato estruturado (ver §4) compilam para regras
|
|
23
|
+
executáveis (`.context/architecture/constitution.json`, versionado em git), verificáveis por
|
|
24
|
+
`forja architecture:check` a qualquer momento — inclusive como gate de CI, quando o projeto
|
|
25
|
+
consumidor optar por isso.
|
|
26
|
+
|
|
27
|
+
## 3. User stories
|
|
28
|
+
|
|
29
|
+
- **Como** sdd-architect, **quero** que uma restrição documentada em ADR seja verificada
|
|
30
|
+
automaticamente, **para que** "documentado" e "em vigor" nunca divirjam sem ninguém notar.
|
|
31
|
+
- **Como** governance, **quero** um relatório de violações por severidade, **para que** eu saiba
|
|
32
|
+
quais bloqueiam merge e quais são só aviso.
|
|
33
|
+
- **Como** desenvolvedor, **quero** `architecture:explain <rule-id>` antes de contestar uma
|
|
34
|
+
violação, **para que** eu entenda o porquê sem precisar caçar a ADR original.
|
|
35
|
+
|
|
36
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
37
|
+
|
|
38
|
+
- [x] AC-1: formato de `## Constraints` em ADR é determinístico e documentado (ex.: lista com
|
|
39
|
+
prefixo fixo — `- billing não importa database diretamente` vira
|
|
40
|
+
`{kind: 'forbid_import', patterns: ['**/database/**']}` só quando a frase casa um padrão
|
|
41
|
+
reconhecido; frases que não casam viram regra `proposed` com `confidence < 1`, nunca
|
|
42
|
+
`active` por adivinhação).
|
|
43
|
+
- [x] AC-2: `forja architecture:compile` lê `memory/90-decisions/*.md` com `## Constraints`,
|
|
44
|
+
produz `ArchitectureRule[]`, grava `.context/architecture/constitution.json`.
|
|
45
|
+
- [x] AC-3: `forja architecture:check` compara `constitution.json` contra o Engineering Graph
|
|
46
|
+
(arestas `depends_on`/`imports` já extraídas por `extractDeterministicRelations`) e reporta
|
|
47
|
+
violações com severidade (`info|low|medium|high|critical`), path do arquivo, ADR de origem,
|
|
48
|
+
remediação sugerida.
|
|
49
|
+
- [x] AC-4: `forja architecture:status` resume: N regras ativas, N propostas, última compilação.
|
|
50
|
+
- [x] AC-5: `forja architecture:explain <rule-id>` mostra a ADR de origem, o texto original da
|
|
51
|
+
restrição, e a severidade/razão.
|
|
52
|
+
- [x] AC-6: uma regra `proposed` só vira `active` por `forja architecture:approve <rule-id>`
|
|
53
|
+
(reaproveita `ApprovalLedger` de `packages/policy` — **não** um sistema de aprovação
|
|
54
|
+
paralelo).
|
|
55
|
+
- [x] AC-7: `architecture:check` pode participar de `check:all` como item opcional
|
|
56
|
+
(`--with-architecture`), não obrigatório por padrão (mesma decisão de opt-in já tomada para
|
|
57
|
+
`drift:check` em SPEC-030 AC-5, pelo mesmo motivo: custo em repos grandes ainda não medido).
|
|
58
|
+
|
|
59
|
+
**Nota de implementação (achado real, fora de escopo desta spec)**: testar `architecture:check`
|
|
60
|
+
contra o workspace real (`~/forja-workspace`) expôs um diagnóstico enganoso em `memory-db`
|
|
61
|
+
(`lib/core/health.ts`): o gate reportou "banco existe mas não abre (SQLITE_ERROR) — provavelmente
|
|
62
|
+
corrompido", mas `sqlite3 ... PRAGMA integrity_check` confirmou "ok" — não é corrupção. Causa real:
|
|
63
|
+
`getWorkspaceDbPath()` aponta para o mesmo arquivo físico usado por dois mecanismos independentes —
|
|
64
|
+
`scripts/sync-universal-memory.ts` cria sua própria tabela `memory_nodes` via `CREATE TABLE IF NOT
|
|
65
|
+
EXISTS` fora de qualquer migration, enquanto `adr:*`/`architecture:*` (e o já mergeado `drift:check`,
|
|
66
|
+
SPEC-030) usam `SqliteMigrationRunner` (schema do Engineering Graph/policy/runtime). Os dois são
|
|
67
|
+
aditivos — não há conflito de dados — mas se `sync:universal` nunca rodou nesse workspace, a tabela
|
|
68
|
+
`memory_nodes` simplesmente não existe ainda, e o `SELECT count(*) FROM memory_nodes` do health check
|
|
69
|
+
cai no branch genérico de erro, que rotula como "provavelmente corrompido" em vez de "rode `npm run
|
|
70
|
+
sync:universal`". Nenhum dado foi perdido (o arquivo de teste era novo, criado só pelos meus testes
|
|
71
|
+
desta sprint, removido com segurança). Vale uma correção pontual em `health.ts` para diferenciar
|
|
72
|
+
"tabela ausente" de corrupção de fato — não implementada aqui por estar fora do escopo desta spec.
|
|
73
|
+
|
|
74
|
+
**Corrigido posteriormente**: `lib/core/health.ts`'s `memory-db` agora reconhece
|
|
75
|
+
`"no such table: memory_nodes"` como um caso à parte (`warn`, mesma severidade de "banco nunca
|
|
76
|
+
indexado", com `fix: npm run sync:universal` — que de fato resolve, ao contrário do caso
|
|
77
|
+
CANTOPEN/EACCES) em vez de cair no branch genérico de "provavelmente corrompido". Ver
|
|
78
|
+
`test/health.test.js` e o commit que fecha esta nota.
|
|
79
|
+
|
|
80
|
+
## 5. Escopo
|
|
81
|
+
|
|
82
|
+
**Dentro**: compile/check/status/explain/approve; parser determinístico de `forbid_import`/
|
|
83
|
+
`require_dependency`/`forbid_dependency` (os três tipos de restrição citados no exemplo da visão
|
|
84
|
+
original); severidade configurável.
|
|
85
|
+
|
|
86
|
+
**Fora**: sugestão de regra via LLM (mencionada na visão como "Fase 6+", não nesta spec — ver
|
|
87
|
+
`ArchitectureConstraint` no documento de arquitetura, campo `confidence` já reservado para quando
|
|
88
|
+
isso existir); auto-correção de violação (só reporta, nunca aplica); tipos de constraint além dos
|
|
89
|
+
três listados (ex.: regras de nomenclatura, limites de complexidade) — aditivo depois que os três
|
|
90
|
+
básicos estiverem em produção.
|
|
91
|
+
|
|
92
|
+
## 6. NFRs / restrições
|
|
93
|
+
|
|
94
|
+
- **LLM nunca decide regra `active` sozinho** — princípio de segurança explícito da visão
|
|
95
|
+
original, reforçado pela postura fail-closed já em vigor no resto do framework desde a
|
|
96
|
+
auditoria de 2026-08-31.
|
|
97
|
+
- `constitution.json` é artefato de git, não linha SQLite — precisa ser revisável em PR como
|
|
98
|
+
qualquer outro artefato gerado (mesma categoria de `.context/forja-runs.jsonl`).
|
|
99
|
+
- Falso positivo é o risco central (ver riscos) — parser determinístico só reconhece padrões de
|
|
100
|
+
frase explícitos; qualquer coisa fora do padrão vira `proposed`, nunca `active` por default.
|
|
101
|
+
|
|
102
|
+
## 7. Riscos e mitigação
|
|
103
|
+
|
|
104
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
105
|
+
|---|---|---|---|
|
|
106
|
+
| Parser de linguagem natural de `## Constraints` interpretar errado uma frase | Alta (é a natureza do problema) | Alta (falso positivo em massa) | Vocabulário de frase reconhecida é pequeno e explícito (AC-1); fora do vocabulário = `proposed`, nunca `active` |
|
|
107
|
+
| `architecture:check` virar ruído e ser ignorado | Média | Alta (perde todo o valor) | AC-7 opt-in até o sinal ser medido; kill criteria já registrado no `plan.md` da spec master |
|
|
108
|
+
| Conflito entre duas ADRs com constraints contraditórias | Baixa | Média | `architecture:compile` reporta conflito explicitamente como erro de compilação, não escolhe uma silenciosamente |
|
|
109
|
+
|
|
110
|
+
## 8. Métricas de sucesso
|
|
111
|
+
|
|
112
|
+
Compilar as ADRs reais deste repositório (`memory/90-decisions/`) produz pelo menos uma regra
|
|
113
|
+
`active` verificável, e `architecture:check` roda sem falso positivo sobre o código atual (linha de
|
|
114
|
+
base limpa, igual ao Sprint 1 do plan.md da spec master).
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Tasks: Architecture Constitution
|
|
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: parser + compile + check
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: G
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `packages/engineering/architecture/src/index.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `parseConstraintLine` reconhece os 3 padrões (D2 do plan) e retorna `undefined`/confiança
|
|
17
|
+
baixa para qualquer coisa fora do vocabulário
|
|
18
|
+
- [ ] `compileConstitution` produz `ArchitectureRule[]` a partir de ADRs reais com
|
|
19
|
+
`## Constraints`
|
|
20
|
+
- [ ] `checkConstitution` compara regras contra `DependencyEdge[]` e reporta violações com
|
|
21
|
+
severidade e remediação
|
|
22
|
+
- [ ] testes unitários (sem `fs`/rede) cobrindo: padrão reconhecido → confidence 1; padrão
|
|
23
|
+
ambíguo → confidence baixa, nunca `active`; violação injetada é detectada; ausência de
|
|
24
|
+
violação é reportada como `compliant`
|
|
25
|
+
|
|
26
|
+
## T2 — `scripts/architecture.ts`: compile/check/status/explain/approve
|
|
27
|
+
- **Owner**: worker
|
|
28
|
+
- **Estimativa**: M
|
|
29
|
+
- **Depende de**: T1
|
|
30
|
+
- **Paths**: `scripts/architecture.ts`, `lib/core/registry.ts`
|
|
31
|
+
- **Done quando**:
|
|
32
|
+
- [ ] `architecture:compile` lê `memory/90-decisions/*.md` reais e grava
|
|
33
|
+
`.context/architecture/constitution.json`
|
|
34
|
+
- [ ] `architecture:check` roda sobre o grafo real (reindexado como `adr:*`/`drift:check` já
|
|
35
|
+
fazem) e reporta zero violação na linha de base deste repositório
|
|
36
|
+
- [ ] `architecture:status`/`architecture:explain <rule-id>` funcionais
|
|
37
|
+
- [ ] `architecture:approve <rule-id>` reaproveita `ApprovalLedger` (`packages/policy`), sem
|
|
38
|
+
sistema de aprovação paralelo
|
|
39
|
+
- [ ] `forja tools:doctor` continua verde (comandos documentados no README)
|
|
40
|
+
|
|
41
|
+
## T3 — prova sobre dado real + violação injetada em teste
|
|
42
|
+
- **Owner**: worker
|
|
43
|
+
- **Estimativa**: P
|
|
44
|
+
- **Depende de**: T2
|
|
45
|
+
- **Paths**: `memory/90-decisions/0078-forjajs-3-engineering-control-plane.md` (`## Constraints`
|
|
46
|
+
já adicionado), `test/architecture-constitution-cli.test.js` (novo)
|
|
47
|
+
- **Done quando**:
|
|
48
|
+
- [ ] `architecture:compile` + `architecture:check` reais sobre este repositório: 1 regra
|
|
49
|
+
ativa, zero violação
|
|
50
|
+
- [ ] teste de CLI com fixture isolada prova que uma violação real (arquivo importando o que a
|
|
51
|
+
regra proíbe) é detectada com exit code ≠ 0
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Handoffs entre agentes
|
|
56
|
+
|
|
57
|
+
T1→T2→T3 sequencial. Sem handoff de papel — spec e plan já aprovados cobrem as decisões de
|
|
58
|
+
produto/arquitetura.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Plan: Change Risk Engine
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
Novo bounded context `packages/engineering/risk` (autorizado por ADR-0078), puro domínio — a
|
|
10
|
+
fórmula dos 7 fatores (§9 do doc de arquitetura) roda inteira sobre um `RiskInput` já calculado,
|
|
11
|
+
sem `fs`/rede/SQLite. Quem coleta os números reais é `scripts/risk.ts` (adapter), reaproveitando
|
|
12
|
+
integralmente o que Sprint 1 já construiu: `GraphLoop.impact()` para blast radius,
|
|
13
|
+
`checkConstitution` (SPEC-033) para violações de arquitetura, `SqliteObservationStore` (já
|
|
14
|
+
existente em `packages/adapter-sqlite`) para taxa histórica de falha. Nenhuma tabela SQLite nova.
|
|
15
|
+
|
|
16
|
+
## 2. Módulos afetados
|
|
17
|
+
|
|
18
|
+
| Caminho | Mudança | Risco |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `packages/engineering/risk/src/index.ts` | novo — `assessRisk`, `explainAssessment`, `createRiskEngine`, pesos/thresholds default | Médio — lógica nova, pura/testável |
|
|
21
|
+
| `scripts/risk.ts` | novo — `risk:assess`/`risk:explain`, coleta blast radius/violações/histórico/testes/serviços reais | Médio — bastante integração, mas cada peça já existe |
|
|
22
|
+
| `lib/core/registry.ts` | 2 comandos novos | Baixo |
|
|
23
|
+
| `packages/policy/src/index.ts` | `PolicyScope.riskScoreRange` + `PolicyRequest.riskScore` (campos aditivos, sem import de `@forja/engineering-risk`) | Baixo — extensão aditiva, mesmo padrão de `maxCostUsd` (SPEC-029) |
|
|
24
|
+
| `test/risk-engine.test.js` (novo) | testes puros do motor: fórmula, confidence, bandas | — |
|
|
25
|
+
| `test/risk-cli.test.js` (novo) | fixture git isolada: `risk:assess`/`risk:explain` ponta a ponta | — |
|
|
26
|
+
| `test/policy.test.js` | +1 teste: `riskScoreRange` na `matches()` | — |
|
|
27
|
+
|
|
28
|
+
## 3. Diagrama de fluxo
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
git diff --name-only [ref] (scripts/risk.ts, coleta)
|
|
32
|
+
│
|
|
33
|
+
├── GraphLoop.impact(origin) ──────────► blast_radius
|
|
34
|
+
├── checkConstitution (constitution.json + arestas DEPENDS_ON) ─► architecture_violations
|
|
35
|
+
├── heurística de path (secrets/database/deployment) ─────────► security_sensitivity
|
|
36
|
+
├── SqliteObservationStore.list() filtrado por files ──────────► historical_failure_rate
|
|
37
|
+
├── existência de test/<nome>.test.js ──────────────────────────► test_confidence
|
|
38
|
+
├── path casa /migration|schema/ ────────────────────────────────► reversibility
|
|
39
|
+
└── packages/*, apps/* distintos tocados ────────────────────────► deployment_complexity
|
|
40
|
+
│
|
|
41
|
+
▼
|
|
42
|
+
assessRisk(input) [packages/engineering/risk, puro]
|
|
43
|
+
│
|
|
44
|
+
▼
|
|
45
|
+
ChangeRiskAssessment (score, confidence, autonomyBand, factors[])
|
|
46
|
+
│
|
|
47
|
+
▼
|
|
48
|
+
.context/risk/<id>.json (efêmero, mesma categoria de forja-runs.jsonl)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## 4. Contratos (API/CLI/Schema)
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
// packages/engineering/risk/src/index.ts
|
|
55
|
+
export type RiskFactorName = 'blast_radius' | 'architecture_violations' | 'security_sensitivity'
|
|
56
|
+
| 'historical_failure_rate' | 'test_confidence' | 'reversibility' | 'deployment_complexity';
|
|
57
|
+
export type RiskWeights = Readonly<Record<RiskFactorName, number>>;
|
|
58
|
+
export const DEFAULT_RISK_WEIGHTS: RiskWeights; // soma 1.0, pesos do §9 do doc de arquitetura
|
|
59
|
+
export interface AutonomyBandThresholds { readonly autonomous: number; readonly autonomousWithReview: number; readonly supervised: number; }
|
|
60
|
+
export const DEFAULT_AUTONOMY_BAND_THRESHOLDS: AutonomyBandThresholds; // 25/50/75 — >75 = human_in_the_loop
|
|
61
|
+
export type AutonomyBand = 'autonomous' | 'autonomous_with_review' | 'supervised' | 'human_in_the_loop';
|
|
62
|
+
export interface RiskInput { /* 7 métricas cruas + evidenceIds por fator — ver código */ }
|
|
63
|
+
export interface RiskFactorResult { readonly name: RiskFactorName; readonly weight: number; readonly value: number; readonly hasRealData: boolean; readonly evidenceIds: readonly string[]; readonly rationale: string; }
|
|
64
|
+
export interface ChangeRiskAssessment { readonly id: string; readonly changeId: string; readonly createdAt: string; readonly score: number; readonly confidence: number; readonly autonomyBand: AutonomyBand; readonly factors: readonly RiskFactorResult[]; }
|
|
65
|
+
export function assessRisk(input: RiskInput, options: { id: string; changeId: string; now: string; weights?: Partial<RiskWeights>; thresholds?: AutonomyBandThresholds }): ChangeRiskAssessment;
|
|
66
|
+
export function explainAssessment(assessment: ChangeRiskAssessment): string;
|
|
67
|
+
export interface RiskEngine { assess(input: RiskInput, meta: { id: string; changeId: string; now: string }): ChangeRiskAssessment; }
|
|
68
|
+
export function createRiskEngine(config?: { weights?: Partial<RiskWeights>; thresholds?: AutonomyBandThresholds }): RiskEngine;
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
risk:assess [ref] # default: diff do working tree vs. HEAD
|
|
73
|
+
risk:explain <assessment-id>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
// packages/policy/src/index.ts — extensão aditiva
|
|
78
|
+
export interface PolicyScope { /* ...campos existentes... */ readonly riskScoreRange?: readonly [number, number]; }
|
|
79
|
+
export interface PolicyRequest { /* ...campos existentes... */ readonly riskScore?: number; }
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## 5. Decisões e alternativas
|
|
83
|
+
|
|
84
|
+
**D1**: `risk:assess` recebe um **git ref opcional** (`risk:assess [ref]`), não uma string livre em
|
|
85
|
+
linguagem natural. A visão original e o §12 (CLI Plan) escrevem `risk:assess "<mudança>"`, que lido
|
|
86
|
+
literalmente sugeriria parsing de texto — incompatível com o NFR "nenhum fator depende de chamada de
|
|
87
|
+
LLM" e com AC-1 (fatores determinísticos). Sem `ref`, compara o working tree contra `HEAD` (mudança
|
|
88
|
+
não commitada ainda, o caso mais comum ao decidir política antes de commitar); com `ref`, compara
|
|
89
|
+
`<ref>^..<ref>`. Mesma resolução já dada a `adr:impact <id>` (recebe um id concreto, não prosa).
|
|
90
|
+
|
|
91
|
+
**D2**: assessments são persistidos em `.context/risk/<id>.json`, efêmero (fora do git, mesma
|
|
92
|
+
categoria de `.context/forja-runs.jsonl` — já ignorado pelo `.gitignore` existente, nenhuma mudança
|
|
93
|
+
de allowlist necessária, ao contrário de `constitution.json` que é fonte de verdade versionada).
|
|
94
|
+
`risk:explain` lê de volta esse arquivo. Alternativa rejeitada: nova tabela SQLite — violaria a NFR
|
|
95
|
+
"nenhuma tabela SQLite nova" desta spec (§6, redigida pelo próprio autor da spec) sem necessidade;
|
|
96
|
+
um assessment é um artefato de leitura pontual, não algo que precisa de índice/query relacional.
|
|
97
|
+
|
|
98
|
+
**D3**: `PolicyRequest.riskScore` é um `number` simples (0-100), não `ChangeRiskAssessment` completo
|
|
99
|
+
como o texto solto da visão original sugeria. `PolicyEngine` só precisa do score para casar
|
|
100
|
+
`riskScoreRange` — carregar o assessment inteiro obrigaria `packages/policy` a conhecer o shape de
|
|
101
|
+
`ChangeRiskAssessment`, violando AC-5 ("policy não importa `packages/engineering/risk`
|
|
102
|
+
diretamente") por tipo estrutural equivalente a import. Quem quiser o assessment completo já tem
|
|
103
|
+
`risk:explain <id>` ou chama `RiskEngine.assess()` diretamente antes de montar o `PolicyRequest`.
|
|
104
|
+
|
|
105
|
+
**D4**: fatores sem dado real (`historical_failure_rate` em cold start, `test_confidence` quando a
|
|
106
|
+
heurística de arquivo de teste não encontra nada) entram no cálculo com um valor neutro (0 para
|
|
107
|
+
histórico — "sem evidência de falha" não é o mesmo que "sem risco", mas é a leitura mais honesta
|
|
108
|
+
disponível; 0.5 para teste — literalmente "desconhecido") e `hasRealData: false`, nunca são
|
|
109
|
+
omitidos do score. `confidence` cai proporcionalmente (AC-3) em vez de o assessment inteiro falhar
|
|
110
|
+
ou mentir com 100% de confiança.
|
|
111
|
+
|
|
112
|
+
## 6. Dependências
|
|
113
|
+
|
|
114
|
+
- SPEC-032 (Engineering Graph) — `GraphLoop.impact()` para blast radius.
|
|
115
|
+
- SPEC-033 (Architecture Constitution) — `checkConstitution` para o fator de violação; roda com
|
|
116
|
+
zero regras (`architectureViolationCount: 0`) se `constitution.json` ainda não foi compilado,
|
|
117
|
+
não é erro bloqueante.
|
|
118
|
+
- `packages/adapter-sqlite.SqliteObservationStore` (já existente, sem migração nova).
|
|
119
|
+
|
|
120
|
+
## 7. Rollout
|
|
121
|
+
|
|
122
|
+
- [ ] Feature flag necessária? Não — comando novo, opt-in por natureza.
|
|
123
|
+
- [ ] Migração de dados existentes? Não.
|
|
124
|
+
- [ ] Doc/persona impactada? README (comandos novos), `docs/architecture/`.
|
|
125
|
+
|
|
126
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
127
|
+
|
|
128
|
+
Já registrado no apêndice de `specs/engineering-intelligence/spec.md`: se `risk:assess` sobre as 5
|
|
129
|
+
mudanças históricas do §8 do spec não ordenar de acordo com julgamento humano, os pesos/fórmula são
|
|
130
|
+
revisados antes de avançar para o Sprint 3 (Evidence Ledger, que agrega o que Risk já produziu).
|