forjajs 5.1.0 → 5.3.1

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 (119) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +52 -4
  3. package/README.pt-BR.md +54 -4
  4. package/dist/apps/cli/src/index.d.ts +0 -1
  5. package/dist/apps/cli/src/index.js +43 -32
  6. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  7. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  8. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  10. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  11. package/dist/apps/server/src/forja-nest.module.js +55 -0
  12. package/dist/apps/server/src/main.d.ts +21 -4
  13. package/dist/apps/server/src/main.js +79 -57
  14. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  15. package/dist/apps/server/src/task-planning-service.js +195 -0
  16. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  17. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  18. package/dist/bin/forja.js +3 -2
  19. package/dist/lib/agent-evals.d.ts +138 -0
  20. package/dist/lib/agent-evals.js +365 -0
  21. package/dist/lib/cli-output.js +14 -2
  22. package/dist/lib/code-context.d.ts +33 -5
  23. package/dist/lib/code-context.js +70 -5
  24. package/dist/lib/context-builder.d.ts +49 -4
  25. package/dist/lib/context-builder.js +114 -47
  26. package/dist/lib/core/coverage-gate.d.ts +59 -0
  27. package/dist/lib/core/coverage-gate.js +58 -0
  28. package/dist/lib/core/doc-graph.d.ts +38 -0
  29. package/dist/lib/core/doc-graph.js +83 -0
  30. package/dist/lib/core/health.js +286 -5
  31. package/dist/lib/core/journey.js +26 -0
  32. package/dist/lib/core/registry.js +81 -6
  33. package/dist/lib/docs-reference.d.ts +35 -0
  34. package/dist/lib/docs-reference.js +57 -0
  35. package/dist/lib/exec.d.ts +55 -0
  36. package/dist/lib/exec.js +141 -0
  37. package/dist/lib/project-wiring.js +6 -2
  38. package/dist/lib/session-memory.d.ts +38 -0
  39. package/dist/lib/session-memory.js +206 -0
  40. package/dist/lib/spec-trace.d.ts +46 -0
  41. package/dist/lib/spec-trace.js +184 -0
  42. package/dist/packages/adapter-git/src/index.js +13 -4
  43. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  44. package/dist/packages/adapter-nest/src/index.js +59 -1
  45. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  46. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  47. package/dist/packages/context/src/index.d.ts +2 -0
  48. package/dist/packages/context/src/index.js +36 -15
  49. package/dist/packages/contracts/src/index.d.ts +64 -0
  50. package/dist/packages/core/src/index.d.ts +9 -1
  51. package/dist/packages/core/src/index.js +28 -3
  52. package/dist/packages/graph/src/index.js +14 -5
  53. package/dist/packages/llm/src/index.js +7 -24
  54. package/dist/packages/mcp/src/index.d.ts +8 -0
  55. package/dist/packages/mcp/src/index.js +12 -1
  56. package/dist/packages/observability/src/index.d.ts +11 -0
  57. package/dist/packages/observability/src/index.js +3 -0
  58. package/dist/packages/orchestration/src/index.d.ts +15 -1
  59. package/dist/packages/orchestration/src/index.js +127 -21
  60. package/dist/packages/planner/src/index.d.ts +7 -1
  61. package/dist/packages/planner/src/index.js +67 -10
  62. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  63. package/dist/packages/planner/src/proposal-store.js +109 -0
  64. package/dist/packages/policy/src/index.d.ts +9 -16
  65. package/dist/packages/policy/src/index.js +114 -31
  66. package/dist/packages/runtime/src/index.d.ts +16 -2
  67. package/dist/packages/runtime/src/index.js +176 -61
  68. package/dist/scripts/build-smart-context.d.ts +2 -0
  69. package/dist/scripts/build-smart-context.js +12 -3
  70. package/dist/scripts/code-context.d.ts +3 -1
  71. package/dist/scripts/code-context.js +13 -3
  72. package/dist/scripts/coverage-gate.d.ts +2 -0
  73. package/dist/scripts/coverage-gate.js +101 -0
  74. package/dist/scripts/eval-agents.d.ts +11 -0
  75. package/dist/scripts/eval-agents.js +96 -0
  76. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  77. package/dist/scripts/gen-commands-doc.js +18 -0
  78. package/dist/scripts/hook-session-memory.d.ts +9 -0
  79. package/dist/scripts/hook-session-memory.js +20 -0
  80. package/dist/scripts/hook-session-start.js +34 -0
  81. package/dist/scripts/llm-fit.js +15 -6
  82. package/dist/scripts/simulate.js +16 -4
  83. package/dist/scripts/spec-trace.d.ts +10 -0
  84. package/dist/scripts/spec-trace.js +73 -0
  85. package/dist/scripts/sync-universal-memory.js +69 -4
  86. package/dist/scripts/token-benchmark.d.ts +33 -1
  87. package/dist/scripts/token-benchmark.js +179 -5
  88. package/dist/scripts/token-economy.js +3 -1
  89. package/dist/scripts/tools-doctor.d.ts +16 -1
  90. package/dist/scripts/tools-doctor.js +58 -17
  91. package/docs/commands.md +155 -0
  92. package/docs/fluxo.md +11 -7
  93. package/docs/init-project.md +3 -1
  94. package/docs/llm-fit-loop.md +20 -0
  95. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  96. package/docs/produto/factsheet-marketing.md +7 -5
  97. package/docs/produto/roteiro-demo.md +14 -5
  98. package/docs/quick-reference.md +3 -3
  99. package/docs/token-optimization.md +10 -6
  100. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  101. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  102. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  103. package/package.json +4 -2
  104. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  105. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  106. package/specs/memoria-de-sessao/spec.md +48 -0
  107. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  108. package/specs/v6-core-consolidation/spec.md +70 -0
  109. package/specs/v6-docs-drift/spec.md +85 -0
  110. package/specs/v6-quality-gates/spec.md +104 -0
  111. package/specs/v6-token-economy/spec.md +84 -0
  112. package/templates/evals/agents/adr.json +25 -0
  113. package/templates/evals/agents/memoria.json +32 -0
  114. package/templates/evals/agents/proxima-acao.json +29 -0
  115. package/templates/evals/agents/spec-nova.json +26 -0
  116. package/templates/evals/agents/teste-do-criterio.json +29 -0
  117. package/templates/project/AGENTS.md +7 -0
  118. package/templates/project/CLAUDE.md +3 -2
  119. package/templates/project/skills/testing/SKILL.md +1 -1
