forjajs 2.0.3 → 3.0.0

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