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,155 @@
1
+ # Referência de comandos
2
+
3
+ > Gerado por `forja docs:gen` a partir de `lib/core/registry.ts` — **não edite à mão.**
4
+ > 106 comandos · 34 skills distribuídas aos projetos gerados.
5
+
6
+ ## workspace
7
+
8
+ | Comando | O que faz | Uso | Tier | Gates |
9
+ |---|---|---|---|---|
10
+ | `forja workspace:init` | Cria a estrutura base do workspace (~/forja-workspace) | `forja workspace:init` | core | — |
11
+ | `forja project:new` | Cria projeto no workspace e registra ficha em 30-projects/ | `forja project:new <nome> [-- --ai claude,copilot --skip-backend] [--template <nome>]` | core | workspace |
12
+ | `forja setup` | Rotina de primeiro uso: workspace:init + sync:universal, atrás de confirmação | `forja setup [--yes]` | core | — |
13
+ | `forja project:list` | Lista projetos do workspace | `forja project:list` | advanced | — |
14
+ | `forja project:upgrade` | Traz peças novas de scaffold e religa a IA num projeto (ou --all) — aditivo; --apply aplica | `forja project:upgrade [--apply] [--project <path> \| --all] [--json]` | advanced | — |
15
+ | `forja workspace:project:check` | Valida padrões em um projeto do workspace | `forja workspace:project:check` | advanced | workspace |
16
+ | `forja project:templates` | Lista os boilerplates: quais são templates validados (project:new --template) e quais são referência | `forja project:templates [--json]` | advanced | — |
17
+ | `forja project:wire` | Conecta o projeto à inteligência do Forja: instruções nativas, hooks, sub-agents e MCP | `forja project:wire [--check] [--ai claude,codex,gemini,copilot] [--json]` | advanced | — |
18
+
19
+ ## sdd
20
+
21
+ | Comando | O que faz | Uso | Tier | Gates |
22
+ |---|---|---|---|---|
23
+ | `forja spec:new` | Cria specs/<slug>/spec.md a partir do template | `forja spec:new <slug>` | core | — |
24
+ | `forja spec:plan` | Deriva plan.md de uma spec | `forja spec:plan <slug>` | core | — |
25
+ | `forja spec:tasks` | Decompõe plan.md em tasks.md | `forja spec:tasks <slug>` | core | — |
26
+ | `forja spec:trace` | Critérios de aceite × testes que os citam (SPEC-NNN AC-N): cobertos, sem teste e órfãos | `forja spec:trace [slug] [--strict] [--json]` | advanced | — |
27
+ | `forja spec:check` | Valida completude da spec (gate de governança) | `forja spec:check [slug] [--json]` | core | — |
28
+ | `forja spec:set-status` | Atualiza o status de um artefato SDD | `forja spec:set-status` | advanced | — |
29
+
30
+ ## gsd
31
+
32
+ | Comando | O que faz | Uso | Tier | Gates |
33
+ |---|---|---|---|---|
34
+ | `forja status` | Retrato único do estado: workspace, sprint, corrida, specs, runs, handoffs | `forja status [--json]` | core | workspace-warn |
35
+ | `forja next` | A próxima ação recomendada + o comando exato para executá-la | `forja next [--json]` | core | workspace-warn |
36
+ | `forja orchestrate` | Abre uma corrida: a cadeia SDD/GSD como máquina de estados guardada por gates | `forja orchestrate "<objetivo>" --slug <slug>` | core | — |
37
+ | `forja orchestrate:status` | O estado da corrida: etapas feitas, aberta, gates e vereditos | `forja orchestrate:status <slug>` | core | — |
38
+ | `forja orchestrate:advance` | Roda o gate da etapa aberta; verde → abre a próxima; vermelho → trava com o parecer | `forja orchestrate:advance <slug>` | core | — |
39
+ | `forja gsd:plan` | Cria runbook GSD em .context/ | `forja gsd:plan` | advanced | — |
40
+ | `forja gsd:handoff` | Registra handoff GSD padronizado (ADR-0005) | `forja gsd:handoff` | advanced | — |
41
+ | `forja gsd:check` | Valida gates básicos do runbook GSD | `forja gsd:check` | advanced | — |
42
+ | `forja hermes:handoff` | Registra handoff ADR-0005 bruto via agent-router | `forja hermes:handoff` | advanced | — |
43
+ | `forja agent:route` | Roteia/inspeciona handoffs (agent-router) | `forja agent:route <append\|list [--open] [--mine\|--project <nome>] [--to <papel>]\|show\|done\|in_progress\|cancel\|archive\|schema> [args]` | advanced | — |
44
+ | `forja sprint:start` | Inicia sprint | `forja sprint:start` | advanced | — |
45
+ | `forja sprint:status` | Status da sprint atual | `forja sprint:status` | advanced | — |
46
+ | `forja sprint:complete` | Encerra sprint | `forja sprint:complete` | advanced | — |
47
+
48
+ ## design
49
+
50
+ | Comando | O que faz | Uso | Tier | Gates |
51
+ |---|---|---|---|---|
52
+ | `forja design:check` | Valida brief visual antes do handoff | `forja design:check` | advanced | — |
53
+ | `forja design:select` | Sugere referências design-md por superfície | `forja design:select` | advanced | — |
54
+
55
+ ## code
56
+
57
+ | Comando | O que faz | Uso | Tier | Gates |
58
+ |---|---|---|---|---|
59
+ | `forja code:check` | Valida índice codegraph (worktree + freshness) | `forja code:check` | advanced | — |
60
+ | `forja code:impact` | Chamadores + blast radius de um símbolo | `forja code:impact` | advanced | — |
61
+ | `forja graph:sync` | Indexa arquivos rastreáveis do workspace no GraphLoop por checksum | `forja graph:sync` | advanced | workspace-warn |
62
+ | `forja drift:check` | Reindexa e sinaliza relações verified que a extração atual não reproduz mais (SPEC-030). --domain <d> restringe; --all roda por projeto do workspace | `forja drift:check [--domain <d>] [--all]` | advanced | workspace-warn |
63
+ | `forja adr:list` | Lista ADRs (memory/90-decisions/) com status, via Engineering Graph (SPEC-032) | `forja adr:list` | advanced | workspace-warn |
64
+ | `forja adr:show` | Mostra uma ADR: status, arquivo, constraints (SPEC-032) | `forja adr:show` | advanced | workspace-warn |
65
+ | `forja adr:impact` | Componentes/documentos alcançáveis a partir de uma ADR, via GraphLoop.impact (SPEC-032) | `forja adr:impact` | advanced | workspace-warn |
66
+ | `forja adr:graph` | Subgrafo (JSON) de nós ADR/SPEC + vizinhança (SPEC-032) | `forja adr:graph` | advanced | workspace-warn |
67
+ | `forja architecture:compile` | ADRs (## Constraints) → .context/architecture/constitution.json (SPEC-033) | `forja architecture:compile` | advanced | — |
68
+ | `forja architecture:check` | Verifica o código real contra a Architecture Constitution compilada (SPEC-033) | `forja architecture:check` | advanced | workspace-warn |
69
+ | `forja architecture:status` | Resumo da Constitution: regras active/proposed, última compilação (SPEC-033) | `forja architecture:status` | advanced | — |
70
+ | `forja architecture:explain` | Explica uma regra da Constitution: ADR de origem, severidade, texto original (SPEC-033) | `forja architecture:explain` | advanced | — |
71
+ | `forja architecture:approve` | Promove uma regra proposed a active via ApprovalLedger (SPEC-033) | `forja architecture:approve` | advanced | — |
72
+ | `forja risk:assess` | Score de risco 0-100 (7 fatores) sobre o diff de um ref (default: working tree) (SPEC-034) | `forja risk:assess` | advanced | workspace-warn |
73
+ | `forja risk:explain` | Reexibe um assessment de risco já calculado, com todos os fatores (SPEC-034) | `forja risk:explain` | advanced | — |
74
+ | `forja evidence:show` | View agregada de evidência de um run: intent, agente, testes, aprovações (SPEC-035) | `forja evidence:show` | advanced | workspace-warn |
75
+ | `forja engineer` | Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado | `forja engineer "<objetivo>" [--ref <ref>] [--role <role>] [--json]` | core | workspace-warn |
76
+ | `forja agent:register` | Registra/atualiza um agente (role/provider/model/capabilities/domains) (SPEC-036) | `forja agent:register <id> --role <role> [--provider <p>] [--model <m>] [--capabilities <c1,c2>] [--domains <d1,d2>] [--max-files <n>] [--max-cost-usd <n>]` | advanced | workspace-warn |
77
+ | `forja agent:list` | Lista agentes registrados, com trustLevel se já pontuados (SPEC-036) | `forja agent:list` | advanced | workspace-warn |
78
+ | `forja agent:show` | Detalhe de um agente registrado (SPEC-036) | `forja agent:show` | advanced | workspace-warn |
79
+ | `forja agent:score` | Computa e persiste trustLevel/autonomyLevel a partir de Observation reais (SPEC-036) | `forja agent:score <id> [--domain <d>]` | advanced | workspace-warn |
80
+ | `forja agent:history` | Observations de um agente, mais recentes primeiro (SPEC-036) | `forja agent:history` | advanced | workspace-warn |
81
+ | `forja agent:recommend` | Ranking de agentes registrados por adequação a um papel/domínio — informação, não atribuição (SPEC-037) | `forja agent:recommend --role <role> [--domain <d>]` | advanced | workspace-warn |
82
+ | `forja agent:monitor` | Compara comportamento recente de um agente contra a linha de base histórica — informação, não bloqueio (SPEC-040) | `forja agent:monitor <id> [--window-hours <n>]` | advanced | workspace-warn |
83
+ | `forja incident:record` | Grava um incidente no Engineering Graph (SPEC-041) | `forja incident:record --title <t> [--description <d>]` | advanced | workspace-warn |
84
+ | `forja incident:list` | Incidentes registrados, mais recentes primeiro (SPEC-041) | `forja incident:list` | advanced | workspace-warn |
85
+ | `forja incident:similar` | Sugere incidentes parecidos por palavra-chave — sugestão, nunca aplicação automática (SPEC-041) | `forja incident:similar` | advanced | workspace-warn |
86
+ | `forja simulate` | Testa+arquitetura+risco de um ref num worktree isolado, nunca promove | `forja simulate <ref> [--command "npm test"] [--json]` | advanced | workspace-warn |
87
+ | `forja provenance:record` | Extrai proveniência (arquivo↔agente) de um RuntimeRun já persistido (SPEC-039) | `forja provenance:record` | advanced | workspace-warn |
88
+ | `forja blame` | Histórico de proveniência de um arquivo — granularidade de arquivo, não linha (SPEC-039) | `forja blame` | advanced | workspace-warn |
89
+ | `forja sbom` | AI-SBOM: relatório de proveniência agregado por agente (SPEC-039) | `forja sbom` | advanced | workspace-warn |
90
+ | `forja code:context` | Pacote de contexto mínimo de um domínio: o mapa (context.md), + código com --code (ADR-0009) | `forja code:context <domínio> [termo] [--code] [--full] [--project <path>]` | advanced | — |
91
+ | `forja code:index` | Inicializa índice codegraph | `forja code:index` | advanced | — |
92
+ | `forja code:sync` | Sincroniza índice codegraph | `forja code:sync` | advanced | — |
93
+ | `forja code:status` | Status do índice codegraph | `forja code:status` | advanced | — |
94
+ | `forja code:query` | Consulta o índice codegraph | `forja code:query` | advanced | — |
95
+
96
+ ## memoria
97
+
98
+ | Comando | O que faz | Uso | Tier | Gates |
99
+ |---|---|---|---|---|
100
+ | `forja sync:universal` | Reindexa a memória universal (SQLite FTS5) | `forja sync:universal` | core | workspace-warn |
101
+ | `forja query:universal` | Busca FTS5 na memória universal | `forja query:universal "<termo>"` | core | workspace-warn |
102
+ | `forja memory:compress` | Arquiva runs antigos e compacta memória de projeto | `forja memory:compress` | advanced | — |
103
+ | `forja memory:vacuum` | Comprime e limpa memória (archive + VACUUM) | `forja memory:vacuum` | advanced | — |
104
+ | `forja memory:schema` | Garante schema do SQLite de memória | `forja memory:schema` | advanced | — |
105
+ | `forja memory:extract` | Extrai conhecimento global da memória | `forja memory:extract` | advanced | — |
106
+ | `forja memory:audit` | Coerência mapa↔código: mapa não cita código morto (falha) + módulo sem mapa (aviso). SPEC-017 | `forja memory:audit` | advanced | — |
107
+
108
+ ## contexto
109
+
110
+ | Comando | O que faz | Uso | Tier | Gates |
111
+ |---|---|---|---|---|
112
+ | `forja context:smart` | Gera smart-context (3 modos: global \| domain \| task) | `forja context:smart [--mode global\|domain\|task] [--domain <d>] [--task <termo>] [--keyword <k>] [--project <nome>] [--full-context]` | core | workspace-warn |
113
+ | `forja context:budget` | Orçamento de tokens do contexto | `forja context:budget` | advanced | — |
114
+ | `forja context:sprint` | Pacote de contexto da sprint | `forja context:sprint` | advanced | — |
115
+ | `forja agent:brief` | Brief de contexto para um agente | `forja agent:brief` | advanced | — |
116
+ | `forja catalog:assets` | Catálogo de assets do repo | `forja catalog:assets` | advanced | — |
117
+ | `forja catalog:manifests` | Catálogo de manifests | `forja catalog:manifests` | advanced | — |
118
+ | `forja token:benchmark` | Benchmark de consumo de tokens | `forja token:benchmark` | advanced | — |
119
+ | `forja token:economy` | Economia de token: eixos arquitetura + memória; --project mede seus domínios reais | `forja token:economy [--project <path>] [--json]` | advanced | — |
120
+ | `forja benchmark:context` | Benchmark JSON determinístico de baseline, contexto mínimo, checksum e cache | `forja benchmark:context` | advanced | — |
121
+
122
+ ## llm
123
+
124
+ | Comando | O que faz | Uso | Tier | Gates |
125
+ |---|---|---|---|---|
126
+ | `forja llm:profiles:init` | Cria perfis de adapters LLM no workspace | `forja llm:profiles:init` | advanced | workspace |
127
+ | `forja llm:doctor` | Verifica adapters LLM configurados sem usar credenciais | `forja llm:doctor` | advanced | workspace |
128
+ | `forja llm:probe` | Executa probe seguro de disponibilidade dos adapters LLM | `forja llm:probe` | advanced | workspace |
129
+ | `forja llm:recommend` | Recomenda perfil LLM por papel, tarefa e evidência local | `forja llm:recommend [--role <papel>] [--task <tarefa>] [--json]` | advanced | workspace |
130
+ | `forja llm:run` | Executa um perfil LLM e registra observação normalizada. --engineer "<objetivo>" monta o contexto pelo façade | `forja llm:run [--profile <perfil>] [--task <caminho>] [--prompt <texto>] [--engineer "<objetivo>"] [--context <caminho>...] [--output-schema <arquivo>] [--validation <arquivo>] [--resume <id>] [--json]` | advanced | workspace |
131
+ | `forja llm:sessions` | Lista/mostra sessões LLM registradas (o SESSION_ID de llm:run --resume) — somente leitura (SPEC-048) | `forja llm:sessions <list\|show> [id] [--json]` | advanced | workspace |
132
+ | `forja llm:eval` | Avalia execuções LLM com métricas determinísticas | `forja llm:eval [--scope <escopo>] [--id <id>] [--json]` | advanced | workspace |
133
+ | `forja eval:agents` | Avalia agentes reais (Claude, Codex) numa suíte de tarefas do Forja, em projeto descartável — custa | `forja eval:agents --agent claude\|codex [--case a,b] [--model m] [--budget-usd n] [--timeout s] [--keep] [--list] [--json]` | advanced | — |
134
+ | `forja cost:economy` | Custo real acumulado (USD) das execuções LLM registradas, por modelo — tabela de preço local | `forja cost:economy [--json]` | advanced | workspace |
135
+
136
+ ## governanca
137
+
138
+ | Comando | O que faz | Uso | Tier | Gates |
139
+ |---|---|---|---|---|
140
+ | `forja project:check` | Standards check do framework (pre-commit) | `forja project:check` | core | — |
141
+ | `forja tools:doctor` | Raio-x do núcleo (gate, exit 1) + ferramentas de processo | `forja tools:doctor [--json]` | core | — |
142
+ | `forja hook:session-start` | Hook SessionStart: briefing de specs, handoffs e saúde do núcleo para a IA | `forja hook:session-start` | advanced | — |
143
+ | `forja hook:user-prompt` | Hook UserPromptSubmit: injeta o contexto da spec citada no prompt | `forja hook:user-prompt` | advanced | — |
144
+ | `forja hook:session-memory` | Hook Stop/PreCompact: grava o checkpoint da sessão em memory/60-runs/sessions/ | `forja hook:session-memory` | advanced | — |
145
+ | `forja demo:autonomy` | Executa a prova offline de autonomia supervisionada com Git worktree real | `forja demo:autonomy` | advanced | — |
146
+ | `forja demo:workspace` | Cria um workspace isolado e rotulado para demonstração do produto | `forja demo:workspace [--path <diretório>] [--json]` | advanced | — |
147
+ | `forja release:check` | Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito | `forja release:check [--publish]` | advanced | — |
148
+ | `forja project:smoke` | Gate do projeto gerado: gera isolado e prova que é coerente. --full instala e builda o backend; --ai <lista> valida as instruções nativas | `forja project:smoke [--full] [--ai claude,copilot,gemini,codex] [--template <nome>]` | advanced | — |
149
+ | `forja check:all` | Roda a bateria inteira de gates e dá um veredito (SPEC-020). --full inclui tarball e build | `forja check:all [--full] [--with-architecture] [--with-drift]` | advanced | — |
150
+ | `forja project:dashboard` | Gera dashboard estático de status | `forja project:dashboard` | advanced | — |
151
+ | `forja audit:sync` | Projeta a trilha de auditoria (.jsonl) numa tabela consultável (SPEC-014) | `forja audit:sync` | advanced | — |
152
+ | `forja audit:query` | Consulta a auditoria: --failed, --cmd <x>, --since 7d | `forja audit:query [--failed] [--cmd <comando>] [--gate <gate>] [--since <janela>]` | advanced | — |
153
+ | `forja docs:gen` | Regenera docs/commands.md a partir do registry — a referência completa de comandos (SPEC-055) | `forja docs:gen` | advanced | — |
154
+ | `forja quality:coverage` | Roda a suíte com a cobertura nativa do Node e cobra o piso versionado (SPEC-056) — exit 2 abaixo do piso | `forja quality:coverage [--json]` | advanced | — |
155
+ | `forja governance:dashboard` | Gera um painel HTML estático de governança (gates, SDD, auditoria) — leitura, sem servidor | `forja governance:dashboard` | advanced | — |
package/docs/fluxo.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Fluxo do 2-projeto-agents — mapa operacional
2
2
 
3
3
  **Princípio:** CLI-first. Todo o ciclo roda por linha de comando. O dashboard web
4
- (`npm run dashboard`, porta 7777) é **visão opcional read-only** — nunca é gate de
5
- spec, handoff, sprint ou entrega.
4
+ (`npm run dashboard:api` + `npm run dashboard:dev`, app na porta 3001) é **visão opcional
5
+ read-only** — nunca é gate de spec, handoff, sprint ou entrega.
6
6
 
7
7
  As 3 capacidades externas (ADR-0016) entram em pontos específicos do ciclo, sem mudar
8
8
  o pipeline SDD+GSD existente:
@@ -35,7 +35,7 @@ flowchart LR
35
35
  end
36
36
 
37
37
  ENTREGA(["✅ Entrega"])
38
- VISAO["👁 dashboard 7777 (opcional)"]
38
+ VISAO["👁 dashboard 3001 (opcional)"]
39
39
 
40
40
  IDEIA --> E1
41
41
  E6 --> ENTREGA
@@ -54,7 +54,7 @@ flowchart LR
54
54
  codegraph product sdd-arch tasks worker governance
55
55
  ai-eng (ref) spec:new spec:plan+ADR spec:tasks codegraph MCP spec:check
56
56
  harness (time) handoffs project:check
57
- ──────────────► 👁 dashboard 7777 (opcional, read-only)
57
+ ──────────────► 👁 dashboard 3001 (opcional, read-only)
58
58
  ```
59
59
 
60
60
  ---
@@ -95,9 +95,13 @@ então *opera* esses agentes pelos handoffs existentes — harness desenha, GSD
95
95
 
96
96
  ## Front (opcional)
97
97
 
98
- O dashboard sobe com `npm run dashboard` em `http://127.0.0.1:7777` e oferece uma visão
99
- read-only de specs, handoffs e agentes (`/api/health`, `/api/specs`, `/api/handoffs`,
100
- `/api/agents`). É conveniência de leitura — se não subir, **o fluxo segue 100% pela CLI**.
98
+ O dashboard sobe em dois terminais — `npm run dashboard:api` (API em `127.0.0.1:3000`) e
99
+ `npm run dashboard:dev` (app em `http://localhost:3001`) — e oferece cinco abas read-only:
100
+ Visão, Rastreio, Custo, Gates e Operação. A leitura passa por `POST /api/capabilities/:id/execute`
101
+ (só capacidades que o servidor declara sem escrita nem efeito colateral), `GET /api/graph/query`,
102
+ `GET /api/control-plane/metrics`, `GET /api/observability/observations` e `GET /api/approvals`.
103
+ É conveniência de leitura — se não subir, **o fluxo segue 100% pela CLI**. Tokens e roteiro:
104
+ `docs/produto/roteiro-demo.md`.
101
105
 
102
106
  Ver também: `docs/cli-first-operacao.md` (comandos), `docs/capacidades-externas.md`
103
107
  (detalhe das 3 capacidades), `AGENTS.md` (papéis), ADR-0016.
@@ -39,7 +39,9 @@ O workspace é resolvido por: `FORJA_WORKSPACE` → `workspaceRoot` em `~/.forja
39
39
  - `AGENTS.md` com o bloco do Forja (lido por Codex, Copilot agent e Gemini).
40
40
  - `CLAUDE.md` e `GEMINI.md` importando o `AGENTS.md`; `.github/copilot-instructions.md`.
41
41
  - `.claude/settings.json`: hooks `forja hook:session-start` (briefing da sessão) e
42
- `forja hook:user-prompt` (anexa a spec citada), mais a permissão `Bash(forja *)`.
42
+ `forja hook:user-prompt` (anexa a spec citada), `forja hook:session-memory` nos eventos `Stop` e
43
+ `PreCompact` (checkpoint da sessão em `memory/60-runs/sessions/`, ADR-0091), mais a permissão
44
+ `Bash(forja *)`.
43
45
  - `.claude/agents/`: orchestrator, product, sdd-architect, context-engineer, governance, marketing.
44
46
  - `.mcp.json`: servidor `forja mcp:start` (e `codegraph`, se instalado); o mesmo servidor em
45
47
  `.codex/config.toml` (Codex), `.gemini/settings.json` (Gemini) e `.vscode/mcp.json` (Copilot).
@@ -168,6 +168,26 @@ workspace. `forja llm:doctor` confere se a CLI instalada oferece as flags de som
168
168
  elas, o perfil fica incompatível em vez de rodar com permissões que o Forja não pediu. Retomada
169
169
  (`--resume`) continua só em Codex e Claude.
170
170
 
171
+ ## Avaliar agentes reais no método do Forja (SPEC-054, ADR-0093)
172
+
173
+ `llm:eval` agrega execuções do `llm:run`. Para saber se um agente **segue o Forja** num projeto
174
+ conectado, use a suíte de tarefas:
175
+
176
+ ```bash
177
+ forja eval:agents --list # os casos (templates/evals/agents/*.json)
178
+ forja eval:agents --agent claude # todos os casos; teto de US$ 1,00 por caso
179
+ forja eval:agents --agent codex --case adr,memoria
180
+ forja eval:agents --agent claude --model sonnet --budget-usd 0.5 --json
181
+ ```
182
+
183
+ Cada caso cria um workspace e um projeto descartáveis, aplica a semente, roda o agente e corrige de
184
+ forma determinística (arquivo criado e conteúdo, comando executado, resposta, critério coberto pelo
185
+ `spec:trace`, comando que passa, arquivos inalterados). É a única exceção ao modo somente leitura:
186
+ o agente escreve, mas só ali (Codex com `-s workspace-write`; Claude com `acceptEdits`, lista fechada
187
+ de comandos e `--max-budget-usd`). O resultado vai para `<workspace>/.context/agent-evals.jsonl` e é
188
+ comparado com a execução anterior do mesmo agente e modelo. **Custa**: cada caso é uma sessão real.
189
+ Exit 0 = tudo passou, 2 = algum caso falhou.
190
+
171
191
  ## Métricas e recomendação por custo/latência (SPEC-049)
172
192
 
173
193
  `llm:eval` acrescenta às métricas do relatório:
@@ -736,10 +736,11 @@ Nao use design como etapa obrigatoria para:
736
736
  - Checks.
737
737
  - Refatoracoes sem interface.
738
738
 
739
- Dashboard:
739
+ Dashboard (dois terminais; tokens em `docs/produto/roteiro-demo.md`):
740
740
 
741
741
  ```bash
742
- npm run dashboard
742
+ npm run dashboard:api # API em 127.0.0.1:3000
743
+ npm run dashboard:dev # app em http://localhost:3001
743
744
  ```
744
745
 
745
746
  Use somente para consulta visual ou depuracao de telas. Nao trate como fonte primaria de operacao.
@@ -133,11 +133,13 @@ supervisionada, governança e memória em uma trilha auditável.
133
133
 
134
134
  ## Estado das superfícies visuais
135
135
 
136
- - **Dashboard 2.x:** superfície de supervisão parcial via API; não é requisito do fluxo CLI-first.
137
- - **Dashboard React/Vite legado:** útil para demonstração local de telas e navegação. Em 2026-08-17,
138
- ele inicia em Node 24 com `better-sqlite3` 12 e expõe API local em `127.0.0.1:7777`; o frontend
139
- Vite fica em `http://127.0.0.1:5173`. Um workspace sem projetos ou handoffs mostra coleções vazias,
140
- não dados de demonstração inventados.
136
+ - **Dashboard 2.x (`apps/dashboard`):** superfície de supervisão via API; não é requisito do fluxo
137
+ CLI-first. O dashboard React/Vite legado foi removido (ADR-0087). Em 2026-11-08 o app Next sobe com
138
+ `npm run dashboard:api` (API em `127.0.0.1:3000`) e `npm run dashboard:dev` (app em
139
+ `http://localhost:3001`), com cinco abas: Visão, Rastreio, Custo, Gates e Operação. Um workspace sem
140
+ projetos ou handoffs mostra coleções vazias, não dados de demonstração inventados.
141
+ - O painel só executa capacidades que o servidor declara como leitura sem efeito colateral, e o proxy
142
+ falha fechado: sem `FORJA_DASHBOARD_TOKEN` nenhuma requisição é encaminhada.
141
143
  - O dashboard não executa LLMs diretamente: essa ação foi direcionada para `forja llm:run` para manter
142
144
  policy, auditoria e privacidade.
143
145
 
@@ -17,11 +17,18 @@ app com o mesmo workspace (dois terminais):
17
17
 
18
18
  ```bash
19
19
  npm --prefix apps/dashboard install
20
- FORJA_WORKSPACE=~/forja-demo-workspace npm run dashboard:api # API local em 127.0.0.1:3000
21
- npm run dashboard:dev # app em http://localhost:3001
20
+ FORJA_WORKSPACE=~/forja-demo-workspace FORJA_AUTH_TOKEN=local-demo npm run dashboard:api # API em 127.0.0.1:3000
21
+ FORJA_API_URL=http://127.0.0.1:3000 FORJA_API_TOKEN=local-demo FORJA_DASHBOARD_TOKEN=demo-local npm run dashboard:dev # app em http://localhost:3001
22
22
  ```
23
23
 
24
- No Windows PowerShell, defina `$env:FORJA_WORKSPACE = "$HOME\forja-demo-workspace"` antes de `npm run dashboard:api`.
24
+ No Windows PowerShell, defina `$env:FORJA_WORKSPACE = "$HOME\forja-demo-workspace"` e
25
+ `$env:FORJA_AUTH_TOKEN = "local-demo"` antes de `npm run dashboard:api`; no segundo terminal,
26
+ `$env:FORJA_API_URL`, `$env:FORJA_API_TOKEN = "local-demo"` e `$env:FORJA_DASHBOARD_TOKEN = "demo-local"`.
27
+
28
+ Ao abrir `http://localhost:3001` o painel pede o `FORJA_DASHBOARD_TOKEN` (`demo-local` acima) e guarda
29
+ um cookie de sessão. Os dois tokens são locais e descartáveis: `FORJA_API_TOKEN` é a credencial do
30
+ proxy para a API, `FORJA_DASHBOARD_TOKEN` é a de quem acessa o painel. Sem o segundo, o proxy recusa
31
+ toda requisição — não existe modo aberto.
25
32
 
26
33
  O dashboard mostra o estado vazio apenas se a API não estiver recebendo a variável `FORJA_WORKSPACE`
27
34
  do cenário.
@@ -32,8 +39,10 @@ do cenário.
32
39
  estado do projeto, spec aprovada, plano, tarefas e a próxima ação com o comando exato.
33
40
  2. `forja project:wire --check`: a IA, os hooks e o MCP estão conectados ao projeto.
34
41
  3. `forja context:smart --mode task --task pix`: o pack mínimo da tarefa, com a contagem de tokens.
35
- 4. No dashboard (**Control Plane**): **GraphLoop** mostra specs, ADRs e evidências ligadas;
36
- **Approvals** e **Atividade recente** mostram as decisões e execuções auditadas.
42
+ 4. No dashboard (**Forja Control Plane**), cinco abas: **Visão** (próxima ação com o comando copiável,
43
+ sprint, specs e execuções recentes), **Rastreio** (cobertura de critérios de aceite por spec),
44
+ **Custo** (USD acumulado por modelo), **Gates** (veredito do núcleo e ferramentas) e **Operação**
45
+ (**Aprovações**, **GraphLoop** com impacto por nó e **Atividade recente** auditada).
37
46
  5. Mostre `forja demo:autonomy` separadamente para a prova de sandbox Git, aprovação e promoção real.
38
47
 
39
48
  ## Regras de uso
@@ -54,7 +54,6 @@ npm run project:new meu-projeto
54
54
  # Com flags
55
55
  npm run project:new meu-projeto -- --ai claude,copilot
56
56
  npm run project:new meu-projeto -- --skip-backend
57
- npm run project:new meu-projeto -- --verbose
58
57
 
59
58
  # Dentro do projeto: conferir a conexão com a IA
60
59
  forja project:wire --check
@@ -91,8 +90,9 @@ npm run start:prod
91
90
  # Health check
92
91
  curl http://localhost:3000/api/health
93
92
 
94
- # Dashboard legado/opcional
95
- npm run dashboard
93
+ # Dashboard opcional (dois terminais; ver docs/produto/roteiro-demo.md para os tokens)
94
+ npm run dashboard:api # API em 127.0.0.1:3000
95
+ npm run dashboard:dev # app em http://localhost:3001
96
96
  ```
97
97
 
98
98
  ---
@@ -59,7 +59,7 @@ Caps em `.memoryrc.json::hooks.userPromptCap` (default 4KB). Cache em `/tmp/fram
59
59
  **Cost**: $0.0001 per request
60
60
 
61
61
  ```bash
62
- node lib/context-builder.js global my-project
62
+ forja context:smart --mode global --project my-project
63
63
  ```
64
64
 
65
65
  ---
@@ -79,7 +79,7 @@ node lib/context-builder.js global my-project
79
79
  **Cost**: $0.005 per request
80
80
 
81
81
  ```bash
82
- node lib/context-builder.js domain my-project
82
+ forja context:smart --mode domain --project my-project
83
83
  ```
84
84
 
85
85
  ---
@@ -97,9 +97,12 @@ node lib/context-builder.js domain my-project
97
97
  **Cost**: $0.008 per request
98
98
 
99
99
  ```bash
100
- node lib/context-builder.js task my-project "auth backend"
100
+ forja context:smart --mode task --task "auth backend" --project my-project
101
101
  ```
102
102
 
103
+ Nó longo entra como **trecho casado** (especificado pelo `snippet()` do FTS5), não por inteiro; o rodapé do
104
+ pacote diz quantos nós vieram cortados, e `--full-context` traz a fatia inteira quando o corte atrapalha.
105
+
103
106
  ---
104
107
 
105
108
  ## 🧠 Smart Context - How It Works
@@ -360,11 +363,12 @@ nodes = nodes.slice(0, maxFiles); // Keep top N
360
363
  ### For Backend Worker
361
364
 
362
365
  ```javascript
363
- import ContextBuilder from '../lib/context-builder.js';
366
+ import ContextBuilder from '../lib/context-builder.ts';
364
367
 
365
368
  // On task start
366
369
  const builder = new ContextBuilder(process.cwd(), dbPath);
367
- const context = builder.build('task', 'my-project', 'backend auth');
370
+ const context = builder.build('task', 'my-project', 'backend auth'); // nós longos em trecho
371
+ const integral = builder.build('task', 'my-project', 'backend auth', { full: true });
368
372
  const stats = builder.stats('task', 'my-project', 'backend auth');
369
373
 
370
374
  console.log(`📊 Using ${stats.tokens} tokens (cost: $${stats.estimatedCost})`);
@@ -394,7 +398,7 @@ const context = builder.build('global', 'my-project');
394
398
  ## 📋 Pre-Flight Checklist
395
399
 
396
400
  - [ ] `.memoryrc.json` created with token limits
397
- - [ ] `lib/context-builder.js` integrated
401
+ - [ ] `lib/context-builder.ts` integrated
398
402
  - [ ] `scripts/compress-memory.mjs` tested
399
403
  - [ ] Cache directory created: `.context/cache/`
400
404
  - [ ] Archive directory created: `.memory/archive/`
@@ -0,0 +1,40 @@
1
+ # ADR-0091: Memória de sessão por hooks (Stop, PreCompact, SessionStart)
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-10-21
5
+ - **Autor(es)**: Allan Pablo / Claude
6
+ - **Tags**: hooks, memory, claude-code
7
+
8
+ ## Contexto
9
+
10
+ O projeto conectado (ADR-0086) injeta contexto na entrada da sessão e do prompt, mas nada sai da sessão
11
+ para a memória. Na compactação a IA perde quais arquivos editou e qual spec seguia; a sessão seguinte
12
+ não sabe onde a anterior parou. O Claude Code expõe os eventos `Stop` (fim de cada turno), `PreCompact`
13
+ (antes de compactar) e `SessionStart` com `source` (`startup`, `resume`, `clear`, `compact`), todos com
14
+ o caminho do transcript JSONL.
15
+
16
+ ## Decisão
17
+
18
+ 1. **Um checkpoint determinístico por sessão** em `memory/60-runs/sessions/<data>-<id8>.md`, reescrito
19
+ por `forja hook:session-memory` no `Stop` e no `PreCompact`. Extraído do transcript sem LLM: título
20
+ da sessão, branch, arquivos editados, comandos `forja`, specs tocadas, assuntos de commit.
21
+ 2. **Nada de texto livre**: prompts, comandos inteiros e saídas de ferramenta não entram. A memória é
22
+ commitada; um segredo colado no chat não pode ir parar no git.
23
+ 3. **O SessionStart fecha o ciclo**: em `compact` devolve o checkpoint da própria sessão; em
24
+ `startup`/`resume`, uma linha sobre a última sessão.
25
+ 4. **Só grava quando houve trabalho** (edição, comando forja ou commit), para a pasta não virar log de conversa.
26
+
27
+ ## Alternativas consideradas
28
+
29
+ - **Resumo por LLM no PreCompact.** Rejeitada por ora: custa a cada compactação e o hook tem timeout
30
+ curto. O checkpoint determinístico pode alimentar um resumo depois.
31
+ - **Gravar no SQLite em vez de Markdown.** Rejeitada: `memory/` em Markdown já é indexado pelo
32
+ `sync:universal` e legível por qualquer IA; o banco é projeção.
33
+ - **Guardar os prompts (truncados).** Rejeitada pelo risco de segredo no git; o título gerado pelo
34
+ Claude Code descreve o assunto sem copiar o texto.
35
+
36
+ ## Consequências
37
+
38
+ - Projetos conectados ganham dois hooks; `project:upgrade --apply` os adiciona a projetos existentes.
39
+ - O parser depende de um formato de transcript que não é contrato público: o que não reconhece é ignorado.
40
+ - Só o Claude Code se beneficia; as outras IAs seguem com o briefing do AGENTS.md.
@@ -0,0 +1,37 @@
1
+ # ADR-0092: Critérios de aceite ligados a testes pela citação no teste
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-10-21
5
+ - **Autor(es)**: Allan Pablo / Claude
6
+ - **Tags**: sdd, testes, governanca
7
+
8
+ ## Contexto
9
+
10
+ As specs (ADR-0007) definem "pronto" em critérios `AC-N`, mas nada liga um critério ao teste que o
11
+ prova. Por costume, testes já citam `SPEC-029 AC-5` no nome ou num comentário, ou usam `AC-1:` num
12
+ arquivo dedicado a uma spec. Ninguém confere essa ligação.
13
+
14
+ ## Decisão
15
+
16
+ 1. **A ligação mora no teste**: citar `SPEC-NNN AC-N` (ou `<slug> AC-N`) no nome do teste ou num
17
+ comentário. `AC-N` sozinho vale quando o arquivo cita uma única spec. Não há arquivo de mapeamento
18
+ à parte, que envelheceria separado do teste.
19
+ 2. **`forja spec:trace`** lê specs e testes e reporta critérios cobertos, sem teste e citações órfãs.
20
+ É estático: não roda os testes, então serve para qualquer stack.
21
+ 3. **Gate opt-in**: `--strict` rejeita (exit 2) specs `approved`/`implementing`/`done` com lacunas.
22
+ Sem a flag, só informa, para não quebrar projetos com specs antigas.
23
+
24
+ ## Alternativas consideradas
25
+
26
+ - **Tabela AC → teste dentro da spec.** Rejeitada: duplica a informação e envelhece quando o teste muda de nome.
27
+ - **Rodar os testes e mapear resultados por AC.** Rejeitada por ora: depende do executor de cada stack.
28
+ A citação estática já responde "existe teste?" e "a citação aponta para algo real?".
29
+ - **Gate obrigatório no `spec:check`.** Rejeitada: specs `done` antigas passariam a falhar de uma vez.
30
+
31
+ ## Consequências
32
+
33
+ - Citar o critério vira parte de escrever o teste (AGENTS.md e skill `testing` ensinam).
34
+ - Uma citação no texto conta como cobertura, mesmo que o teste seja fraco; a revisão do teste segue humana.
35
+ - Fixtures que contêm citações de exemplo (`'SPEC-001 AC-1: …'` como dado de teste) contariam como
36
+ cobertura de uma spec real; ficam entre `spec-trace:off` e `spec-trace:on`. Achado no próprio Forja:
37
+ a SPEC-001 aparecia com 2/7 critérios cobertos só por fixtures.
@@ -0,0 +1,40 @@
1
+ # ADR-0093: Avaliações com agentes reais em projeto descartável
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-10-21
5
+ - **Autor(es)**: Allan Pablo / Claude
6
+ - **Tags**: llm, evals, qualidade, security
7
+
8
+ ## Contexto
9
+
10
+ Os testes do Forja provam que o projeto gerado tem instruções, skills, hooks e MCP no lugar. Não
11
+ provam que um agente real, lendo isso, segue o método. O `llm:run` roda os agentes somente leitura
12
+ (ADR-0090), o que impede avaliar tarefas que exigem escrever: registrar um ADR, criar uma spec,
13
+ escrever um teste.
14
+
15
+ ## Decisão
16
+
17
+ 1. **`forja eval:agents` é a única exceção à regra de somente leitura**, e só porque o alvo é
18
+ descartável: workspace e projeto criados num diretório temporário para a execução e apagados no
19
+ fim. Nunca roda no projeto do usuário.
20
+ 2. **Escrita confinada pelo próprio agente**: Codex com sandbox `workspace-write` (projeto e workspace
21
+ descartáveis como raízes graváveis); Claude com `acceptEdits` (edições no diretório de trabalho e no
22
+ `--add-dir`), lista fechada de comandos Bash e teto de custo por caso.
23
+ 3. **Casos são dados e a correção é determinística**: arquivos, comandos executados, resposta e
24
+ `spec:trace`. Sem juiz LLM, para que o resultado não oscile por causa do corretor.
25
+ 4. **Sob demanda, fora do CI**: custa dinheiro e exige credenciais. O histórico em
26
+ `.context/agent-evals.jsonl` permite comparar versões do Forja, agentes e modelos.
27
+
28
+ ## Alternativas consideradas
29
+
30
+ - **Avaliar só respostas em modo somente leitura.** Rejeitada: os comportamentos que importam
31
+ (ADR, spec, teste) são escritas.
32
+ - **Juiz LLM para corrigir.** Rejeitada por ora: adiciona custo e uma segunda fonte de variação.
33
+ - **Rodar no CI com credenciais de serviço.** Rejeitada: custo recorrente e segredos no CI para um
34
+ sinal que é útil antes de release, não a cada commit.
35
+
36
+ ## Consequências
37
+
38
+ - Mudanças em AGENTS.md, skills e hooks podem ser medidas antes do release.
39
+ - Agentes não são determinísticos; um caso pode oscilar entre execuções, e o histórico mostra isso.
40
+ - O Claude roda com as configurações globais do usuário (não é um ambiente estéril).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "5.1.0",
3
+ "version": "5.3.1",
4
4
  "description": "ForjaJS é uma plataforma local-first para memória, contexto, governança e execução supervisionada de agentes de desenvolvimento",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -90,7 +90,9 @@
90
90
  "dashboard:start": "npm --prefix apps/dashboard run start",
91
91
  "build": "tsc -p tsconfig.build.json && node -e \"for (const f of Object.values(require('./package.json').bin)) require('fs').chmodSync(f, 0o755)\"",
92
92
  "types:check": "tsc --noEmit",
93
- "test": "node --test test/*.test.js",
93
+ "docs:gen": "node bin/forja.ts docs:gen",
94
+ "test": "node --test --import ./test/isolate-workspace.mjs test/*.test.js",
95
+ "test:coverage": "node bin/forja.ts quality:coverage",
94
96
  "demo:autonomy": "node bin/forja.ts demo:autonomy",
95
97
  "demo:workspace": "node bin/forja.ts demo:workspace",
96
98
  "benchmark:context": "node bin/forja.ts benchmark:context",
@@ -0,0 +1,52 @@
1
+ # Spec: avaliacoes-de-agentes
2
+
3
+ - **ID**: SPEC-054
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-10-21
7
+ - **Sprint alvo**: 5.2
8
+ - **ADRs relacionadas**: [ADR-0090](../../memory/90-decisions/0090-adapters-de-agente-somente-leitura.md) (adapters somente leitura), ADR-0093 (esta feature)
9
+
10
+ ## 1. Problema
11
+ O Forja promete que, num projeto conectado, a IA segue o método: registra ADR em
12
+ `memory/90-decisions/`, cria spec com `forja spec:new`, liga teste a critério, consulta a memória antes
13
+ de responder. Os testes provam que os arquivos (AGENTS.md, skills, hooks, MCP) estão no lugar, mas
14
+ nada prova que um agente de verdade, lendo esses arquivos, faz a coisa certa. Uma mudança no
15
+ AGENTS.md ou numa skill pode piorar o comportamento sem nenhum teste ficar vermelho. O `llm:eval`
16
+ agrega execuções do `llm:run`, que é somente leitura e não tem tarefa nem gabarito. Medição hoje:
17
+ nenhuma.
18
+
19
+ ## 2. Proposta de valor
20
+ `forja eval:agents` roda uma suíte fixa de tarefas com um agente real (Claude Code ou Codex) num
21
+ projeto Forja descartável e corrige cada uma de forma determinística, olhando o que ficou no disco,
22
+ os comandos executados e a resposta. O resultado vira histórico, comparado com a execução anterior
23
+ do mesmo agente e modelo.
24
+
25
+ ## 3. User stories
26
+ - **Como** mantenedor do Forja, **quero** saber se uma mudança no AGENTS.md ou numa skill piorou o
27
+ comportamento dos agentes, **para que** a regressão apareça antes do release.
28
+ - **Como** usuário escolhendo entre Claude e Codex, **quero** ver qual segue melhor o método do Forja, **para que** a escolha tenha evidência.
29
+ - **Como** dono da máquina, **quero** que o agente avaliado só escreva no projeto descartável e que o custo tenha teto, **para que** rodar a suíte não tenha efeito colateral.
30
+
31
+ ## 4. Critérios de aceite (Definition of Done)
32
+ - [ ] AC-1: `forja eval:agents [--agent claude|codex] [--case a,b] [--model m] [--budget-usd n] [--json]` cria um workspace e um projeto descartáveis (`project:new --ai claude,codex`), aplica a semente de cada caso, roda o agente no projeto e corrige; o `forja` que o agente chama é o da instalação em teste.
33
+ - [ ] AC-2: os casos são dados (`templates/evals/agents/*.json`: id, prompt, semente, checks) e os checks são determinísticos: arquivo por glob com conteúdo, resposta, comando executado, critério coberto (`spec:trace`), comando que passa e arquivos inalterados.
34
+ - [ ] AC-3: a suíte inicial cobre ADR no lugar certo, spec criada pelo `spec:new`, teste que cita `SPEC-NNN AC-N`, resposta tirada da memória do projeto e próxima ação via `forja next`/`status`.
35
+ - [ ] AC-4: o agente só escreve no projeto e no workspace descartáveis: Codex com `-s workspace-write` (`-C` projeto, `--add-dir` workspace); Claude com `--permission-mode acceptEdits`, lista fechada de comandos Bash e `--max-budget-usd` por caso.
36
+ - [ ] AC-5: o resultado (por caso e por check, custo, duração) é anexado a `<workspace>/.context/agent-evals.jsonl` e comparado com a última execução do mesmo agente e modelo (casos que passaram a falhar ou a passar).
37
+ - [ ] AC-6: exit 0 quando todos os casos passam, 2 (`rejected`) quando algum falha, 1 quando o agente não está instalado ou o caso não existe; `--json` segue o contrato (ADR-0082).
38
+ - [ ] AC-7: o runner e os checks são testados offline com um agente falso; nenhum teste da suíte chama um provedor real.
39
+
40
+ ## 5. Requisitos não-funcionais
41
+ - **Custo**: teto por caso (`--budget-usd`, padrão 1,00 no Claude); timeout por caso (padrão 300 s) nos dois.
42
+ - **Segurança**: nada fora dos diretórios descartáveis; o workspace real do usuário só recebe a linha de histórico.
43
+ - **Reprodutibilidade**: o histórico registra versão do Forja, agente, modelo e versão da CLI.
44
+
45
+ ## 6. Fora de escopo
46
+ - Rodar no CI (custa e exige credenciais); fica sob demanda.
47
+ - Gemini, Cursor, opencode e Copilot CLI (entram com adapters de escrita confinada depois).
48
+ - Correção por LLM (juiz); só checks determinísticos.
49
+
50
+ ## 7. Riscos e dependências
51
+ - Agentes não são determinísticos: um caso pode oscilar. O histórico mostra a oscilação; `--repeat` fica para depois.
52
+ - O Claude usa as configurações globais do usuário (hooks, plugins) além das do projeto; é o ambiente real, mas não é estéril.