@@ -0,0 +1,32 @@
1
+ {
2
+ "id": "memoria",
3
+ "title": "Resposta vem da memória do projeto",
4
+ "prompt": "Um cliente perguntou em quantos dias úteis vence um boleto no nosso produto. Qual é a regra e em que arquivo do projeto ela está registrada? Não altere nada.",
5
+ "seed": {
6
+ "files": {
7
+ "memory/30-domains/cobranca/context.md": "# Cobrança — contexto\n\n## Regras\n\n- Boleto vence em **3 dias úteis** a partir da emissão.\n- Pix expira em 30 minutos.\n- Cartão é capturado na hora.\n"
8
+ }
9
+ },
10
+ "checks": [
11
+ {
12
+ "type": "answer",
13
+ "desc": "responde 3 dias úteis",
14
+ "matches": [
15
+ "\\b3\\b|\\btr[eê]s\\b",
16
+ "[uú]teis"
17
+ ]
18
+ },
19
+ {
20
+ "type": "answer",
21
+ "desc": "cita o arquivo de memória",
22
+ "matches": [
23
+ "memory/30-domains/cobranca"
24
+ ]
25
+ },
26
+ {
27
+ "type": "unchanged",
28
+ "desc": "não alterou a memória",
29
+ "glob": "memory/**"
30
+ }
31
+ ]
32
+ }
@@ -0,0 +1,29 @@
1
+ {
2
+ "id": "proxima-acao",
3
+ "title": "Próxima ação vem do forja",
4
+ "prompt": "Acabei de voltar de férias. O que devo fazer agora neste projeto? Seja breve e não altere nada.",
5
+ "seed": {
6
+ "files": {
7
+ "specs/exportar-relatorios/spec.md": "# Spec: exportar-relatorios\n\n- **ID**: SPEC-001\n- **Status**: approved\n- **Owner**: time\n- **Criado em**: 2026-10-01\n\n## 1. Problema\nClientes copiam a tabela de relatórios à mão para a planilha.\n\n## 4. Critérios de aceite (Definition of Done)\n- [ ] AC-1: o relatório mensal pode ser baixado em CSV.\n"
8
+ }
9
+ },
10
+ "checks": [
11
+ {
12
+ "type": "ran",
13
+ "desc": "consultou forja next ou status",
14
+ "matches": "forja\\s+(next|status)|mcp__forja__(next|status)"
15
+ },
16
+ {
17
+ "type": "answer",
18
+ "desc": "recomenda o plano da spec aprovada",
19
+ "matches": [
20
+ "spec:plan|plan\\.md|plano"
21
+ ]
22
+ },
23
+ {
24
+ "type": "unchanged",
25
+ "desc": "não alterou specs",
26
+ "glob": "specs/**"
27
+ }
28
+ ]
29
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "id": "spec-nova",
3
+ "title": "Feature nova começa por spec, pelo spec:new",
4
+ "prompt": "Queremos que o cliente consiga exportar o extrato da conta em PDF. Comece essa feature do jeito que este projeto pede. Não escreva código ainda.",
5
+ "checks": [
6
+ {
7
+ "type": "ran",
8
+ "desc": "criou a spec com forja spec:new",
9
+ "matches": "forja\\s+spec:new|mcp__forja__spec_new"
10
+ },
11
+ {
12
+ "type": "file",
13
+ "desc": "spec com ID e critério de aceite preenchido",
14
+ "glob": "specs/*/spec.md",
15
+ "contains": [
16
+ "\\*\\*ID\\*\\*: *SPEC-\\d+",
17
+ "^- \\[ \\] \\**AC-1\\b[^:\\n]*: *[^<\\s]"
18
+ ]
19
+ },
20
+ {
21
+ "type": "unchanged",
22
+ "desc": "não escreveu código",
23
+ "glob": "src/**"
24
+ }
25
+ ]
26
+ }
@@ -0,0 +1,29 @@
1
+ {
2
+ "id": "teste-do-criterio",
3
+ "title": "Teste cita o critério que prova",
4
+ "prompt": "Escreva o teste automatizado que prova o critério AC-1 da spec de pagamentos. Use o executor de testes nativo do Node (node --test). Não altere o código de produção.",
5
+ "seed": {
6
+ "files": {
7
+ "specs/pagamentos/spec.md": "# Spec: pagamentos\n\n- **ID**: SPEC-001\n- **Status**: approved\n- **Owner**: time\n- **Criado em**: 2026-10-01\n\n## 1. Problema\nPagamentos com valor zero ou negativo chegam ao gateway e são recusados lá, tarde demais.\n\n## 4. Critérios de aceite (Definition of Done)\n- [ ] AC-1: `validarValor` rejeita valor zero ou negativo com erro \"valor inválido\".\n- [ ] AC-2: `validarValor` devolve o valor quando ele é positivo.\n",
8
+ "src/pagamentos.js": "export function validarValor(valor) {\n if (!(valor > 0)) throw new Error('valor inválido');\n return valor;\n}\n"
9
+ }
10
+ },
11
+ "checks": [
12
+ {
13
+ "type": "criterion",
14
+ "desc": "um teste cita SPEC-001 AC-1 (spec:trace)",
15
+ "spec": "pagamentos",
16
+ "ac": "AC-1"
17
+ },
18
+ {
19
+ "type": "command",
20
+ "desc": "os testes passam",
21
+ "run": "node --test"
22
+ },
23
+ {
24
+ "type": "unchanged",
25
+ "desc": "não mexeu no código de produção",
26
+ "glob": "src/pagamentos.js"
27
+ }
28
+ ]
29
+ }
@@ -33,6 +33,7 @@ forja spec:set-status <slug> spec approved # depois da revisão
33
33
  forja spec:plan <slug> # plan.md (exige spec aprovada)
