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,88 @@
1
+ # Plan: release-auditor-health
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: done
5
+ - **Criado em**: 2026-08-17
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui, só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ **Compor, não reimplementar.** O Release Auditor continuará sendo uma persona de julgamento, sem
12
+ probes próprios. Seu procedimento passa a executar `tools:doctor`, que já apresenta
13
+ `lib/core/health.ts`, e só então `release:check --publish`, que preserva o contrato estrito de
14
+ pré-publicação. Um teste lê o prompt como contrato e garante presença, ordem e flags dos comandos.
15
+
16
+ ## 2. Módulos afetados
17
+
18
+ | Caminho | Mudança | Risco |
19
+ |---|---|---|
20
+ | `.claude/agents/release-auditor.md` | editar procedimento, checks e regras de julgamento | B |
21
+ | `AGENTS.md` | alinhar descrição canônica do papel aos dois gates | B |
22
+ | `test/release-auditor.test.js` | criar teste do contrato do procedimento | B |
23
+ | `memory/40-delivery/current-sprint.md` | substituir candidatos obsoletos pelo item em execução | B |
24
+
25
+ Nenhum módulo executável de health, release ou registry será alterado.
26
+
27
+ ## 3. Diagrama de fluxo
28
+
29
+ ```text
30
+ Release Auditor
31
+ |
32
+ +--> npm run tools:doctor
33
+ | |
34
+ | +--> critical fail: REPROVADO, parar e reportar fix
35
+ | `--> ok/warn: continuar
36
+ |
37
+ `--> npm run release:check -- --publish
38
+ |
39
+ +--> fail: REPROVADO
40
+ `--> ok: parecer, ressalvas e validade perecível
41
+ ```
42
+
43
+ ## 4. Contratos
44
+
45
+ O contrato público continua sendo CLI existente:
46
+
47
+ ```text
48
+ npm run tools:doctor
49
+ npm run release:check -- --publish
50
+ ```
51
+
52
+ O primeiro comando deve aparecer antes do segundo. `--publish` é obrigatório. Avisos são lidos e
53
+ relatados, mas apenas falhas críticas bloqueiam. O agente nunca executa `npm publish`.
54
+
55
+ ## 5. Decisões e alternativas
56
+
57
+ **D1: Consumir health por `tools:doctor`.** Alternativa rejeitada: importar `runChecks()` num script
58
+ novo para o agente, pois criaria outra superfície executável sem necessidade.
59
+
60
+ **D2: Preservar dois comandos explícitos.** Alternativa rejeitada: trocar por `check:all --full`,
61
+ pois hoje o agregador chama `runReleaseChecks({})` sem `publish: true`; árvore suja seria aviso.
62
+
63
+ **D3: Testar o prompt como contrato.** O teste verifica índices dos comandos no texto, a flag
64
+ `--publish` e a proibição de `npm publish`. Alternativa rejeitada: testar só presença por grep, que
65
+ não detectaria ordem invertida nem enfraquecimento da flag.
66
+
67
+ Nenhuma decisão é estrutural ou irreversível. ADR novo não é necessário; o plano aplica ADR-0023 e
68
+ ADR-0024.
69
+
70
+ ## 6. Dependências
71
+
72
+ - **Specs**: SPEC-009/ADR-0023 e SPEC-010/ADR-0024, ambas concluídas.
73
+ - **Pacotes npm**: nenhum.
74
+ - **Migrações de dados/memory**: nenhuma.
75
+
76
+ ## 7. Rollout
77
+
78
+ - [x] Feature flag necessária? Não, é procedimento interno de governança.
79
+ - [x] Migração de dados existentes? Não.
80
+ - [x] Doc/persona impactada? Release Auditor e sua descrição canônica em `AGENTS.md`.
81
+ - [x] Rodar teste direcionado, `types:check`, `project:check`, `tools:doctor` e `spec:check`.
82
+ - [x] Registrar handoff para Governance após implementação.
83
+
84
+ ## 8. Sinais de fracasso
85
+
86
+ - A solução introduz probe ou lógica de severidade fora de `lib/core/health.ts`.
87
+ - `release:check --publish` deixa de ser obrigatório ou é substituído pelo agregador não estrito.
88
+ - O teste fica acoplado à redação completa do prompt, em vez de somente ao contrato operacional.
@@ -0,0 +1,82 @@
1
+ # Spec: release-auditor-health
2
+
3
+ - **ID**: SPEC-022
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-08-17
7
+ - **Sprint alvo**: framework-root
8
+ - **ADRs relacionadas**: [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (saúde compartilhada), [ADR-0024](../../memory/90-decisions/0024-release-gate-tarball.md) (gate do tarball)
9
+
10
+ ## 1. Problema
11
+ O ADR-0023 definiu `lib/core/health.ts` como fonte única da saúde do núcleo e previu três
12
+ consumidores: `tools:doctor`, `SessionStart` e Release Auditor. Os dois primeiros já consomem o
13
+ catálogo; o Release Auditor ainda manda executar apenas `release:check --publish`.
14
+
15
+ Esse gate prova a fronteira do tarball, mas não substitui a saúde do repositório. Ele não executa os
16
+ checks de coerência de documentação e topologia e só alcança parte da saúde indiretamente, por meio
17
+ de comandos de smoke na instalação limpa. Assim, o auditor pode aprovar o pacote sem ter obtido o
18
+ veredito da fonte que o ADR-0023 declarou canônica.
19
+
20
+ O agregador `check:all --full` também não substitui o procedimento de publicação: internamente ele
21
+ roda `release:check` em modo de desenvolvimento, no qual árvore suja é aviso. Pré-publicação exige
22
+ `release:check --publish`, que reprova se o tarball não corresponder a um commit.
23
+
24
+ ## 2. Proposta de valor
25
+ Toda auditoria pré-publicação valida primeiro a saúde canônica do núcleo e depois a instalação limpa
26
+ do tarball, sem duplicar probes e sem enfraquecer o contrato de árvore limpa.
27
+
28
+ ## 3. User stories
29
+ - **Como** Release Auditor, **quero** consumir o veredito de `tools:doctor` antes do gate do
30
+ tarball, **para que** eu não aprove um release sobre um núcleo incoerente.
31
+ - **Como** mantenedor, **quero** que o procedimento aponte para os gates executáveis existentes,
32
+ **para que** uma nova entrada em `CHECKS[]` seja herdada sem editar o agente.
33
+ - **Como** quem publica, **quero** preservar `release:check --publish`, **para que** uma árvore suja
34
+ continue bloqueando a publicação.
35
+
36
+ ## 4. Critérios de aceite (Definition of Done)
37
+ - [x] AC-1: `.claude/agents/release-auditor.md` manda executar `npm run tools:doctor` antes de
38
+ `npm run release:check -- --publish`.
39
+ - [x] AC-2: Falha crítica do doctor reprova a auditoria e impede parecer de aprovação, com a
40
+ correção fornecida pelo próprio check.
41
+ - [x] AC-3: O agente não reimplementa nenhum probe de `lib/core/health.ts`; o catálogo continua
42
+ sendo a única fonte da definição de saúde.
43
+ - [x] AC-4: `release:check -- --publish` permanece obrigatório e separado. `check:all --full` não é
44
+ apresentado como equivalente de pré-publicação enquanto não propagar o modo `publish`.
45
+ - [x] AC-5: A descrição canônica do papel em `AGENTS.md` reflete os dois gates e mantém explícito que
46
+ o auditor não executa `npm publish`.
47
+ - [x] AC-6: Teste automatizado falha se o procedimento perder um dos comandos, inverter sua ordem
48
+ ou remover `--publish`.
49
+
50
+ ## 5. Escopo
51
+ **Dentro**:
52
+ - Procedimento e julgamento em `.claude/agents/release-auditor.md`.
53
+ - Descrição canônica do papel em `AGENTS.md`.
54
+ - Teste de contrato do procedimento.
55
+ - Atualização do candidato obsoleto em `memory/40-delivery/current-sprint.md`.
56
+
57
+ **Fora** (explícito, evita scope creep):
58
+ - Alterar `lib/core/health.ts`, seus checks ou severidades.
59
+ - Alterar `lib/core/release.ts` ou incorporar os checks de health ao catálogo de release.
60
+ - Fazer `check:all --full` propagar modo de publicação.
61
+ - Executar ou automatizar `npm publish`.
62
+ - Criar ADR: os contratos necessários já estão decididos nos ADRs 0023 e 0024.
63
+
64
+ ## 6. NFRs / restrições
65
+ - **Performance**: o doctor roda antes do gate caro e pode interromper cedo uma auditoria inviável.
66
+ - **Segurança**: nenhuma correção e nenhuma publicação são executadas automaticamente.
67
+ - **Observabilidade**: o parecer cita o gate, o check que falhou e sua correção; não resume falha
68
+ crítica como diagnóstico genérico.
69
+ - **Compatibilidade**: nomes e contratos dos comandos existentes permanecem intactos.
70
+
71
+ ## 7. Riscos e mitigação
72
+ | Risco | Probabilidade | Impacto | Mitigação |
73
+ |---|---|---|---|
74
+ | Duplicar checks entre health e release | M | A | Compor comandos existentes; zero probe novo |
75
+ | Trocar por `check:all --full` e aceitar árvore suja | M | A | Manter `release:check --publish` explícito e testado |
76
+ | Doctor tornar o release mais lento | B | B | Gate barato roda antes do empacotamento e falha cedo |
77
+ | Documentação do papel voltar a divergir | M | M | Teste de contrato cobre presença e ordem dos comandos |
78
+
79
+ ## 8. Métricas de sucesso
80
+ Nos 30 dias após a entrega, 100% dos pareceres do Release Auditor registrados na trilha executam os
81
+ dois gates; nenhuma aprovação ocorre após `tools:doctor` crítico e nenhuma auditoria de publicação
82
+ usa `release:check` sem `--publish`.
@@ -0,0 +1,72 @@
1
+ # Tasks: release-auditor-health
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: done
6
+ - **Criado em**: 2026-08-17
7
+
8
+ > Decomposição executável. A sequência preserva o contrato antes de atualizar a documentação.
9
+
10
+ ---
11
+
12
+ ## T1 — Fixar o contrato do Release Auditor
13
+
14
+ - **Owner**: Worker
15
+ - **Estimativa**: P
16
+ - **Depende de**: —
17
+ - **Paths**: `test/release-auditor.test.js`
18
+ - **Done quando**:
19
+ - [x] O teste lê `.claude/agents/release-auditor.md` como contrato operacional.
20
+ - [x] Reprova se `npm run tools:doctor` estiver ausente ou depois de
21
+ `npm run release:check -- --publish` (AC-1, AC-6).
22
+ - [x] Reprova se o gate do tarball perder `--publish` (AC-4, AC-6).
23
+ - [x] Reprova se o procedimento autorizar ou executar `npm publish` (AC-5).
24
+ - [x] Não compara o prompt inteiro nem fica acoplado a texto editorial fora desses invariantes.
25
+
26
+ ## T2 — Migrar o procedimento do agente
27
+
28
+ - **Owner**: Worker
29
+ - **Estimativa**: P
30
+ - **Depende de**: T1
31
+ - **Paths**: `.claude/agents/release-auditor.md`
32
+ - **Done quando**:
33
+ - [x] O procedimento executa `npm run tools:doctor` antes do gate do tarball (AC-1).
34
+ - [x] Falha crítica do doctor interrompe a auditoria e produz parecer reprovado com o `fix` do
35
+ check; avisos são lidos e relatados sem serem promovidos a falha (AC-2).
36
+ - [x] `npm run release:check -- --publish` permanece obrigatório (AC-4).
37
+ - [x] Não há probe, heurística de saúde ou lista duplicada de checks no prompt (AC-3).
38
+ - [x] A regra de nunca executar `npm publish` permanece explícita (AC-5).
39
+
40
+ ## T3 — Alinhar a topologia e a sprint
41
+
42
+ - **Owner**: Worker
43
+ - **Estimativa**: P
44
+ - **Depende de**: T2
45
+ - **Paths**: `AGENTS.md`, `memory/40-delivery/current-sprint.md`
46
+ - **Done quando**:
47
+ - [x] A descrição canônica do Release Auditor cita os dois gates, na ordem correta, e mantém a
48
+ publicação como ato humano (AC-5).
49
+ - [x] O candidato obsoleto de migração do Release Auditor sai de "Próximos candidatos" e a
50
+ SPEC-022 aparece como item da sprint.
51
+ - [x] A informação de que `tools:doctor` ainda não roda no CI é removida, pois `.github/workflows/ci.yml`
52
+ já executa o gate.
53
+
54
+ ## T4 — Validação e handoff de governança
55
+
56
+ - **Owner**: Governance
57
+ - **Estimativa**: P
58
+ - **Depende de**: T1, T2, T3
59
+ - **Paths**: `specs/release-auditor-health/spec.md`, `specs/release-auditor-health/tasks.md`
60
+ - **Done quando**:
61
+ - [x] Teste direcionado do Release Auditor passa.
62
+ - [x] `npm run types:check`, `npm run project:check`, `npm run tools:doctor` e
63
+ `npm run spec:check -- release-auditor-health` passam.
64
+ - [x] AC-1 a AC-6 são marcados somente após evidência verificável.
65
+ - [x] Handoff `review` é registrado; Governance emite parecer antes de concluir a spec.
66
+
67
+ ---
68
+
69
+ ## Handoffs entre agentes
70
+
71
+ Após aprovação destas tasks, registrar `npm run gsd:handoff -- implement release-auditor-health`.
72
+ Ao concluir T1-T3, registrar `npm run gsd:handoff -- review release-auditor-health` para Governance.
@@ -0,0 +1,55 @@
1
+ # Plan: Smart Agent Routing
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-01
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ Extensão de `packages/engineering/identity` (mesmo pacote de SPEC-036, não um novo sub-domínio):
10
+ `recommendAgent(profiles, criteria)`, função pura, mesmo estilo de `recommendProfile`
11
+ (`packages/llm`) — soma pontos por critério casado, nunca esconde o porquê. `scripts/agent.ts`
12
+ ganha `agent:recommend`, reaproveitando `SqliteAgentProfileStore.list()` já existente.
13
+
14
+ ## 2. Módulos afetados
15
+
16
+ | Caminho | Mudança | Risco |
17
+ |---|---|---|
18
+ | `packages/engineering/identity/src/index.ts` | `recommendAgent` novo | Baixo — função pura pequena |
19
+ | `scripts/agent.ts` | `agent:recommend` novo subcomando | Baixo |
20
+ | `lib/core/registry.ts` | 1 comando novo | Baixo |
21
+ | `test/agent-identity-reputation.test.js` | testes unitários de `recommendAgent` | — |
22
+ | `test/agent-cli.test.js` | teste de CLI de `agent:recommend` | — |
23
+
24
+ ## 3. Contratos
25
+
26
+ ```ts
27
+ // packages/engineering/identity/src/index.ts
28
+ export interface AgentRecommendation { readonly agentId: string; readonly score: number; readonly reasons: readonly string[]; }
29
+ export function recommendAgent(profiles: readonly AgentProfile2[], criteria: { readonly role: string; readonly domain?: string }): readonly AgentRecommendation[];
30
+ ```
31
+
32
+ Fórmula (D1): `score = (role === criteria.role ? 100 : 0) + (domain casado em architectureDomains ?
33
+ 50 : 0) + (trustLevel ?? 0) * 10` (0-50). Pesos documentados aqui e no código — mesmo princípio de
34
+ `computeReputationScore`/`RiskEngine`. Sem `trustLevel`, o termo de reputação é 0 (não excluído do
35
+ ranking, AC-2) e o motivo declara "sem pontuação ainda".
36
+
37
+ ```bash
38
+ agent:recommend --role <role> [--domain <d>]
39
+ ```
40
+
41
+ ## 4. Decisões
42
+
43
+ **D1**: pesos 100/50/(0-50) espelham a proporção já usada em `recommendProfile` (100 pro papel, 50
44
+ pra tarefa/domínio) — reaproveita a mesma "linguagem de score" em vez de inventar uma nova escala,
45
+ mais fácil de comparar mentalmente entre os dois comandos irmãos.
46
+
47
+ ## 5. Rollout
48
+
49
+ Sem migração, sem feature flag — comando novo, opt-in por natureza.
50
+
51
+ ## 6. Kill criteria
52
+
53
+ Já coberto pelo mesmo princípio de SPEC-034/036: se o ranking não corresponder a julgamento humano
54
+ sobre dado real, os pesos de D1 são revisados antes de qualquer consumo automático (§5 do spec,
55
+ "Fora").
@@ -0,0 +1,85 @@
1
+ # Spec: Smart Agent Routing
2
+
3
+ - **ID**: SPEC-037
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-01
7
+ - **Sprint alvo**: Sprint 5 (segundo sprint da Fase 3 — a peça deixada de fora de SPEC-036 §5
8
+ deliberadamente: "consumo depende deste sprint já estar em produção")
9
+ - **ADRs relacionadas**: ADR-0078; depende de SPEC-036 (`AgentProfile2`/`trustLevel` — a fonte de
10
+ reputação que esta spec consome, não recalcula)
11
+
12
+ > Não confundir com `packages/llm.recommendProfile` (ADR-0074, "LLM Fit Loop") — aquele roteia
13
+ > entre **perfis de provider/model** (`codex`/`claude`/`gemini`/`ollama`) por papel/tarefa; esta
14
+ > spec roteia entre **agentes registrados** (`AgentProfile2`, SPEC-036) por papel/domínio/reputação.
15
+ > São dois problemas adjacentes, não o mesmo — por isso esta spec **estende
16
+ > `packages/engineering/identity`** (onde `AgentProfile2`/`computeReputationScore` já vivem), não
17
+ > `packages/llm`. O gap analysis original (`docs/architecture/...` §3) que sugeriu "estender
18
+ > `llm-fit`" previa isso antes de `AgentProfile2` existir; agora que existe, estender o pacote que
19
+ > já tem o dado é a composição certa, não duplicar o dado em `packages/llm`.
20
+
21
+ ## 1. Problema
22
+
23
+ `AgentProfile2` (SPEC-036) já tem `trustLevel`/`autonomyLevel` reais, derivados de comportamento —
24
+ mas nada usa esse dado pra recomendar **qual agente registrado** é o mais adequado pra um
25
+ papel/domínio. Hoje a escolha de agente é manual e não considera histórico de confiabilidade.
26
+
27
+ ## 2. Proposta de valor
28
+
29
+ `forja agent:recommend --role <role> [--domain <d>]` classifica os agentes já registrados por
30
+ adequação (papel, domínio de arquitetura, reputação), com razões explícitas — nunca um ranking sem
31
+ explicação, mesmo princípio já usado em `risk:assess`/`architecture:check`.
32
+
33
+ ## 3. User stories
34
+
35
+ - **Como** governance/orchestrator, **quero** uma recomendação de qual agente registrado atribuir a
36
+ uma tarefa de um papel/domínio específico, **para que** a escolha considere reputação real, não
37
+ só disponibilidade.
38
+
39
+ ## 4. Critérios de aceite (Definition of Done)
40
+
41
+ - [x] AC-1: `recommendAgent` (função pura, `packages/engineering/identity`, mesmo pacote de
42
+ `computeReputationScore` — SPEC-036) recebe `readonly AgentProfile2[]` + critério
43
+ (`role`, `domain?`) e devolve um ranking com `score` e `reasons[]` — nunca um número sem
44
+ explicação (mesmo padrão de `recommendProfile`/`risk:assess`).
45
+ - [x] AC-2: agente sem `trustLevel` ainda (nunca rodou `agent:score`) ainda aparece no ranking —
46
+ não é excluído, mas o motivo declara explicitamente "sem pontuação ainda", nunca finge um
47
+ trust level que não existe.
48
+ - [x] AC-3: `forja agent:recommend --role <role> [--domain <d>]` (novo subcomando de
49
+ `scripts/agent.ts` — mesmo domínio de comando de SPEC-036, não um script novo) funcional.
50
+ - [x] AC-4: recomendação é **informação**, não decisão — não bloqueia, não atribui, não chama
51
+ `PolicyEngine`/`RuntimeEngine`. Mesmo princípio de `RiskEngine`/SPEC-034 D3: o score informa,
52
+ quem decide continua sendo o humano/orquestrador.
53
+
54
+ ## 5. Escopo
55
+
56
+ **Dentro**: `recommendAgent` (motor puro); `agent:recommend` (CLI).
57
+
58
+ **Fora**: atribuição automática de agente a uma tarefa (decisão continua manual/orquestrador, AC-4);
59
+ routing entre provider/model (`packages/llm.recommendProfile` já existe e não muda aqui);
60
+ `PolicyEngine` consumir a recomendação automaticamente (mesmo raciocínio de SPEC-034/036 — consumo
61
+ é spec própria futura, quando/se fizer sentido).
62
+
63
+ ## 6. NFRs / restrições
64
+
65
+ - Determinístico, sem LLM — mesma fórmula de scoring documentada em código e aqui.
66
+ - Reaproveita `AgentProfile2`/`trustLevel` já persistido — nenhum cálculo de reputação novo (isso é
67
+ SPEC-036, não esta spec).
68
+
69
+ ## 7. Riscos e mitigação
70
+
71
+ | Risco | Probabilidade | Impacto | Mitigação |
72
+ |---|---|---|---|
73
+ | Confundir com `llm:recommend` (routing de provider/model) | Média (nomes parecidos) | Baixa (confusão, não bug) | Nota explícita no topo desta spec e no código; comandos com prefixos diferentes (`agent:` vs. `llm:`) |
74
+ | Ranking virar decisão automática por acidente | Baixa (mesmo padrão já seguido em RiskEngine) | Alta se acontecesse | AC-4 explícito; nenhum código nesta spec chama `PolicyEngine`/atribui trabalho |
75
+
76
+ ## 8. Métricas de sucesso
77
+
78
+ Registrar 2+ agentes com `role`/`architectureDomains`/`trustLevel` diferentes (reaproveitando os
79
+ dados de teste de SPEC-036) e confirmar que `agent:recommend` ordena corretamente por adequação —
80
+ revisão humana, mesma metodologia de SPEC-034/036 §8.
81
+
82
+ **Validado** (`test/agent-cli.test.js`): 3 agentes registrados — `agent-a` (role+domain casados,
83
+ mais reputação real via amostra sintética de SPEC-036: 4 sucessos/1 rollback), `agent-b` (só role),
84
+ `agent-c` (só domain). Ranking saiu `agent-a > agent-b > agent-c`, na ordem esperada por revisão
85
+ humana — nenhum redesenho de pesos necessário (kill criteria do plan não disparado).
@@ -0,0 +1,26 @@
1
+ # Tasks: Smart Agent Routing
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-01
7
+
8
+ ---
9
+
10
+ ## T1 — `recommendAgent` (motor puro) + `agent:recommend` (CLI)
11
+ - **Owner**: worker
12
+ - **Estimativa**: P
13
+ - **Depende de**: —
14
+ - **Paths**: `packages/engineering/identity/src/index.ts`, `scripts/agent.ts`, `lib/core/registry.ts`
15
+ - **Done quando**:
16
+ - [ ] `recommendAgent` implementa a fórmula de D1, agente sem `trustLevel` não é excluído (AC-2)
17
+ - [ ] `agent:recommend --role <role> [--domain <d>]` funcional
18
+ - [ ] testes unitários: role casado, domain casado, sem pontuação ainda, ordenação por score
19
+ - [ ] teste de CLI: 2+ agentes registrados com reputações diferentes, ranking correto
20
+ - [ ] `forja tools:doctor` continua verde
21
+
22
+ ---
23
+
24
+ ## Handoffs entre agentes
25
+
26
+ Sprint pequeno, sem handoff — T1 é a spec inteira.
@@ -1 +0,0 @@
1
- export {};
@@ -1,52 +0,0 @@
1
- import fs from 'node:fs';
2
- import os from 'node:os';
3
- import path from 'node:path';
4
- import Database from 'better-sqlite3';
5
- import { CapabilityRegistry } from "../packages/core/src/index.js";
6
- import { EventBus } from "../packages/events/src/index.js";
7
- import { GraphLoop } from "../packages/graph/src/index.js";
8
- import { ApprovalLedger, PolicyEngine } from "../packages/policy/src/index.js";
9
- import { InMemoryEventStream } from "../packages/adapter-nest/src/index.js";
10
- import { createDefaultControlPlane } from "../apps/server/src/main.js";
11
- import { SqliteApprovalStore, SqliteContextCache, SqliteEventStore, SqliteGraphStore, SqliteMigrationRunner, SqliteObservationStore, SqliteOrchestrationStore, SqliteRuntimePersistence } from "../packages/adapter-sqlite/src/index.js";
12
- const agent = { id: 'server-persistence-agent', name: 'Persistence test agent', role: 'developer', autonomy: 'supervised' };
13
- const definition = { schemaVersion: '2.0', createdAt: '2026-08-02T00:00:00.000Z', updatedAt: '2026-08-02T00:00:00.000Z', correlationId: 'server-persistence', id: 'server.persistence.read', version: '1.0.0', description: 'Deterministic persistence probe', permissions: ['read'], risk: 'low', sideEffects: [], requirements: [], supportsAutonomy: true, idempotent: true, timeoutMs: 1000, retry: { maxAttempts: 1, backoffMs: 0 }, aliases: [] };
14
- function makeRegistry() {
15
- const value = new CapabilityRegistry();
16
- value.register({ definition, validateInput: (input) => input ?? {}, validateOutput: (output) => output, handler: async () => ({ capabilityId: definition.id, payload: { ok: true }, evidence: [{ id: 'server-persistence-evidence', source: 'server-persistence-test', locator: 'handler', capturedAt: '2026-08-02T00:00:00.000Z', status: 'verified' }] }) });
17
- return value;
18
- }
19
- function makePolicy(database) {
20
- return new PolicyEngine({ approvalLedger: new ApprovalLedger(new SqliteApprovalStore(database)), rules: [{ id: 'server-persistence-approval', priority: 10, effect: 'REQUIRE_APPROVAL', reason: 'Persistence probe requires approval', scope: {} }] });
21
- }
22
- function makeControlPlane(database, value, policy) {
23
- const graph = new GraphLoop(new SqliteGraphStore(database));
24
- const events = new EventBus(new SqliteEventStore(database));
25
- return createDefaultControlPlane(new InMemoryEventStream(), value, policy, new SqliteRuntimePersistence(database), new ApprovalLedger(new SqliteApprovalStore(database)), events, graph, undefined, new SqliteOrchestrationStore(database), new SqliteObservationStore(database));
26
- }
27
- const root = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-server-persistence-'));
28
- const dbPath = path.join(root, 'runtime.db');
29
- try {
30
- const firstDatabase = new Database(dbPath);
31
- new SqliteMigrationRunner(firstDatabase).apply();
32
- const firstControlPlane = makeControlPlane(firstDatabase, makeRegistry(), makePolicy(firstDatabase));
33
- const budget = { inputTokens: 40, outputTokens: 20, totalTokens: 60, usedTokens: 0 };
34
- const started = await firstControlPlane.runtimeStart({ objective: 'restart persistence probe', agent, budget, steps: [{ capabilityId: definition.id, payload: {}, estimatedTokens: 10, categories: ['read'], environment: 'local', files: [], approval: { action: 'read.probe', justification: 'Prove approval persistence', impact: 'No files changed', expiresAt: '2099-01-01T00:00:00.000Z' } }] });
35
- const awaiting = await firstControlPlane.runtimeExecute(started.runId);
36
- const pending = await firstControlPlane.approvalList();
37
- const graph = new GraphLoop(new SqliteGraphStore(firstDatabase));
38
- graph.upsertNode({ id: 'restart-node', type: 'Task', label: 'restart persistence probe', status: 'verified' });
39
- new SqliteContextCache(firstDatabase).set('restart-context', 'evidence context');
40
- await new EventBus(new SqliteEventStore(firstDatabase)).append({ type: 'approval.requested', aggregateId: started.runId, payload: { approvalId: pending[0].id }, idempotencyKey: `approval:${pending[0].id}` });
41
- await firstControlPlane.record({ traceId: 'restart-observation', runId: started.runId, outcome: 'blocked', contextRefs: ['restart-context'] });
42
- firstDatabase.close();
43
- const secondDatabase = new Database(dbPath);
44
- const secondControlPlane = makeControlPlane(secondDatabase, makeRegistry(), makePolicy(secondDatabase));
45
- const recovered = await secondControlPlane.runtimeGet(started.runId);
46
- const result = { ok: recovered.runId === started.runId && awaiting.state === 'awaiting_approval', state: recovered.state, approvals: (await secondControlPlane.approvalList()).length, context: new SqliteContextCache(secondDatabase).get('restart-context'), graphNodes: new GraphLoop(new SqliteGraphStore(secondDatabase)).query({ labelIncludes: 'restart persistence' }).length, events: (await new EventBus(new SqliteEventStore(secondDatabase)).list()).length, observations: (await secondControlPlane.observations()).length };
47
- secondDatabase.close();
48
- console.log(JSON.stringify(result));
49
- }
50
- finally {
51
- fs.rmSync(root, { recursive: true, force: true });
52
- }
@@ -1,52 +0,0 @@
1
- import fs from 'node:fs';
2
- import os from 'node:os';
3
- import path from 'node:path';
4
- import Database from 'better-sqlite3';
5
- import { CapabilityRegistry } from "../packages/core/src/index.js";
6
- import { EventBus } from "../packages/events/src/index.js";
7
- import { GraphLoop } from "../packages/graph/src/index.js";
8
- import { ApprovalLedger, PolicyEngine } from "../packages/policy/src/index.js";
9
- import { InMemoryEventStream } from "../packages/adapter-nest/src/index.js";
10
- import { createDefaultControlPlane } from "../apps/server/src/main.js";
11
- import { SqliteApprovalStore, SqliteContextCache, SqliteEventStore, SqliteGraphStore, SqliteMigrationRunner, SqliteObservationStore, SqliteOrchestrationStore, SqliteRuntimePersistence } from "../packages/adapter-sqlite/src/index.js";
12
- const agent = { id: 'server-persistence-agent', name: 'Persistence test agent', role: 'developer', autonomy: 'supervised' };
13
- const definition = { schemaVersion: '2.0', createdAt: '2026-08-02T00:00:00.000Z', updatedAt: '2026-08-02T00:00:00.000Z', correlationId: 'server-persistence', id: 'server.persistence.read', version: '1.0.0', description: 'Deterministic persistence probe', permissions: ['read'], risk: 'low', sideEffects: [], requirements: [], supportsAutonomy: true, idempotent: true, timeoutMs: 1000, retry: { maxAttempts: 1, backoffMs: 0 }, aliases: [] };
14
- function makeRegistry() {
15
- const value = new CapabilityRegistry();
16
- value.register({ definition, validateInput: (input) => input ?? {}, validateOutput: (output) => output, handler: async () => ({ capabilityId: definition.id, payload: { ok: true }, evidence: [{ id: 'server-persistence-evidence', source: 'server-persistence-test', locator: 'handler', capturedAt: '2026-08-02T00:00:00.000Z', status: 'verified' }] }) });
17
- return value;
18
- }
19
- function makePolicy(database) {
20
- return new PolicyEngine({ approvalLedger: new ApprovalLedger(new SqliteApprovalStore(database)), rules: [{ id: 'server-persistence-approval', priority: 10, effect: 'REQUIRE_APPROVAL', reason: 'Persistence probe requires approval', scope: {} }] });
21
- }
22
- function makeControlPlane(database, value, policy) {
23
- const graph = new GraphLoop(new SqliteGraphStore(database));
24
- const events = new EventBus(new SqliteEventStore(database));
25
- return createDefaultControlPlane(new InMemoryEventStream(), value, policy, new SqliteRuntimePersistence(database), new ApprovalLedger(new SqliteApprovalStore(database)), events, graph, undefined, new SqliteOrchestrationStore(database), new SqliteObservationStore(database));
26
- }
27
- const root = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-server-persistence-'));
28
- const dbPath = path.join(root, 'runtime.db');
29
- try {
30
- const firstDatabase = new Database(dbPath);
31
- new SqliteMigrationRunner(firstDatabase).apply();
32
- const firstControlPlane = makeControlPlane(firstDatabase, makeRegistry(), makePolicy(firstDatabase));
33
- const budget = { inputTokens: 40, outputTokens: 20, totalTokens: 60, usedTokens: 0 };
34
- const started = await firstControlPlane.runtimeStart({ objective: 'restart persistence probe', agent, budget, steps: [{ capabilityId: definition.id, payload: {}, estimatedTokens: 10, categories: ['read'], environment: 'local', files: [], approval: { action: 'read.probe', justification: 'Prove approval persistence', impact: 'No files changed', expiresAt: '2099-01-01T00:00:00.000Z' } }] });
35
- const awaiting = await firstControlPlane.runtimeExecute(started.runId);
36
- const pending = await firstControlPlane.approvalList();
37
- const graph = new GraphLoop(new SqliteGraphStore(firstDatabase));
38
- graph.upsertNode({ id: 'restart-node', type: 'Task', label: 'restart persistence probe', status: 'verified' });
39
- new SqliteContextCache(firstDatabase).set('restart-context', 'evidence context');
40
- await new EventBus(new SqliteEventStore(firstDatabase)).append({ type: 'approval.requested', aggregateId: started.runId, payload: { approvalId: pending[0].id }, idempotencyKey: `approval:${pending[0].id}` });
41
- await firstControlPlane.record({ traceId: 'restart-observation', runId: started.runId, outcome: 'blocked', contextRefs: ['restart-context'] });
42
- firstDatabase.close();
43
- const secondDatabase = new Database(dbPath);
44
- const secondControlPlane = makeControlPlane(secondDatabase, makeRegistry(), makePolicy(secondDatabase));
45
- const recovered = await secondControlPlane.runtimeGet(started.runId);
46
- const result = { ok: recovered.runId === started.runId && awaiting.state === 'awaiting_approval', state: recovered.state, approvals: (await secondControlPlane.approvalList()).length, context: new SqliteContextCache(secondDatabase).get('restart-context'), graphNodes: new GraphLoop(new SqliteGraphStore(secondDatabase)).query({ labelIncludes: 'restart persistence' }).length, events: (await new EventBus(new SqliteEventStore(secondDatabase)).list()).length, observations: (await secondControlPlane.observations()).length };
47
- secondDatabase.close();
48
- console.log(JSON.stringify(result));
49
- }
50
- finally {
51
- fs.rmSync(root, { recursive: true, force: true });
52
- }