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