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.
- package/CHANGELOG.md +108 -0
- package/README.md +52 -4
- package/README.pt-BR.md +54 -4
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +365 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +26 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/exec.d.ts +55 -0
- package/dist/lib/exec.js +141 -0
- package/dist/lib/project-wiring.js +6 -2
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/packages/adapter-git/src/index.js +13 -4
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/llm/src/index.js +7 -24
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/llm-fit.js +15 -6
- package/dist/scripts/simulate.js +16 -4
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +20 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +104 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +7 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/skills/testing/SKILL.md +1 -1
package/docs/commands.md
ADDED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
99
|
-
|
|
100
|
-
|
|
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.
|
package/docs/init-project.md
CHANGED
|
@@ -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),
|
|
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).
|
package/docs/llm-fit-loop.md
CHANGED
|
@@ -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
|
|
137
|
-
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
|
21
|
-
npm run dashboard:dev
|
|
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"`
|
|
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**): **
|
|
36
|
-
|
|
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
|
package/docs/quick-reference.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
"
|
|
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.
|