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,121 @@
1
+ # Plan: Engineering Evidence Ledger + `forja engineer` (façade)
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-01
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ Dois entregáveis pequenos, ambos composição pura sobre o que já existe — nenhuma tabela SQLite
10
+ nova, nenhuma lógica de decisão nova:
11
+
12
+ 1. `packages/engineering/evidence` — `buildEvidenceLedger(input)`, função pura que recebe um
13
+ `RuntimeRun` + `AuditRecord[]`/`ApprovalRequest[]` já filtrados + `ArchitectureCheckReport`/
14
+ `ChangeRiskAssessment` opcionais e devolve o JSON agregado (`run/intent/agent/risk/
15
+ architectureCheck/tests/approvals/commit`). `scripts/evidence.ts` é o adapter (`evidence:show
16
+ <run-id>`) que busca esses dados reais via `SqliteRuntimeRunStore`/`SqliteAuditStore`/
17
+ `ApprovalLedger`.
18
+ 2. `scripts/engineer.ts` — `forja engineer "<objetivo>"`, façade que chama, nesta ordem:
19
+ `ContextEngine.build()` (grafo, mesmo padrão de `scripts/demo-autonomy.ts`) →
20
+ `GraphLoop.contextRecords(objetivo)` filtrado a nós ADR/SPEC (SPEC-032, reaproveitado, não uma
21
+ busca nova) → `architecture:check` (não escopado — antes de haver diff, não há arquivo pra
22
+ escopar; ver D1) → `RiskEngine.assess()` (só com `--ref`; ver D1) → fluxo recomendado, parseado
23
+ de `docs/fluxo.md` (D2 — parser, não cópia hardcoded).
24
+
25
+ ## 2. Módulos afetados
26
+
27
+ | Caminho | Mudança | Risco |
28
+ |---|---|---|
29
+ | `packages/engineering/evidence/src/index.ts` | novo — `buildEvidenceLedger` | Baixo — mapeamento puro |
30
+ | `scripts/evidence.ts` | novo — `evidence:show <run-id>` | Baixo |
31
+ | `scripts/engineer.ts` | novo — `engineer "<objetivo>" [--ref <ref>] [--json]` | Médio — orquestra 4 subsistemas, mas cada chamada já existe |
32
+ | `lib/core/registry.ts` | 2 comandos novos | Baixo |
33
+ | `test/evidence-ledger.test.js` (novo) | testes puros de `buildEvidenceLedger` | — |
34
+ | `test/engineer-cli.test.js` (novo) | fixture git isolada, `engineer` ponta a ponta | — |
35
+
36
+ ## 3. Diagrama de fluxo
37
+
38
+ ```text
39
+ forja engineer "<objetivo>" [--ref <ref>]
40
+ │
41
+ ├─► ContextEngine.build({ objective, graph: GraphContextSource(graph.contextRecords) })
42
+ ├─► graph.contextRecords(objetivo) filtrado a nós ADR/SPEC (SPEC-032)
43
+ ├─► architecture:check (constitution.json real, SPEC-033) — não escopado
44
+ ├─► RiskEngine.assess() (SPEC-034) — só se --ref foi passado
45
+ └─► fluxo recomendado — parseado da tabela "Etapa → papel → comando" de docs/fluxo.md
46
+ │
47
+ ▼
48
+ saída de texto (default) ou --json (AC-3: nunca sintetiza além do que cada
49
+ subsistema já disse)
50
+ ```
51
+
52
+ ## 4. Contratos (API/CLI/Schema)
53
+
54
+ ```ts
55
+ // packages/engineering/evidence/src/index.ts
56
+ export interface EvidenceLedgerInput {
57
+ readonly run: RuntimeRun;
58
+ readonly auditRecords: readonly AuditRecord[];
59
+ readonly approvals: readonly ApprovalRequest[];
60
+ readonly architectureCheck?: ArchitectureCheckReport;
61
+ readonly riskAssessment?: ChangeRiskAssessment;
62
+ readonly commit?: string;
63
+ }
64
+ export interface EvidenceLedgerRecord {
65
+ readonly run: { readonly runId: string; readonly state: string; readonly startedAt: string; readonly updatedAt: string; readonly steps: number; readonly changedFiles: readonly string[] };
66
+ readonly intent: string;
67
+ readonly agent: AgentIdentity;
68
+ readonly architectureCheck?: ArchitectureCheckReport;
69
+ readonly risk?: ChangeRiskAssessment;
70
+ readonly tests?: EvaluationResult;
71
+ readonly approvals: readonly ApprovalRequest[];
72
+ readonly commit?: string;
73
+ }
74
+ export function buildEvidenceLedger(input: EvidenceLedgerInput): EvidenceLedgerRecord;
75
+ ```
76
+
77
+ ```bash
78
+ evidence:show <run-id>
79
+ engineer "<objetivo>" [--ref <ref>] [--json]
80
+ ```
81
+
82
+ ## 5. Decisões e alternativas
83
+
84
+ **D1**: `forja engineer` roda `architecture:check` **não escopado** (relatório completo, não
85
+ filtrado a arquivos) e só inclui `risk` quando `--ref` é passado explicitamente. A visão original
86
+ lista os dois como parte fixa da composição, mas `forja engineer` roda **antes** de existir um
87
+ diff (é a ferramenta que orienta o início do trabalho) — não há arquivos afetados ainda para
88
+ escopar nenhum dos dois. Alternativa rejeitada: inferir arquivos afetados a partir do texto do
89
+ objetivo (aí sim seria síntese/adivinhação, proibido por AC-3). Quando `--ref` é passado (ex.:
90
+ objetivo já tem uma branch com commits), o risco entra completo, exatamente como `risk:assess`
91
+ computaria.
92
+
93
+ **D2**: o "fluxo recomendado" é **parseado** da tabela "Etapa → papel → comando" existente em
94
+ `docs/fluxo.md`, não copiado/hardcoded em `scripts/engineer.ts`. Só uma fonte de verdade para os 6
95
+ passos SDD/GSD — se `docs/fluxo.md` mudar, `forja engineer` acompanha sem exigir sincronização
96
+ manual. Parser é uma regex sobre linhas de tabela markdown (determinístico, sem LLM).
97
+
98
+ **D3**: `EvidenceLedgerInput` não busca dado nenhum sozinho — é `scripts/evidence.ts`/
99
+ `scripts/engineer.ts` que buscam `RuntimeRun`/`AuditRecord`/`ApprovalRequest` reais e montam o
100
+ input. `buildEvidenceLedger` é só o mapeamento — igual ao par engine-puro/CLI-adapter já usado em
101
+ `packages/engineering/architecture` e `packages/engineering/risk`.
102
+
103
+ ## 6. Dependências
104
+
105
+ - SPEC-032 (`GraphLoop.contextRecords`), SPEC-033 (`checkConstitution`), SPEC-034
106
+ (`assessRisk`/`RiskEngine`) — todas já mergeadas/em PR quando este sprint começa.
107
+ - `packages/context.ContextEngine`/`GraphContextSource` (já existentes, mesmo padrão de
108
+ `scripts/demo-autonomy.ts`).
109
+ - `packages/adapter-sqlite.SqliteRuntimeRunStore`/`SqliteAuditStore` (já existentes).
110
+
111
+ ## 7. Rollout
112
+
113
+ - [ ] Feature flag necessária? Não.
114
+ - [ ] Migração de dados existentes? Não.
115
+ - [ ] Doc/persona impactada? README (comandos novos).
116
+
117
+ ## 8. Sinais de fracasso (kill criteria)
118
+
119
+ Já registrado no apêndice de `specs/engineering-intelligence/spec.md`, §8 deste spec: se a saída de
120
+ `forja engineer` sobre um objetivo real não for usável sem edição, o design da façade (não os
121
+ engines subjacentes, já validados nos Sprints 1-2) é revisado.
@@ -0,0 +1,90 @@
1
+ # Spec: Engineering Evidence Ledger + `forja engineer` (façade)
2
+
3
+ - **ID**: SPEC-035
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-01
7
+ - **Sprint alvo**: Sprint 3
8
+ - **ADRs relacionadas**: ADR-0078; depende de SPEC-032, SPEC-033, SPEC-034 (a façade compõe as
9
+ três)
10
+
11
+ ## 1. Problema
12
+
13
+ `AuditRecord`/`Observation`/`RuntimeRun` já são gravados por run, mas cada um em sua própria
14
+ tabela/stream — não existe uma view única "o que aconteceu neste run, do intent à evidência".
15
+ Separadamente, montar o quadro completo de uma mudança antes de começar (contexto + arquitetura +
16
+ risco + ADRs relevantes) hoje exige rodar vários comandos manualmente.
17
+
18
+ ## 2. Proposta de valor
19
+
20
+ Uma view agregada por run (Evidence Ledger) e uma façade única (`forja engineer`) que compõe tudo
21
+ que já existe — sem introduzir nenhuma fonte de dado nova.
22
+
23
+ ## 3. User stories
24
+
25
+ - **Como** governance, **quero** um registro append-only por run (`intent`, `agent`, `risk`,
26
+ `architectureCheck`, `tests`, `approvals`, `commit`), **para que** eu audite uma execução sem
27
+ cruzar manualmente quatro tabelas.
28
+ - **Como** desenvolvedor, **quero** `forja engineer "<objetivo>"` trazendo de uma vez arquitetura
29
+ afetada, ADRs relevantes, risco estimado e o fluxo recomendado, **para que** eu comece o trabalho
30
+ já orientado.
31
+
32
+ ## 4. Critérios de aceite (Definition of Done)
33
+
34
+ - [x] AC-1: view agregada (função pura sobre `AuditRecord`/`Observation`/`RuntimeRun` já
35
+ persistidos) produz o JSON no formato do exemplo da visão original (`run`, `intent`, `agent`,
36
+ `risk`, `architectureCheck`, `tests`, `approvals`, `commit`) — sem nova tabela SQLite além
37
+ das já existentes.
38
+ - [x] AC-2: `forja engineer "<objetivo>"` compõe, nesta ordem: `ContextEngine.build()` (já
39
+ existente) → `GraphLoop`/ADR relevantes (SPEC-032) → `architecture:check` (SPEC-033;
40
+ não escopado sem `--ref`, ver D1 do plan — não há diff ainda antes do trabalho começar) →
41
+ `RiskEngine.assess()` (SPEC-034, só com `--ref`) → fluxo recomendado (parseado de
42
+ `docs/fluxo.md`, D2 do plan — não reinventado).
43
+ - [x] AC-3: saída de `forja engineer` é estruturada (JSON opcional via `--json`, texto legível por
44
+ padrão) e nunca afirma nada que os componentes subjacentes não afirmaram — sem síntese de
45
+ LLM que possa alucinar arquitetura inexistente.
46
+ - [x] AC-4: nenhuma lógica de negócio nova em `forja engineer` além de composição e formatação —
47
+ qualquer decisão real continua nos engines que ela chama.
48
+
49
+ ## 5. Escopo
50
+
51
+ **Dentro**: view agregada de evidência; façade `forja engineer` na versão mínima descrita acima
52
+ (sem seleção de time de agentes, que depende de Agent Identity/Reputation, fora de escopo).
53
+
54
+ **Fora**: seleção/recomendação de agente ou modelo (Fase 3); relatório de release
55
+ (`release:engineering-report`, feature separada da visão original, útil mas não bloqueante para
56
+ esta fundação); qualquer persistência nova — esta spec é puramente uma camada de leitura/composição
57
+ sobre dados que Sprints 1-2 e o framework já existente produzem.
58
+
59
+ ## 6. NFRs / restrições
60
+
61
+ - View de evidência é derivável a qualquer momento a partir do que já está persistido — se
62
+ recalculada, produz o mesmo resultado (sem estado próprio para divergir).
63
+ - `forja engineer` nunca é a única fonte de verdade de nada — é sempre um resumo do que os
64
+ componentes subjacentes já disseram, rastreável de volta a cada um.
65
+
66
+ ## 7. Riscos e mitigação
67
+
68
+ | Risco | Probabilidade | Impacto | Mitigação |
69
+ |---|---|---|---|
70
+ | `forja engineer` virar um "resumo de LLM" que esconde de onde vieram os fatos | Média (é a tentação óbvia de UX) | Alta (quebra auditabilidade) | AC-3 proíbe síntese que não seja rastreável componente-a-componente |
71
+ | Evidence Ledger duplicar dado já em `AuditRecord`/`Observation` | Baixa se implementado como view | Média (duas fontes de verdade) | AC-1 explicitamente "função pura sobre dados já persistidos", sem gravação própria |
72
+
73
+ ## 8. Métricas de sucesso
74
+
75
+ Rodar `forja engineer` para uma mudança real proposta neste repositório produz uma saída que um
76
+ humano usaria sem edição para decidir se e como prosseguir — mesma métrica da spec master, aqui
77
+ verificada no nível do comando específico.
78
+
79
+ **Validado**: `forja engineer "compilar a architecture constitution deste repositório"` rodado
80
+ contra este próprio repositório (grafo real, 1013 arquivos). Produziu contexto relevante (specs e
81
+ testes de SPEC-033), ADRs/SPECs corretos (ADR-0078, SPEC-032/033/034), `architecture:check` real
82
+ (constitution já compilada neste repo) e o fluxo recomendado de `docs/fluxo.md` — utilizável sem
83
+ edição.
84
+
85
+ **Achado real corrigido durante a implementação (não um bug de lógica — um limite de exibição
86
+ ausente)**: a primeira execução sem `maxItems` devolveu **1013** referências de contexto (todo o
87
+ grafo do repositório caiu dentro do orçamento de 20k tokens), tornando a saída inutilizável sem
88
+ edição — o oposto do que esta métrica pede. Corrigido passando `maxItems: 10` para
89
+ `ContextEngine.build()` (as 10 mais relevantes, já ordenadas por `ContextEngine`); a lista completa
90
+ continua disponível via `context:smart`/`code:query`, que `forja engineer` não substitui.
@@ -0,0 +1,54 @@
1
+ # Tasks: Engineering Evidence Ledger + `forja engineer`
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-01
7
+
8
+ ---
9
+
10
+ ## T1 — `buildEvidenceLedger` (view pura) + `evidence:show`
11
+ - **Owner**: worker
12
+ - **Estimativa**: M
13
+ - **Depende de**: —
14
+ - **Paths**: `packages/engineering/evidence/src/index.ts`, `scripts/evidence.ts`, `lib/core/registry.ts`
15
+ - **Done quando**:
16
+ - [ ] `buildEvidenceLedger` mapeia `EvidenceLedgerInput` → `EvidenceLedgerRecord` sem inventar
17
+ nenhum campo que não veio no input (AC-1)
18
+ - [ ] `evidence:show <run-id>` busca `RuntimeRun` real (`SqliteRuntimeRunStore`), `AuditRecord`s
19
+ (`SqliteAuditStore`, filtrado por `aggregateId === runId`), `ApprovalRequest`s
20
+ (`ApprovalLedger`, filtrado por `correlationId === runId`)
21
+ - [ ] testes unitários (sem `fs`/rede): campos opcionais ausentes não aparecem como `null`
22
+ inventado; `run-id` inexistente é erro claro, não JSON vazio
23
+
24
+ ## T2 — `forja engineer "<objetivo>"` façade
25
+ - **Owner**: worker
26
+ - **Estimativa**: G
27
+ - **Depende de**: T1 (reaproveita o mesmo padrão engine-puro/CLI-adapter)
28
+ - **Paths**: `scripts/engineer.ts`, `lib/core/registry.ts`
29
+ - **Done quando**:
30
+ - [ ] compõe, na ordem do plan: `ContextEngine.build()` → `contextRecords` filtrado a ADR/SPEC →
31
+ `architecture:check` não escopado → `RiskEngine.assess()` só com `--ref` (D1) → fluxo
32
+ recomendado parseado de `docs/fluxo.md` (D2)
33
+ - [ ] `--json` produz JSON estruturado; sem a flag, texto legível
34
+ - [ ] nenhuma string sintetizada além do que os componentes já disseram (grep manual: sem
35
+ chamada de LLM/heurística de texto livre em `scripts/engineer.ts`)
36
+ - [ ] `forja tools:doctor` continua verde
37
+
38
+ ## T3 — prova sobre objetivo real deste repositório
39
+ - **Owner**: worker
40
+ - **Estimativa**: P
41
+ - **Depende de**: T2
42
+ - **Paths**: `test/engineer-cli.test.js` (novo)
43
+ - **Done quando**:
44
+ - [ ] fixture git isolada: `engineer "<objetivo>"` roda ponta a ponta (sem `--ref`) e produz
45
+ texto com todas as seções (contexto, ADRs relevantes, architecture:check, fluxo)
46
+ - [ ] com `--ref`, a seção de risco aparece com score real
47
+ - [ ] `evidence:show` recupera um run persistido de ponta a ponta
48
+
49
+ ---
50
+
51
+ ## Handoffs entre agentes
52
+
53
+ T1 → T2 → T3 sequencial. Sem handoff de papel — spec e plan já aprovados cobrem as decisões de
54
+ produto/arquitetura.
@@ -0,0 +1,92 @@
1
+ # Plan: Engineering Graph extensions (ADR/SPEC como nós de primeira classe)
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-01
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ Estender `extractDeterministicRelations` (packages/graph) para ler o campo `Status` de ADR e de
10
+ Spec como propriedade dedicada (não `GraphNode.status`/`KnowledgeStatus` — ver AC-1, é um
11
+ vocabulário de domínio diferente). `GraphNodeSpec`/`GraphNode` (packages/contracts) ganham um campo
12
+ opcional `documentStatus?: string` — extensão aditiva, mesmo padrão já usado nesta mesma janela de
13
+ trabalho para `PolicyLimits.maxCostUsd`/`isPathWithinRoot`/`remoteAddress` em `HttpRequest`: nenhum
14
+ consumidor existente quebra, campo ausente = comportamento idêntico ao de hoje.
15
+
16
+ `adr:list`/`adr:show`/`adr:impact`/`adr:graph` são scripts novos (`scripts/adr.ts`), mesmo padrão
17
+ de `scripts/drift-check.ts`: comando de processo, não capability registrada — não escreve em
18
+ projeto, só lê o grafo.
19
+
20
+ ## 2. Módulos afetados
21
+
22
+ | Caminho | Mudança | Risco |
23
+ |---|---|---|
24
+ | `packages/graph/src/index.ts` | `extractDeterministicRelations`: ler `- **Status**: <valor>` de ADR e `- **Status**: <valor>` de spec.md, embutir no label do nó | Baixo — aditivo, mesma função já testada |
25
+ | `scripts/adr.ts` | novo — `adr:list`/`adr:show`/`adr:impact`/`adr:graph` | Baixo — só leitura |
26
+ | `lib/core/registry.ts` | registrar os 4 comandos novos | Baixo |
27
+ | `test/graph.test.js` | testes para status de ADR/SPEC no extrator | — |
28
+ | `test/adr-cli.test.js` (novo) | testes de CLI para os 4 comandos | — |
29
+
30
+ ## 3. Diagrama de fluxo
31
+
32
+ ```text
33
+ memory/90-decisions/*.md ──┐
34
+ specs/*/spec.md ─┼─► extractDeterministicRelations (estendido)
35
+ │ │
36
+ │ ▼
37
+ │ GraphLoop.apply (existente, sem mudança)
38
+ │
39
+ ▼
40
+ scripts/adr.ts (list/show/impact/graph)
41
+ │
42
+ ▼
43
+ GraphLoop.query()/impact() (existente, sem mudança)
44
+ ```
45
+
46
+ ## 4. Contratos (API/CLI/Schema)
47
+
48
+ ```ts
49
+ // packages/contracts/src/index.ts (aditivo)
50
+ export interface GraphNode extends AuditFields {
51
+ // ...campos existentes inalterados...
52
+ readonly documentStatus?: string; // 'accepted'|'proposed'|'superseded'|'deprecated'|'rejected' (ADR) ou 'draft'|'review'|'approved'|'implementing'|'done'|'abandoned' (SPEC) — vocabulário do documento, não confundir com KnowledgeStatus
53
+ }
54
+ export interface GraphNodeSpec {
55
+ // ...campos existentes inalterados...
56
+ readonly documentStatus?: string;
57
+ }
58
+ ```
59
+
60
+ ```bash
61
+ adr:list # lista ADRs com status
62
+ adr:show <id> # mostra uma ADR: status, arquivo, resumo de constraints (se houver)
63
+ adr:impact <id> # usa GraphLoop.impact() — nós/arestas alcançáveis
64
+ adr:graph # exporta subgrafo (JSON) de nós ADR/SPEC + vizinhança
65
+ ```
66
+ (sem prefixo `forja`/`npm run` aqui — comandos ainda não existem; ver convenção já usada em
67
+ `docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md`)
68
+
69
+ ## 5. Decisões e alternativas
70
+
71
+ **D1**: `documentStatus?: string` como campo novo, aditivo, em `GraphNode`/`GraphNodeSpec`.
72
+ Alternativa rejeitada: usar `GraphNode.status` (`KnowledgeStatus`) — explicitamente proibido pela
73
+ spec (AC-1), mistura o ciclo de vida do documento com a epistemologia da aresta. Alternativa
74
+ descartada: embutir no `label` (string) — mais frágil (parse reverso, título com separador
75
+ colidindo) sem nenhuma economia real, já que extensão aditiva de contrato é o padrão já em uso
76
+ nesta mesma janela de trabalho para casos equivalentes.
77
+
78
+ ## 6. Dependências
79
+
80
+ - Nenhuma spec bloqueadora. `packages/graph`, `scripts/`, `lib/core/registry.ts` já existentes.
81
+
82
+ ## 7. Rollout
83
+
84
+ - [ ] Feature flag necessária? Não — leitura pura, sem side effect em projeto consumidor.
85
+ - [ ] Migração de dados existentes? Não — próxima reindexação (`code:sync`/`drift:check`) já
86
+ popula o status ao reprocessar os documentos.
87
+ - [ ] Doc/persona impactada? `docs/architecture/`, README (comandos novos).
88
+
89
+ ## 8. Sinais de fracasso (kill criteria)
90
+
91
+ Se o parse de `label` para extrair status de volta (D1) se mostrar frágil (ADRs com título contendo
92
+ " · ") isso é motivo para promover à alternativa (b) do D1 antes de expandir mais consumidores.
@@ -0,0 +1,101 @@
1
+ # Spec: Engineering Graph extensions (ADR/SPEC como nós de primeira classe)
2
+
3
+ - **ID**: SPEC-032
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-01
7
+ - **Sprint alvo**: Sprint 1 (ver `../engineering-intelligence/plan.md`)
8
+ - **ADRs relacionadas**: ADR-0078; nenhuma ADR própria esperada — extensão aditiva de vocabulário
9
+ sobre `GraphNode.type`/`GraphEdge.type`, que já são `string` livre em `packages/contracts`.
10
+
11
+ ## 1. Problema
12
+
13
+ `extractDeterministicRelations` já cria nós `ADR` a partir do padrão `ADR-\d{4}` encontrado em
14
+ texto, mas trata isso como uma referência solta (uma aresta `DERIVED_FROM` para um nó `ADR` sem
15
+ metadado) — não lê o `## Status` do próprio arquivo de ADR, não sabe se está `accepted`,
16
+ `superseded` ou `deprecated`, e não faz o mesmo para `SPEC-\d{3}`. Sem isso, perguntas como
17
+ "quais componentes uma ADR supersedida ainda governa" não têm resposta estruturada.
18
+
19
+ ## 2. Proposta de valor
20
+
21
+ ADRs e Specs passam a ser nós completos do grafo (com status, não só uma referência textual),
22
+ consultáveis via `adr:impact`/`adr:graph` e usados como insumo real do Change Risk Engine
23
+ (SPEC-034) e do Architecture Constitution (SPEC-033).
24
+
25
+ ## 3. User stories
26
+
27
+ - **Como** sdd-architect, **quero** `forja adr:impact 0027` mostrando componentes/specs/testes
28
+ afetados, **para que** eu saiba o raio de explosão antes de superseder uma decisão.
29
+ - **Como** governance, **quero** saber que uma ADR está `superseded` sem precisar abrir o arquivo,
30
+ **para que** `architecture:check` não valide contra uma regra morta.
31
+
32
+ ## 4. Critérios de aceite (Definition of Done)
33
+
34
+ - [x] AC-1: extensão de `extractDeterministicRelations` (ou uma função irmã dedicada, decisão de
35
+ implementação) lê `- **Status**: <valor>` do frontmatter de ADR (já no formato existente,
36
+ `memory/90-decisions/_template.md`) e do campo `Status` de spec.md (`_templates/spec.md`), e
37
+ grava como propriedade do nó — decisão de implementação: usar `GraphNode.status`
38
+ (`KnowledgeStatus`) é a tentação óbvia mas **errada** (status de ADR — accepted/proposed/
39
+ superseded/deprecated/rejected — é um conceito de domínio diferente de
40
+ verified/inferred/hypothesis/contradicted/unknown, que descreve confiança epistêmica da
41
+ *aresta*, não o ciclo de vida do documento); a spec desta feature deve decidir isso
42
+ explicitamente no `plan.md`, não misturar os dois vocabulários.
43
+ - [x] AC-2: `forja adr:list`/`adr:show <id>` funcionam sobre `memory/90-decisions/` real deste
44
+ repositório.
45
+ - [x] AC-3: `forja adr:impact <id>` usa `GraphLoop.impact()` (já existente, sem reimplementar BFS)
46
+ para listar nós/arestas alcançáveis a partir do nó ADR.
47
+ - [x] AC-4: `forja adr:graph` exporta um subgrafo (JSON) navegável — sem visualização nesta spec
48
+ (Fase posterior, dashboard é consumidor per princípio da visão original).
49
+ - [x] AC-5: mesmo tratamento para `SPEC-\d{3}` (nó `SPEC`, status do template já existente:
50
+ draft/review/approved/implementing/done/abandoned).
51
+
52
+ **Nota de implementação (achado real, fora de escopo desta spec)**: rodar `adr:list`/`show`/
53
+ `impact` contra o repositório real (1014 arquivos rastreados) travou por dezenas de minutos neste
54
+ ambiente — não é bug de lógica (uma fixture isolada com 2 documentos passa em <1s, ver
55
+ `test/adr-cli.test.js`) nem específico deste comando: `GitGraphDocumentSource.listDocuments()` é
56
+ rápido (1 subprocesso `git ls-files` + leitura síncrona de arquivo), mas
57
+ `SqliteGraphStore.saveNode`/`saveEdge`/`saveEvidence` (packages/adapter-sqlite) fazem um `INSERT`
58
+ individual por chamada, sem transação — para ~1000 documentos com múltiplas relações cada, isso é
59
+ plausivelmente dezenas de milhares de writes SQLite não agrupados, cada um com custo de fsync.
60
+ Mesmo padrão usado por `drift:check`/`graph:sync` — não é regressão desta spec, mas um achado real
61
+ que vale uma spec própria de performance (`GraphLoop.apply()` já processa uma `GraphMutation`
62
+ inteira por documento; agrupar os saves de uma mutation numa única transação SQLite é o candidato
63
+ óbvio, não implementado aqui por estar fora do escopo declarado em §5).
64
+
65
+ **Corrigido posteriormente**: `GraphStore` ganhou um método opcional `transaction<T>(fn: () => T):
66
+ T`; `GraphLoop.transaction()` delega pra ele (cai pra só `fn()` quando o store não suporta, ex.
67
+ `InMemoryGraphStore`); `SqliteGraphStore.transaction` implementa com `BEGIN`/`COMMIT`/`ROLLBACK`
68
+ reais (testado, incluindo reversão de fato em erro — `test/adapter-sqlite.test.js`).
69
+ `GraphIndexer.sync()` agora envolve o loop inteiro de `apply()` numa única transação. Medido contra
70
+ este próprio repositório (`adr:list`, mesma máquina, antes/depois via `git stash`): 7,65s → 2,75s,
71
+ tempo de sistema (I/O) caindo de ~3s pra ~0,08s — confirma a causa (fsync por `INSERT`), não só a
72
+ teoria.
73
+
74
+ ## 5. Escopo
75
+
76
+ **Dentro**: extração determinística de status de ADR/SPEC; `adr:list`/`adr:show`/`adr:impact`/
77
+ `adr:graph`; nenhuma mudança em `KnowledgeStatus` (contrato existente intocado).
78
+
79
+ **Fora**: visualização gráfica (Fase posterior); extração de `Requirement`/`BusinessRule` como
80
+ nós (a visão original pede, mas este repositório-framework não tem uma fonte de requisitos de
81
+ produto estruturada hoje — fica para quando um projeto consumidor real tiver essa fonte,
82
+ provavelmente via `docs/produto/`); `PullRequest`/`Commit`/`Release` como nós (SPEC-035/Provenance,
83
+ fase seguinte).
84
+
85
+ ## 6. NFRs / restrições
86
+
87
+ - Determinístico, sem LLM (mesmo padrão do extrator já existente).
88
+ - Não quebra `extractDeterministicRelations` existente — testes atuais (`test/graph.test.js`)
89
+ continuam passando sem alteração de comportamento para os tipos de nó já existentes.
90
+
91
+ ## 7. Riscos e mitigação
92
+
93
+ | Risco | Probabilidade | Impacto | Mitigação |
94
+ |---|---|---|---|
95
+ | Confundir status de documento com `KnowledgeStatus` de epistemologia da aresta | Média (é a armadilha óbvia) | Média (contamina semântica do grafo inteiro) | AC-1 marca a decisão como obrigatória e explícita no plan.md, não implícita no código |
96
+ | `adr:impact` ficar lento em grafos grandes | Baixa neste repositório (~78 ADRs hoje) | Baixa | `GraphLoop.impact()` já tem parâmetro `depth`; reaproveitar, não implementar limite novo |
97
+
98
+ ## 8. Métricas de sucesso
99
+
100
+ `forja adr:impact 0020` (core/registry, uma das ADRs mais referenciadas do repositório) retorna um
101
+ conjunto de componentes que um mantenedor confirma como correto, sem falso-negativo óbvio.
@@ -0,0 +1,60 @@
1
+ # Tasks: Engineering Graph extensions
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-01
7
+
8
+ ---
9
+
10
+ ## T1 — `documentStatus` no contrato de grafo
11
+ - **Owner**: worker
12
+ - **Estimativa**: P
13
+ - **Depende de**: —
14
+ - **Paths**: `packages/contracts/src/index.ts`
15
+ - **Done quando**:
16
+ - [ ] `GraphNode`/`GraphNodeSpec` ganham `documentStatus?: string`
17
+ - [ ] `npx tsc --noEmit` limpo
18
+ - [ ] nenhum teste existente quebra (campo opcional)
19
+
20
+ ## T2 — extrator lê status de ADR e de SPEC
21
+ - **Owner**: worker
22
+ - **Estimativa**: M
23
+ - **Depende de**: T1
24
+ - **Paths**: `packages/graph/src/index.ts`
25
+ - **Done quando**:
26
+ - [ ] `extractDeterministicRelations` popula `documentStatus` do nó ADR a partir de
27
+ `- **Status**: <valor>` no corpo do documento (formato de `memory/90-decisions/_template.md`)
28
+ - [ ] mesmo tratamento para nó `SPEC` a partir do campo `Status` de `specs/_templates/spec.md`
29
+ - [ ] testes em `test/graph.test.js` cobrindo ADR com/sem status e SPEC com/sem status
30
+ - [ ] testes passando
31
+
32
+ ## T3 — `scripts/adr.ts`: list/show/impact/graph
33
+ - **Owner**: worker
34
+ - **Estimativa**: M
35
+ - **Depende de**: T2
36
+ - **Paths**: `scripts/adr.ts`, `lib/core/registry.ts`
37
+ - **Done quando**:
38
+ - [ ] `adr:list` lista ADRs reais de `memory/90-decisions/` com status
39
+ - [ ] `adr:show <id>` mostra status, arquivo, e (se houver) o texto de `## Constraints`
40
+ - [ ] `adr:impact <id>` usa `GraphLoop.impact()` já existente, sem reimplementar BFS
41
+ - [ ] `adr:graph` exporta subgrafo JSON de nós ADR/SPEC + vizinhança direta
42
+ - [ ] `forja tools:doctor` (`docs-commands`/`commands-documented`) continua verde após os
43
+ comandos novos serem documentados no README
44
+
45
+ ## T4 — testes de CLI + integração com `code:sync`
46
+ - **Owner**: worker
47
+ - **Estimativa**: P
48
+ - **Depende de**: T3
49
+ - **Paths**: `test/adr-cli.test.js` (novo)
50
+ - **Done quando**:
51
+ - [ ] `adr:impact 0020` (ADR real deste repositório) retorna componentes plausíveis
52
+ - [ ] `npm test` verde, `npx tsc --noEmit` limpo
53
+
54
+ ---
55
+
56
+ ## Handoffs entre agentes
57
+
58
+ T1→T2→T3→T4 é sequencial (cada uma consome o contrato/dado da anterior); sem handoff de papel
59
+ (tudo cai em `worker`, sem etapa própria de product/architect — spec e plan já aprovados cobrem
60
+ essa decisão).