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,177 @@
|
|
|
1
|
+
# Spec: Engineering Intelligence / Engineering Twin (master)
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-031
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprints 1-3 (fundação); fases seguintes ficam em specs próprias
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0078](../../memory/90-decisions/0078-forjajs-3-engineering-control-plane.md)
|
|
9
|
+
|
|
10
|
+
> **Spec master.** Não é implementada diretamente — decompõe em
|
|
11
|
+
> [SPEC-032](../engineering-graph-extensions/spec.md) (Engineering Graph),
|
|
12
|
+
> [SPEC-033](../architecture-constitution/spec.md) (Architecture Constitution + drift),
|
|
13
|
+
> [SPEC-034](../change-risk-engine/spec.md) (Change Risk Engine) e
|
|
14
|
+
> [SPEC-035](../engineering-evidence-ledger/spec.md) (Evidence Ledger + façade `forja engineer`).
|
|
15
|
+
> Ver [`docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md`](../../docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md)
|
|
16
|
+
> para a auditoria completa, gap analysis e desenho técnico que fundamentam esta spec.
|
|
17
|
+
|
|
18
|
+
## 1. Problema
|
|
19
|
+
|
|
20
|
+
A Forja hoje orquestra *como* agentes de IA trabalham (processo, memória, aprovação, sandbox) mas
|
|
21
|
+
não entende *por que* o software que eles produzem existe, *se* o que produzem respeita a
|
|
22
|
+
arquitetura pretendida, *qual o risco* de uma mudança antes de ela acontecer, nem *quem/o quê*
|
|
23
|
+
produziu cada linha depois do fato. Essas perguntas hoje só têm resposta manual — um humano lendo
|
|
24
|
+
ADRs, olhando `git blame`, adivinhando risco. Para operar com autonomia supervisionada em escala
|
|
25
|
+
(múltiplos agentes, múltiplos projetos), essas respostas precisam ser estruturadas, auditáveis e
|
|
26
|
+
consultáveis por comando — não tribais.
|
|
27
|
+
|
|
28
|
+
## 2. Proposta de valor
|
|
29
|
+
|
|
30
|
+
A Forja passa a responder, de forma estruturada e com evidência: por que um código existe (SPEC/ADR
|
|
31
|
+
de origem), se uma mudança viola a arquitetura pretendida, qual o risco de uma mudança antes dela
|
|
32
|
+
acontecer, e quem/o quê a produziu. **GitHub guarda o código. A Forja guarda a engenharia.**
|
|
33
|
+
|
|
34
|
+
## 3. User stories
|
|
35
|
+
|
|
36
|
+
- **Como** sdd-architect, **quero** que uma decisão registrada em ADR vire uma regra que o sistema
|
|
37
|
+
verifica sozinho, **para que** "arquitetura documentada" e "arquitetura em vigor" nunca divirjam
|
|
38
|
+
em silêncio.
|
|
39
|
+
- **Como** governance, **quero** um score de risco explicável (não uma caixa-preta) antes de uma
|
|
40
|
+
mudança grande, **para que** eu saiba quando exigir revisão humana em vez de deixar autonomia
|
|
41
|
+
supervisionada seguir sozinha.
|
|
42
|
+
- **Como** desenvolvedor/consultor operando múltiplos projetos, **quero** uma única pergunta
|
|
43
|
+
(`forja engineer "<objetivo>"`) que já traga arquitetura, risco, ADRs relevantes e fluxo
|
|
44
|
+
recomendado, **para que** eu não precise consultar cinco comandos manualmente antes de começar.
|
|
45
|
+
|
|
46
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
47
|
+
|
|
48
|
+
- [x] AC-1: Engineering Graph (SPEC-032) extrai `ADR`/`SPEC` como nós de primeira classe, com
|
|
49
|
+
`status`/`documentStatus` e arestas `DERIVED_FROM`, **sem LLM** (extensão de
|
|
50
|
+
`extractDeterministicRelations`, mesmo padrão determinístico já existente).
|
|
51
|
+
- [x] AC-2: `forja architecture:compile`/`architecture:check`/`architecture:explain` (SPEC-033)
|
|
52
|
+
funcionam sobre pelo menos um ADR real deste repositório com `## Constraints` — validado
|
|
53
|
+
contra ADR-0078.
|
|
54
|
+
- [x] AC-3: `forja risk:assess [ref]` (SPEC-034) produz um score 0-100 com fatores nomeados e
|
|
55
|
+
`evidenceIds` — nunca um número sem explicação. (`[ref]`, não `"<mudança>"` livre — D1 de
|
|
56
|
+
`specs/change-risk-engine/plan.md`: um git ref é verificável, prosa livre exigiria parsing.)
|
|
57
|
+
- [x] AC-4: Risk assessment é **opcionalmente** consumível por `PolicyEngine` via
|
|
58
|
+
`PolicyScope.riskScoreRange`/`PolicyRequest.riskScore` (um `number`, não o assessment
|
|
59
|
+
inteiro) — `packages/policy` nunca importa `@forja/engineering-risk`.
|
|
60
|
+
- [x] AC-5: Evidence Ledger (SPEC-035) produz uma view agregada por run a partir de dados já
|
|
61
|
+
persistidos (`AuditRecord`/`ApprovalRequest`/`RuntimeRun`), sem nova fonte de verdade
|
|
62
|
+
primária.
|
|
63
|
+
- [x] AC-6 (revisado — ver nota): `forja engineer "<objetivo>"` compõe `ContextEngine` +
|
|
64
|
+
`GraphLoop` (ADRs/SPECs relevantes) + `architecture:check` + `RiskEngine` + fluxo
|
|
65
|
+
recomendado, sem reimplementar nenhum. **Não** compõe `DeterministicPlanner`/`PolicyEngine`
|
|
66
|
+
como o texto original desta AC previa — decisão registrada em
|
|
67
|
+
`specs/engineering-evidence-ledger/plan.md` D1: `forja engineer` roda **antes** de existir
|
|
68
|
+
um diff (orienta o início do trabalho), e tanto planejamento quanto decisão de política
|
|
69
|
+
exigem um plano/capability concretos que ainda não existem nesse momento. Compor os dois
|
|
70
|
+
"porque a AC pedia" teria sido invenção, não composição real — proibido por AC-3 de
|
|
71
|
+
SPEC-035.
|
|
72
|
+
- [x] AC-7: nenhum comando existente mudou de assinatura ou comportamento; toda extensão de
|
|
73
|
+
contrato (`documentStatus`, `riskScoreRange`/`riskScore`) foi aditiva — confirmado por
|
|
74
|
+
`npx tsc --noEmit` limpo e pela suíte de testes pré-existente intacta em cada PR.
|
|
75
|
+
|
|
76
|
+
## 5. Escopo
|
|
77
|
+
|
|
78
|
+
**Dentro** (Sprints 1-3, esta spec master):
|
|
79
|
+
- Engineering Graph: vocabulário de nós/arestas de engenharia + extratores determinísticos para
|
|
80
|
+
ADR/SPEC.
|
|
81
|
+
- Architecture Constitution: compile/check/explain, reaproveitando o motor de drift já em
|
|
82
|
+
construção em `specs/drift-sentinel`.
|
|
83
|
+
- Change Risk Engine: fórmula documentada, fatores configuráveis, integração opcional com Policy.
|
|
84
|
+
- Evidence Ledger: view agregada por run.
|
|
85
|
+
- Façade `forja engineer` (versão mínima: contexto + arquitetura + risco + ADRs relevantes +
|
|
86
|
+
fluxo recomendado — **sem** roteamento de agente/seleção de time, que depende de Agent
|
|
87
|
+
Identity/Reputation, fora de escopo aqui).
|
|
88
|
+
|
|
89
|
+
**Fora** (fases seguintes, cada uma com spec própria quando chegar a vez — ver
|
|
90
|
+
`plan.md` desta spec para a ordem):
|
|
91
|
+
- Agent Identity / Agent Reputation / Project Evals / Smart Routing (Fase 3 da visão original).
|
|
92
|
+
- Predictive Change Simulation (Fase 4).
|
|
93
|
+
- AI Code Provenance / `forja blame` / AI-SBOM (Fase 5).
|
|
94
|
+
- Agent Runtime Monitoring / Behavior Anomaly Engine (Fase 5).
|
|
95
|
+
- Learning Loop / Incident → Knowledge / Cross-project Intelligence (Fase 6).
|
|
96
|
+
- Autonomous Maintenance (Fase 7) — só arquitetura preparatória, nunca habilitação automática.
|
|
97
|
+
- Dashboard/visualização do Engineering Graph — core primeiro, UI depois, por princípio explícito
|
|
98
|
+
da visão recebida.
|
|
99
|
+
|
|
100
|
+
## 6. NFRs / restrições
|
|
101
|
+
|
|
102
|
+
- **Local-first**: nenhuma dependência de rede nova.
|
|
103
|
+
- **Determinismo antes de LLM**: extração de ADR/SPEC e cálculo de risco são determinísticos; LLM
|
|
104
|
+
entra só como sugestão opcional revisável por humano (nunca regra `active` direto).
|
|
105
|
+
- **Fail-closed em ambiguidade**: regra de Constitution mal-formada não vira regra `active`
|
|
106
|
+
silenciosamente — fica `proposed` até aprovação.
|
|
107
|
+
- **Compatibilidade**: zero breaking change nesta spec master; qualquer breaking change futuro tem
|
|
108
|
+
ADR próprio (ver ADR-0078, "Negativas/Trade-offs").
|
|
109
|
+
|
|
110
|
+
## 7. Riscos e mitigação
|
|
111
|
+
|
|
112
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
113
|
+
|---|---|---|---|
|
|
114
|
+
| Escopo da visão original (33 features) vazar para dentro desta spec master | Alta se não vigiado | Alta (nunca termina) | Escopo §5 explicitamente limitado a Sprints 1-3; fases seguintes exigem spec própria, não emenda desta |
|
|
115
|
+
| `packages/engineering` virar acoplamento cruzado entre architecture/risk/provenance/identity | Média | Média | `architecture` e `risk` não importam um ao outro (peers, sem acoplamento horizontal). Exceção única e intencional: `evidence` importa tipos de ambos — é o ponto de agregação por design (SPEC-035 AC-1), não um vazamento; import `type`-only, sem runtime coupling |
|
|
116
|
+
| Risk score sem uso real por falta de dado histórico (cold start) | Alta no início | Baixa | `confidence` do assessment reflete isso explicitamente — não é um bloqueador, é um dado honesto |
|
|
117
|
+
|
|
118
|
+
## 8. Métricas de sucesso
|
|
119
|
+
|
|
120
|
+
30 dias após Sprint 3: rodar `forja engineer "<mudança real deste repositório>"` produz uma saída
|
|
121
|
+
com ADRs corretos, risco plausível e nenhuma alucinação de arquitetura que não existe — validado
|
|
122
|
+
por revisão humana em pelo menos 3 mudanças reais consecutivas.
|
|
123
|
+
|
|
124
|
+
**Status na entrega dos Sprints 1-3** (validação imediata, não os 30 dias de uso real — essa
|
|
125
|
+
segunda parte só se acumula com o tempo): `forja engineer` já foi validado sobre um objetivo real
|
|
126
|
+
deste repositório (`specs/engineering-evidence-ledger/spec.md` §8), e `risk:assess` sobre 5 commits
|
|
127
|
+
reais com ordenação de risco aceita em revisão humana (`specs/change-risk-engine/spec.md` §8). Os
|
|
128
|
+
"pelo menos 3 mudanças reais consecutivas" ao longo de 30 dias de uso continuado ficam para quem
|
|
129
|
+
usar a ferramenta a partir daqui — não algo que esta entrega possa provar sozinha no dia do merge.
|
|
130
|
+
|
|
131
|
+
## Apêndice — plano de sprints (não é `plan.md` formal: esta spec ainda está em `draft`, e o
|
|
132
|
+
próprio gate de `spec:check` do Forja recusa `plan.md` antes de `spec: approved` — o rascunho de
|
|
133
|
+
sprints pedido na primeira entrega vive aqui até a aprovação formal, quando então vira `plan.md`
|
|
134
|
+
de verdade)
|
|
135
|
+
|
|
136
|
+
**Abordagem**: bottom-up a partir do Engineering Graph (SPEC-032), porque toda outra peça
|
|
137
|
+
(Constitution, Risk, Evidence) lê ou escreve nele. Cada sprint entrega um comando funcional real
|
|
138
|
+
sobre este próprio repositório antes de passar ao próximo.
|
|
139
|
+
|
|
140
|
+
| Sprint | Specs | Entrega | Prova de sucesso |
|
|
141
|
+
|---|---|---|---|
|
|
142
|
+
| **1** | SPEC-032, SPEC-033 | `ADR`/`SPEC` como nós de primeira classe; `architecture:compile`/`check` sobre `memory/90-decisions/` real, reaproveitando o motor do `drift-sentinel` (SPEC-030) | `architecture:check` neste repo aponta zero violação na linha de base e detecta uma violação injetada de propósito em teste |
|
|
143
|
+
| **2** | SPEC-034 | `risk:assess`/`risk:explain` funcionais; `RiskAssessor` opcionalmente consultado por `PolicyEngine` | score sobre um diff real deste repositório concorda com julgamento humano |
|
|
144
|
+
| **3** | SPEC-035 | view agregada de evidência por run; façade `forja engineer` (contexto + arquitetura + risco + ADRs + fluxo recomendado) | saída de `forja engineer` sobre um objetivo real seria usada sem edição para começar o trabalho |
|
|
145
|
+
|
|
146
|
+
Diagrama:
|
|
147
|
+
|
|
148
|
+
```text
|
|
149
|
+
Sprint 1 Sprint 2 Sprint 3
|
|
150
|
+
Engineering Graph → Change Risk Engine → Evidence Ledger
|
|
151
|
+
Architecture (consome Graph + (agrega dados já
|
|
152
|
+
Constitution Architecture) persistidos)
|
|
153
|
+
│ │ │
|
|
154
|
+
└───────────────────────┴───────────────────────┘
|
|
155
|
+
│
|
|
156
|
+
forja engineer
|
|
157
|
+
(façade, Sprint 3)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Decisão registrada (D1): ordem Graph → Constitution → Risk → Evidence, não a ordem alfabética/de
|
|
161
|
+
prioridade P0 da visão original — cada peça depende de contratos que a anterior estabiliza;
|
|
162
|
+
implementar em paralelo geraria retrabalho. Não é estrutural o suficiente para ADR própria (a
|
|
163
|
+
decisão estrutural maior — 3.0 vs. 2.x — já está em ADR-0078).
|
|
164
|
+
|
|
165
|
+
Dependências: specs SPEC-032 a SPEC-035 (todas draft); SPEC-029 (cost-aware-autonomy-budget, done)
|
|
166
|
+
e SPEC-030 (drift-sentinel, base do `architecture:check`) já em implementação nesta mesma janela.
|
|
167
|
+
Nenhum pacote npm novo.
|
|
168
|
+
|
|
169
|
+
Rollout: feature flags `features.engineeringGraph`/`architectureConstitution`/`changeRiskEngine`
|
|
170
|
+
default `false` até cada sprint fechar seus próprios testes; nenhuma migração de dado existente
|
|
171
|
+
(extensão aditiva de vocabulário); docs impactadas — `docs/architecture/`, `AGENTS.md` (papel
|
|
172
|
+
opcional "architecture reviewer"), `DOC-MAP.md`.
|
|
173
|
+
|
|
174
|
+
Kill criteria: se `architecture:check` gerar mais falso-positivo que sinal real sobre este próprio
|
|
175
|
+
repositório depois do Sprint 1, o motor é redesenhado antes de avançar para o Sprint 2 — não
|
|
176
|
+
empilhamos risco em cima de arquitetura que não detecta corretamente. Falta de histórico para
|
|
177
|
+
`confidence` alta no Risk Engine (Sprint 2) é limitação documentada, não kill criteria.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Plan: Learning Loop — Registro de Incidentes + Sugestão por Similaridade
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
Nenhum pacote novo em `packages/engineering` — `GraphNode.type` já é vocabulário livre e
|
|
10
|
+
`GraphLoop.upsertNode`/`addEvidence` já fazem tudo que o registro precisa. `scripts/incident.ts` é
|
|
11
|
+
puramente um adapter: grava um nó `Incident` + evidência via `GraphLoop` (mesmo `SqliteGraphStore`
|
|
12
|
+
compartilhado de `adr:*`/`architecture:*`), e implementa o matching por palavra-chave de
|
|
13
|
+
`incident:similar` diretamente (função pequena e local, não uma dependência de
|
|
14
|
+
`GraphLoop.contextRecords` — D1).
|
|
15
|
+
|
|
16
|
+
## 2. Módulos afetados
|
|
17
|
+
|
|
18
|
+
| Caminho | Mudança | Risco |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `scripts/incident.ts` | novo — `incident:record`/`:list`/`:similar` | Baixo — composição de `GraphLoop` já existente |
|
|
21
|
+
| `lib/core/registry.ts` | 3 comandos novos | Baixo |
|
|
22
|
+
| `test/incident-cli.test.js` (novo) | fixture isolada, ciclo completo | — |
|
|
23
|
+
|
|
24
|
+
## 3. Contratos
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
incident:record --title <t> [--description <d>]
|
|
28
|
+
incident:list
|
|
29
|
+
incident:similar "<busca>"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## 4. Decisões
|
|
33
|
+
|
|
34
|
+
**D1**: `incident:similar` implementa seu próprio matching por palavra-chave local (mesmo estilo de
|
|
35
|
+
`GraphLoop.contextRecords`: normaliza pra minúsculo, quebra em termos, conta sobreposição,
|
|
36
|
+
`relevance = matches / totalTerms`), em vez de reaproveitar `contextRecords` diretamente.
|
|
37
|
+
`contextRecords` casa contra **arestas** (`from.label + type + to.label`); nós `Incident` desta
|
|
38
|
+
versão não têm aresta nenhuma (§5 do spec, "Fora" — linkagem fica pra depois), então
|
|
39
|
+
`contextRecords` nunca encontraria um nó sem aresta. Reimplementar o mesmo *estilo* de matching
|
|
40
|
+
sobre nós (não arestas) é a única forma de a busca funcionar nesta versão, sem duplicar a lógica de
|
|
41
|
+
extração de relação que `contextRecords` de fato tem (essa parte não é copiada, só o padrão de
|
|
42
|
+
scoring por sobreposição de termos, que é trivial e não vale abstrair numa função compartilhada por
|
|
43
|
+
uma linha de código).
|
|
44
|
+
|
|
45
|
+
**D2**: `Incident.label` carrega `título + '\n' + descrição` concatenados (não um campo separado —
|
|
46
|
+
`GraphNodeSpec` não tem campo de descrição livre além de `label`). Alternativa considerada: guardar
|
|
47
|
+
a descrição como uma segunda `Evidence`/nota — rejeitada por adicionar uma peça de dado sem
|
|
48
|
+
necessidade real nesta versão mínima; `label` já é uma string livre, suficiente pro matching de
|
|
49
|
+
AC-3.
|
|
50
|
+
|
|
51
|
+
## 5. Rollout
|
|
52
|
+
|
|
53
|
+
Sem migração, sem feature flag.
|
|
54
|
+
|
|
55
|
+
## 6. Kill criteria
|
|
56
|
+
|
|
57
|
+
Já coberto pelo mesmo princípio das specs anteriores — se `incident:similar` não corresponder a
|
|
58
|
+
julgamento humano sobre os incidentes de teste, o scoring é revisado antes de qualquer extensão
|
|
59
|
+
futura (linkagem de grafo, cross-project).
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Spec: Learning Loop — Registro de Incidentes + Sugestão por Similaridade
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-041
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 9 (primeiro sprint da Fase 6 da visão original — Learning Loop /
|
|
8
|
+
Incident → Knowledge; Cross-project Intelligence fica de fora, ver §5)
|
|
9
|
+
- **ADRs relacionadas**: ADR-0078; depende de `packages/graph.GraphLoop` (já existente —
|
|
10
|
+
`upsertNode`/`addEvidence`/`upsertEdge` reaproveitados sem mudança)
|
|
11
|
+
|
|
12
|
+
> Gap analysis original (`docs/architecture/...` §3): "`GraphLoop` + evidência já dão a base; falta
|
|
13
|
+
> o tipo de nó `Incident` e o fluxo de sugestão (nunca aplicação automática) — Construir,
|
|
14
|
+
> reaproveitando grafo + approvals." `GraphNode.type` já é vocabulário livre (o próprio doc já lista
|
|
15
|
+
> `Incident` em `ENGINEERING_NODE_TYPES` §6) — não precisa de contrato novo, só de um adapter que
|
|
16
|
+
> grava/consulta esse tipo.
|
|
17
|
+
|
|
18
|
+
## 1. Problema
|
|
19
|
+
|
|
20
|
+
Nada registra incidentes de forma consultável, nem sugere "isso já aconteceu antes" quando um novo
|
|
21
|
+
problema se parece com um antigo — cada incidente é resolvido isoladamente, sem acumular
|
|
22
|
+
conhecimento reconsultável.
|
|
23
|
+
|
|
24
|
+
## 2. Proposta de valor
|
|
25
|
+
|
|
26
|
+
`forja incident:record --title <t> [--description <d>]` registra um incidente no Engineering Graph
|
|
27
|
+
já existente; `forja incident:similar "<busca>"` sugere incidentes passados parecidos — sugestão
|
|
28
|
+
por palavra-chave, determinística, nunca aplica nada sozinha.
|
|
29
|
+
|
|
30
|
+
## 3. User stories
|
|
31
|
+
|
|
32
|
+
- **Como** governance, **quero** registrar um incidente de forma estruturada, **para que** ele vire
|
|
33
|
+
conhecimento consultável, não conhecimento tribal.
|
|
34
|
+
- **Como** desenvolvedor investigando um problema, **quero** ver incidentes parecidos já resolvidos,
|
|
35
|
+
**para que** eu não resolva o mesmo problema do zero toda vez.
|
|
36
|
+
|
|
37
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
38
|
+
|
|
39
|
+
- [x] AC-1: `forja incident:record --title <t> [--description <d>]` grava um nó `Incident` real no
|
|
40
|
+
Engineering Graph (`GraphLoop.upsertNode`+`addEvidence`, já existentes) — mesmo armazenamento
|
|
41
|
+
compartilhado já usado por `adr:*`/`architecture:*` (`SqliteGraphStore`), sem tabela nova.
|
|
42
|
+
- [x] AC-2: `forja incident:list` lista os incidentes registrados, mais recentes primeiro.
|
|
43
|
+
- [x] AC-3: `forja incident:similar "<busca>"` classifica incidentes registrados por sobreposição de
|
|
44
|
+
palavras-chave contra título+descrição — determinístico (mesmo estilo de matching já usado em
|
|
45
|
+
`GraphLoop.contextRecords`), sem LLM, sem inventar semântica que o texto não sustenta.
|
|
46
|
+
- [x] AC-4: **nunca aplicação automática** — nenhum comando desta spec chama `PolicyEngine`,
|
|
47
|
+
modifica arquivo, ou sugere uma correção como se fosse certeza. `incident:similar` é sempre
|
|
48
|
+
leitura/sugestão, nunca decisão.
|
|
49
|
+
- [x] AC-5: incidente sem nenhuma busca ainda registrada devolve lista vazia (não erro) em
|
|
50
|
+
`incident:similar`.
|
|
51
|
+
|
|
52
|
+
## 5. Escopo
|
|
53
|
+
|
|
54
|
+
**Dentro**: `incident:record`/`:list`/`:similar` — registro + sugestão por palavra-chave.
|
|
55
|
+
|
|
56
|
+
**Fora** (spec própria futura, mesmo princípio de escopo já usado nas specs anteriores):
|
|
57
|
+
- Vincular automaticamente um incidente a ADRs/arquivos/evidência (`--related-adr` etc.) — versão
|
|
58
|
+
mínima desta spec não faz linkagem de grafo além do próprio nó `Incident`+evidência de quem
|
|
59
|
+
registrou; linkagem exigiria resolver ids de nós já indexados (mesmo custo de reindexação de
|
|
60
|
+
`adr:*`), fora do escopo desta primeira entrega.
|
|
61
|
+
- "Lições aprendidas" geradas automaticamente (resumo/causa raiz sugerida por LLM) — proibido pelo
|
|
62
|
+
mesmo princípio de "determinístico antes de LLM" de toda a fundação; um humano escreve a
|
|
63
|
+
descrição, o sistema só indexa e sugere por palavra-chave.
|
|
64
|
+
- Cross-project Intelligence (correlacionar incidentes entre múltiplos projetos/repositórios) — este
|
|
65
|
+
workspace é de um único projeto; múltiplos projetos exigem uma fonte de dado que não existe hoje
|
|
66
|
+
(workspace compartilhado entre repos), fora de escopo.
|
|
67
|
+
|
|
68
|
+
## 6. NFRs / restrições
|
|
69
|
+
|
|
70
|
+
- Determinístico — nenhum LLM/ML em nenhum ponto; matching por palavra-chave, mesmo estilo já usado
|
|
71
|
+
em `GraphLoop.contextRecords`.
|
|
72
|
+
- Zero migration SQLite nova — reaproveita `SqliteGraphStore` já existente.
|
|
73
|
+
- Evidência de quem registrou (`source: 'forja.cli'`, fonte confiável já reconhecida por
|
|
74
|
+
`GraphLoop.addEvidence` — ver `DEFAULT_TRUSTED_EVIDENCE_SOURCES`) mantém o nó `verified`, não
|
|
75
|
+
`inferred` — é um humano registrando via CLI, ação deliberada, não uma inferência de agente.
|
|
76
|
+
|
|
77
|
+
## 7. Riscos e mitigação
|
|
78
|
+
|
|
79
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
80
|
+
|---|---|---|---|
|
|
81
|
+
| `incident:similar` prometer entendimento semântico que não tem (é só palavra-chave) | Média (nome "similar" sugere mais) | Baixa (decepção, não dado errado) | AC-3 explícito; saída indica o score de sobreposição, não uma alegação de "causa igual" |
|
|
82
|
+
| Incidentes virarem uma lista sem uso (write-only) | Média se a busca não for útil | Baixa | `incident:similar` é o consumidor imediato — não é write-only por design |
|
|
83
|
+
|
|
84
|
+
## 8. Métricas de sucesso
|
|
85
|
+
|
|
86
|
+
Registrar 2+ incidentes reais ou sintéticos documentados como tais, com um par claramente parecido
|
|
87
|
+
e um claramente diferente, e confirmar que `incident:similar` ordena corretamente — revisão humana,
|
|
88
|
+
mesma metodologia das specs anteriores.
|
|
89
|
+
|
|
90
|
+
**Validado** (`test/incident-cli.test.js`): 3 incidentes registrados, 2 deles reais achados desta
|
|
91
|
+
mesma sessão (SQLite writes não em lote, de SPEC-032; `sandboxEnvironment` sem `HOME`, de SPEC-038)
|
|
92
|
+
mais 1 claramente não relacionado (build de frontend). `incident:similar` de cada busca achou
|
|
93
|
+
exatamente o incidente correspondente, sem falso-positivo do incidente não relacionado.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Tasks: Learning Loop — Registro de Incidentes + Sugestão por Similaridade
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — `scripts/incident.ts`: record/list/similar
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: M
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `scripts/incident.ts`, `lib/core/registry.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `incident:record` grava nó `Incident` + evidência (`source: 'forja.cli'`) via `GraphLoop`,
|
|
17
|
+
sem migration nova
|
|
18
|
+
- [ ] `incident:list` lista mais recentes primeiro
|
|
19
|
+
- [ ] `incident:similar` implementa o matching de D1, nunca aplica nada (AC-4)
|
|
20
|
+
- [ ] `forja tools:doctor` continua verde
|
|
21
|
+
|
|
22
|
+
## T2 — prova sobre incidentes reais/sintéticos documentados
|
|
23
|
+
- **Owner**: worker
|
|
24
|
+
- **Estimativa**: P
|
|
25
|
+
- **Depende de**: T1
|
|
26
|
+
- **Paths**: `test/incident-cli.test.js` (novo)
|
|
27
|
+
- **Done quando**:
|
|
28
|
+
- [ ] 3 incidentes registrados (2 parecidos, 1 diferente), `incident:similar` ordena
|
|
29
|
+
corretamente
|
|
30
|
+
- [ ] `incident:similar` sem nenhum incidente registrado devolve vazio, não erro (AC-5)
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Handoffs entre agentes
|
|
35
|
+
|
|
36
|
+
T1 → T2 sequencial. Sem handoff de papel.
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Plan: Predictive Change Simulation
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
`scripts/simulate.ts`, adapter puro de composição (mesmo padrão de `scripts/engineer.ts`) — nenhum
|
|
10
|
+
pacote novo em `packages/engineering`, porque não há lógica de domínio nova aqui, só orquestração
|
|
11
|
+
de engines já existentes (`SandboxEngine`, `checkConstitution`, `assessRisk`).
|
|
12
|
+
|
|
13
|
+
Ciclo do sandbox usado (D1): `create({sourceRef: ref})` → `prepare` → `execute(testCommand)` →
|
|
14
|
+
`reject` → `destroy`. **Não** usa `validate`/`diff`/`promote` do `SandboxEngine` — esses passos
|
|
15
|
+
existem pra "modifiquei o worktree, quero decidir se aplico as mudanças na árvore real"; aqui o
|
|
16
|
+
worktree já nasce checked out no `ref` (nada é modificado depois), e a árvore real nunca deveria
|
|
17
|
+
receber nada desta simulação. `reject()` aceita o estado `'validating'` (onde a sessão fica logo
|
|
18
|
+
após `execute()`) — não precisa passar por `validate()` pra chegar lá. Isso torna
|
|
19
|
+
"nunca promove" uma propriedade estrutural do código (a função `promote()` simplesmente nunca é
|
|
20
|
+
chamada em lugar nenhum deste arquivo), não uma disciplina que dependeria de lembrar de não chamar.
|
|
21
|
+
|
|
22
|
+
## 2. Módulos afetados
|
|
23
|
+
|
|
24
|
+
| Caminho | Mudança | Risco |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| `scripts/simulate.ts` | novo — `forja simulate <ref>` | Médio — orquestra sandbox real + grafo temporário, mas cada peça já existe e testada |
|
|
27
|
+
| `lib/core/registry.ts` | 1 comando novo | Baixo |
|
|
28
|
+
| `test/simulate-cli.test.js` (novo) | fixture git isolada, verifica não-promoção e destruição do worktree | — |
|
|
29
|
+
|
|
30
|
+
## 3. Diagrama de fluxo
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
forja simulate <ref> [--command "npm test"]
|
|
34
|
+
│
|
|
35
|
+
├─► SandboxEngine.create({sourceRef: ref}) — GitWorktreeBackend, worktree isolado real
|
|
36
|
+
├─► SandboxEngine.prepare
|
|
37
|
+
├─► SandboxEngine.execute({command}) — roda o teste DENTRO do worktree
|
|
38
|
+
│ │
|
|
39
|
+
│ ▼ (sessão em 'validating')
|
|
40
|
+
├─► SqliteMigrationRunner sobre um SQLite TEMPORÁRIO (mkdtemp, não getWorkspaceDbPath)
|
|
41
|
+
├─► GraphIndexer.sync(GitGraphDocumentSource(session.root)) — indexa o worktree isolado
|
|
42
|
+
├─► checkConstitution(constitution.json do worktree, arestas do grafo temporário)
|
|
43
|
+
├─► buildRiskInput(changedFiles, database-temporário) + assessRisk
|
|
44
|
+
│
|
|
45
|
+
├─► SandboxEngine.reject(session.id) — nunca promote()
|
|
46
|
+
└─► SandboxEngine.destroy(session.id) — sempre, mesmo em erro (try/finally)
|
|
47
|
+
│
|
|
48
|
+
▼
|
|
49
|
+
SimulationReport { testResult, architectureCheck, risk, recommendation }
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 4. Contratos (CLI/Schema)
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// scripts/simulate.ts
|
|
56
|
+
interface SimulationReport {
|
|
57
|
+
readonly ref: string;
|
|
58
|
+
readonly changedFiles: readonly string[];
|
|
59
|
+
readonly testCommand: string;
|
|
60
|
+
readonly testResult: { readonly exitCode: number; readonly durationMs: number; readonly passed: boolean };
|
|
61
|
+
readonly architectureCheck: ArchitectureCheckReport | { readonly note: string };
|
|
62
|
+
readonly risk: ChangeRiskAssessment;
|
|
63
|
+
readonly recommendation: 'promote' | 'review' | 'discard';
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
simulate <ref> [--command "npm test"] [--json]
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## 5. Decisões e alternativas
|
|
72
|
+
|
|
73
|
+
**D1**: ciclo `create→prepare→execute→reject→destroy`, sem `validate`/`diff`/`promote` — ver §1.
|
|
74
|
+
Alternativa considerada: usar o ciclo completo de `runSandboxedCapability` — rejeitada porque esse
|
|
75
|
+
helper foi desenhado pra capabilities que **modificam** o worktree via `work()` e depois decidem
|
|
76
|
+
promover; aqui o "trabalho" é só checkout+teste, sem modificação, e a promoção nunca deveria
|
|
77
|
+
acontecer — usar o ciclo completo introduziria um caminho de código (`promote`) que não deveria
|
|
78
|
+
nunca ser exercitado, risco desnecessário pro que AC-3 exige.
|
|
79
|
+
|
|
80
|
+
**D2**: `changedFiles` vem de `git diff --name-only HEAD <ref>` (reaproveita
|
|
81
|
+
`lib/core/risk-collect.ts.changedFiles`, mesma função de `risk:assess`/`forja engineer`) — rodado
|
|
82
|
+
**antes** de criar o sandbox, contra a árvore real (só leitura, `git diff` não modifica nada).
|
|
83
|
+
|
|
84
|
+
**D3**: grafo + banco da simulação são **completamente isolados** do workspace real — SQLite em
|
|
85
|
+
`fs.mkdtempSync`, apontando `FORJA_GRAPH_ROOT` pro `session.root` só durante a chamada de
|
|
86
|
+
`buildRiskInput`/`checkConstitution` (restaurado no `finally`, mesmo em exceção). Alternativa
|
|
87
|
+
rejeitada: reaproveitar `getWorkspaceDbPath()` — violaria AC-2/NFR explicitamente (contaminaria o
|
|
88
|
+
grafo persistente com o estado de um ref que pode nunca ser integrado).
|
|
89
|
+
|
|
90
|
+
**D4**: `recommendation` — `discard` se o teste falhar (hard gate); senão `review` se houver
|
|
91
|
+
violação de arquitetura `active` OU `risk.autonomyBand` for `supervised`/`human_in_the_loop`;
|
|
92
|
+
senão `promote`. Mesma filosofia de "informa, não decide" de `RiskEngine` (SPEC-034 D3) —
|
|
93
|
+
`forja simulate` nunca aplica a mudança sozinho independente da recomendação.
|
|
94
|
+
|
|
95
|
+
## 6. Dependências
|
|
96
|
+
|
|
97
|
+
- SPEC-033 (`checkConstitution`), SPEC-034 (`assessRisk`/`buildRiskInput`, `lib/core/risk-collect.ts`)
|
|
98
|
+
— reaproveitados sem mudança.
|
|
99
|
+
- `packages/sandbox.SandboxEngine`/`packages/adapter-git.GitWorktreeBackend` — já existentes.
|
|
100
|
+
|
|
101
|
+
## 7. Rollout
|
|
102
|
+
|
|
103
|
+
Sem migração, sem feature flag — comando novo, opt-in.
|
|
104
|
+
|
|
105
|
+
## 8. Kill criteria
|
|
106
|
+
|
|
107
|
+
Se a recomendação não corresponder a julgamento humano sobre um ref real (§8 do spec), os pesos de
|
|
108
|
+
D4 são revisados antes de qualquer consumo automático futuro (fora de escopo desta spec de
|
|
109
|
+
qualquer forma, §5 "Fora").
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Spec: Predictive Change Simulation
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-038
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 6 (Fase 4 da visão original)
|
|
8
|
+
- **ADRs relacionadas**: ADR-0078; depende de SPEC-033 (`checkConstitution`), SPEC-034
|
|
9
|
+
(`assessRisk`/`buildRiskInput`) — reaproveitados, não recalculados
|
|
10
|
+
|
|
11
|
+
> Gap analysis original (`docs/architecture/...` §3): `SandboxEngine` + `GitWorktreeBackend` +
|
|
12
|
+
> `runSandboxedCapability` "já são exatamente 'aplicar em worktree isolado, testar, decidir
|
|
13
|
+
> promover ou descartar'" — **compor** sandbox + risk engine + architecture:check, não construir
|
|
14
|
+
> nada novo. Esta spec é essa composição.
|
|
15
|
+
|
|
16
|
+
## 1. Problema
|
|
17
|
+
|
|
18
|
+
Hoje, avaliar se um ref/branch proposto é seguro pra integrar exige checkout manual, rodar teste
|
|
19
|
+
manualmente, rodar `architecture:check`/`risk:assess` manualmente, e cruzar os três resultados na
|
|
20
|
+
cabeça. Nenhum comando único simula "e se essa mudança fosse aplicada" com isolamento real e
|
|
21
|
+
resposta estruturada.
|
|
22
|
+
|
|
23
|
+
## 2. Proposta de valor
|
|
24
|
+
|
|
25
|
+
`forja simulate <ref> [--command "npm test"]` aplica o `ref` num worktree git isolado (nunca a
|
|
26
|
+
árvore real), roda o comando de teste, computa `architecture:check`+`risk:assess` contra o estado
|
|
27
|
+
resultante, e devolve uma recomendação (`promote`/`review`/`discard`) — sempre destruindo o
|
|
28
|
+
worktree ao final, nunca promovendo automaticamente.
|
|
29
|
+
|
|
30
|
+
## 3. User stories
|
|
31
|
+
|
|
32
|
+
- **Como** governance, **quero** simular uma mudança antes de integrá-la, **para que** eu veja
|
|
33
|
+
teste+arquitetura+risco combinados sem tocar a árvore real nem rodar três comandos manualmente.
|
|
34
|
+
|
|
35
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
36
|
+
|
|
37
|
+
- [x] AC-1: `forja simulate <ref>` cria um worktree git isolado no `ref` (via `SandboxEngine` +
|
|
38
|
+
`GitWorktreeBackend`, já existentes — nenhum motor de isolamento novo), roda o comando de
|
|
39
|
+
teste (`--command`, default `npm test`) dentro dele via `sandbox.execute()`.
|
|
40
|
+
- [x] AC-2: `architecture:check`/`risk:assess` rodam contra o **estado do worktree isolado**
|
|
41
|
+
(reaproveitando `checkConstitution`/`buildRiskInput` já existentes — nenhuma lógica de
|
|
42
|
+
violação/risco reimplementada), usando um SQLite temporário próprio da simulação — **nunca**
|
|
43
|
+
o workspace real (evita contaminar o Engineering Graph persistente com estado de um ref que
|
|
44
|
+
pode nunca ser integrado).
|
|
45
|
+
- [x] AC-3: o worktree é **sempre destruído** ao final (sucesso, falha de teste, ou exceção) —
|
|
46
|
+
`forja simulate` nunca chama `sandbox.promote()`; a única escrita na árvore real é a remoção
|
|
47
|
+
do próprio worktree. Verificável: `git worktree list` antes/depois idêntico.
|
|
48
|
+
- [x] AC-4: recomendação (`promote`/`review`/`discard`) é determinística a partir de teste+
|
|
49
|
+
arquitetura+risco (regra documentada em código e no plan) — nunca decide sozinha (não chama
|
|
50
|
+
`PolicyEngine`, não integra nada), é leitura, mesmo princípio de `RiskEngine`/SPEC-034 D3.
|
|
51
|
+
- [x] AC-5: `--json` produz saída estruturada; texto legível por padrão.
|
|
52
|
+
|
|
53
|
+
## 5. Escopo
|
|
54
|
+
|
|
55
|
+
**Dentro**: `forja simulate <ref> [--command <cmd>] [--json]`, composição de `SandboxEngine` +
|
|
56
|
+
`checkConstitution` + `assessRisk`.
|
|
57
|
+
|
|
58
|
+
**Fora**: aplicação automática (`sandbox.promote()` nunca é chamado — essa decisão continua manual,
|
|
59
|
+
via os fluxos normais de merge/PR); simular a partir de um patch/diff textual solto (só refs git,
|
|
60
|
+
mesmo princípio de `risk:assess`/SPEC-034 D1 — verificável, não texto livre); múltiplos comandos de
|
|
61
|
+
teste em paralelo (um `--command` por vez, nesta versão).
|
|
62
|
+
|
|
63
|
+
## 6. NFRs / restrições
|
|
64
|
+
|
|
65
|
+
- Isolamento real: nenhuma escrita na árvore/branch atual além do worktree (que é sempre removido).
|
|
66
|
+
- SQLite temporário e descartável — zero persistência cross-run do Engineering Graph do ref
|
|
67
|
+
simulado.
|
|
68
|
+
- Determinístico: nenhum LLM em nenhum ponto.
|
|
69
|
+
|
|
70
|
+
## 7. Riscos e mitigação
|
|
71
|
+
|
|
72
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
73
|
+
|---|---|---|---|
|
|
74
|
+
| Simulação vazar pro Engineering Graph real | Média se não isolado explicitamente | Alta (grafo persistente contaminado com ref nunca integrado) | AC-2: SQLite temporário próprio, nunca `getWorkspaceDbPath()` |
|
|
75
|
+
| `forja simulate` promover por engano | Baixa (mesmo padrão de `runSandboxedCapability`) | Muito alta (mudaria a árvore real sem revisão) | AC-3: nenhuma chamada a `sandbox.promote()` em todo o código; teste de CLI verifica `git worktree list` antes/depois |
|
|
76
|
+
| Comando de teste do projeto não ser `npm test` | Média (todo projeto é diferente) | Baixa | `--command` configurável, `npm test` é só o default |
|
|
77
|
+
|
|
78
|
+
## 8. Métricas de sucesso
|
|
79
|
+
|
|
80
|
+
Simular um ref real deste repositório (ex.: um commit já mergeado, comparado contra seu pai) produz
|
|
81
|
+
teste+arquitetura+risco coerentes com o que se sabe sobre aquela mudança — revisão humana, mesma
|
|
82
|
+
metodologia de SPEC-034/036/037 §8.
|
|
83
|
+
|
|
84
|
+
**Validado**: `forja simulate <commit real deste repositório> --command "node --test
|
|
85
|
+
test/risk-engine.test.js"` — teste passou, `architecture:check` achou a regra active real (0
|
|
86
|
+
violações, coerente com o estado real do repositório), risco 18/100 (`autonomous`), recomendação
|
|
87
|
+
`promote`. `git worktree list`/`git status` idênticos antes/depois (AC-3 confirmado sobre dado
|
|
88
|
+
real, não só fixture).
|
|
89
|
+
|
|
90
|
+
**Achados reais corrigidos durante a implementação (não adiados)**:
|
|
91
|
+
|
|
92
|
+
1. **`sandboxEnvironment()` não passava `HOME`/`USERPROFILE`** (`packages/adapter-git/src/index.ts`
|
|
93
|
+
— código pré-existente, não escrito nesta spec, mas exposto por ela: nenhum consumidor anterior
|
|
94
|
+
do sandbox rodava um comando dependente de resolver `HOME`). `npm test` como comando de teste
|
|
95
|
+
travava indefinidamente com o ambiente restrito por padrão — sem `HOME`, `npm` não consegue
|
|
96
|
+
resolver seu diretório de config/cache e trava em vez de falhar rápido (reproduzido
|
|
97
|
+
isoladamente com `env -i` fora do sandbox pra confirmar a causa antes de mexer no código).
|
|
98
|
+
Corrigido adicionando os dois ao allowlist fixo — nenhum dos dois é segredo, e o teste "runner
|
|
99
|
+
não herda secrets do ambiente por padrão" continua passando (cobre uma env var arbitrária do
|
|
100
|
+
processo host, não este allowlist).
|
|
101
|
+
2. **Rodar `--command "npm test"` (a suíte inteira, 400+ testes) contra este próprio repositório é
|
|
102
|
+
lento e inconsistente neste ambiente sandboxado** — mesma categoria de achado já documentada em
|
|
103
|
+
SPEC-032 (SQLite não em lote) e SPEC-034 (reindexação do grafo real): I/O pesado sob este
|
|
104
|
+
sandbox específico não é confiável dentro de um timeout razoável. Não é um bug em `forja
|
|
105
|
+
simulate` (a mesma suíte roda em ~10s fora de um worktree recém-criado, sem cache de
|
|
106
|
+
dependências); a validação real do §8 usou um comando de teste mais leve por esse motivo — não
|
|
107
|
+
um limite estrutural de `forja simulate`.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Tasks: Predictive Change Simulation
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — `scripts/simulate.ts`: sandbox real + grafo temporário + recomendação
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: G
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `scripts/simulate.ts`, `lib/core/registry.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `SandboxEngine.create({sourceRef: ref})` → `prepare` → `execute` → `reject` → `destroy`
|
|
17
|
+
(D1) — `promote()` nunca chamado em nenhum caminho, incluindo erro
|
|
18
|
+
- [ ] SQLite/grafo da simulação são temporários (`mkdtemp`), nunca `getWorkspaceDbPath()` (D3)
|
|
19
|
+
- [ ] `checkConstitution`/`assessRisk` rodam contra o worktree isolado, reaproveitando
|
|
20
|
+
`lib/core/risk-collect.ts`
|
|
21
|
+
- [ ] `recommendation` segue a regra de D4
|
|
22
|
+
- [ ] worktree sempre destruído mesmo se o teste falhar ou o processo lançar exceção
|
|
23
|
+
(try/finally)
|
|
24
|
+
- [ ] `forja tools:doctor` continua verde
|
|
25
|
+
|
|
26
|
+
## T2 — prova de isolamento + prova sobre ref real
|
|
27
|
+
- **Owner**: worker
|
|
28
|
+
- **Estimativa**: M
|
|
29
|
+
- **Depende de**: T1
|
|
30
|
+
- **Paths**: `test/simulate-cli.test.js` (novo)
|
|
31
|
+
- **Done quando**:
|
|
32
|
+
- [ ] fixture git isolada: `git worktree list` antes/depois de `forja simulate` idêntico (AC-3)
|
|
33
|
+
- [ ] teste com comando de teste que falha → `recommendation: 'discard'`
|
|
34
|
+
- [ ] teste com violação de arquitetura injetada → `recommendation: 'review'`
|
|
35
|
+
- [ ] simulação de um ref real deste repositório (§8 do spec) documentada no spec.md
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Handoffs entre agentes
|
|
40
|
+
|
|
41
|
+
T1 → T2 sequencial. Sem handoff de papel.
|