34
34
  forja spec:tasks <slug> # tasks.md
35
35
  forja spec:check <slug> # gate de completude
36
+ forja spec:trace <slug> # critérios AC-N × testes que os citam
36
37
  forja orchestrate "<objetivo>" --slug <slug> # corrida guardada por gates
37
38
  forja orchestrate:advance # roda o gate da etapa aberta
38
39
  ```
@@ -45,8 +46,13 @@ forja code:impact <símbolo> # quem chama e o que quebra
45
46
  forja project:check # documentação de fundação
46
47
  forja tools:doctor # saúde do Forja e das ferramentas
47
48
  forja project:wire --check # IA, hooks e MCP conectados a este projeto
49
+ forja spec:trace <slug> --strict # todo critério da spec tem teste (exit 2 se não)
48
50
  ```
49
51
 
52
+ Teste que prova um critério cita a spec e o critério no nome ou num comentário: `SPEC-NNN AC-N`
53
+ (ex.: `test('SPEC-004 AC-2: estorno parcial', …)`). É o que o `spec:trace` lê.
54
+ Fixture com citações de exemplo fica entre comentários `spec-trace:off` e `spec-trace:on`.
55
+
50
56
  ## Onde fica cada coisa
51
57
 
52
58
  ```
@@ -56,6 +62,7 @@ memory/20-architecture/ design técnico
56
62
  memory/30-domains/ regras por domínio
57
63
  memory/40-delivery/ roadmap, sprint, backlog
58
64
  memory/50-orchestration/ topologia e handoffs
65
+ memory/60-runs/sessions/ checkpoint de cada sessão do Claude Code (gerado pelos hooks; não edite)
59
66
  memory/70-summaries/ resumos compactos (prefira a arquivos brutos)
60
67
  memory/90-decisions/ ADRs
61
68
  specs/<slug>/ spec → plan → tasks
@@ -3,7 +3,8 @@
3
3
  ## Claude Code neste projeto
4
4
 
5
5
  - Os hooks em `.claude/settings.json` abrem cada sessão com o estado do projeto (`forja hook:session-start`)
6
- e anexam a spec citada no prompt (`forja hook:user-prompt`). Se o briefing não aparecer, rode
7
- `forja project:wire --check`.
6
+ e anexam a spec citada no prompt (`forja hook:user-prompt`); ao fim de cada turno e antes de compactar,
7
+ `forja hook:session-memory` grava o checkpoint da sessão em `memory/60-runs/sessions/`. Se o
8
+ briefing não aparecer, rode `forja project:wire --check`.
8
9
  - O servidor MCP `forja` (`.mcp.json`) expõe as capacidades do Forja como ferramentas.
9
10
  - Sub-agents de cada papel ficam em `.claude/agents/`. Delegue a eles quando a tarefa cruzar papéis.
@@ -95,7 +95,7 @@ Feche com **Pendentes**: regras que dependem de suposições não confirmadas e
95
95
 
96
96
  ## No Forja
97
97
 
98
- No Forja, os critérios de aceite estão em `specs/<slug>/spec.md` (§4, `AC-n`). Nomeie os casos citando o `AC-n` que cobrem, para a ligação spec → teste ficar rastreável, e registre a evidência na seção "Evidências e estado real" da spec.
98
+ No Forja, os critérios de aceite estão em `specs/<slug>/spec.md` (§4, `AC-n`). Nomeie os casos citando a spec e o critério que cobrem, `SPEC-NNN AC-N` (ex.: `test('SPEC-004 AC-2: estorno parcial', …)`), e confira com `forja spec:trace <slug>`: critérios sem teste e citações a critérios que não existem mais aparecem ali. Registre a evidência na seção "Evidências e estado real" da spec.
99
99
 
100
100
  ## Evite
101
101