forjajs 5.0.1 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +114 -2
- package/README.md +40 -5
- package/README.pt-BR.md +42 -4
- package/boilerplates/02-saas-starter/README.md +58 -293
- package/boilerplates/02-saas-starter/backend/.env.example +13 -0
- package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
- package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
- package/boilerplates/02-saas-starter/backend/package.json +32 -73
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
- package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
- package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
- package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
- package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
- package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
- package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
- package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
- package/boilerplates/README.md +9 -10
- 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/bin/init-project.js +1 -0
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +349 -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 +36 -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/generators/memory-generator.d.ts +0 -11
- package/dist/lib/generators/memory-generator.js +5 -161
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/llm/json-output.d.ts +14 -0
- package/dist/lib/llm/json-output.js +77 -0
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +79 -3
- 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/lib/validators/structure-validator.js +0 -1
- 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 +12 -2
- 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 +23 -1
- 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 +36 -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/0088-templates-validados.md +3 -0
- package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
- package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
- 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/skills-do-projeto/plan.md +40 -0
- package/specs/skills-do-projeto/spec.md +63 -0
- package/specs/skills-do-projeto/tasks.md +27 -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 +99 -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 +16 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/agents/context-engineer.md +3 -0
- package/templates/project/agents/governance.md +3 -0
- package/templates/project/agents/marketing.md +3 -0
- package/templates/project/agents/orchestrator.md +3 -0
- package/templates/project/agents/product.md +3 -0
- package/templates/project/agents/sdd-architect.md +3 -0
- package/templates/project/skills/README.md +14 -0
- package/templates/project/skills/accessibility-review/SKILL.md +89 -0
- package/templates/project/skills/api-design/SKILL.md +77 -0
- package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
- package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
- package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
- package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
- package/templates/project/skills/commit-message/SKILL.md +143 -0
- package/templates/project/skills/data-migrations/SKILL.md +88 -0
- package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
- package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
- package/templates/project/skills/domain-modeling/SKILL.md +120 -0
- package/templates/project/skills/event-storming/SKILL.md +95 -0
- package/templates/project/skills/executive-writing/SKILL.md +99 -0
- package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
- package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
- package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
- package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
- package/templates/project/skills/observability/SKILL.md +93 -0
- package/templates/project/skills/product-evaluation/SKILL.md +130 -0
- package/templates/project/skills/prompt-spec/SKILL.md +83 -0
- package/templates/project/skills/pull-request/SKILL.md +101 -0
- package/templates/project/skills/query-performance/SKILL.md +83 -0
- package/templates/project/skills/release-checklist/SKILL.md +106 -0
- package/templates/project/skills/release-notes/SKILL.md +87 -0
- package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
- package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
- package/templates/project/skills/technical-spike/SKILL.md +101 -0
- package/templates/project/skills/testing/SKILL.md +109 -0
- package/templates/project/skills/threat-modeling/SKILL.md +87 -0
- package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
- package/templates/project/skills/ts-code-review/SKILL.md +121 -0
- package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
- package/templates/project/skills/ts-testing/SKILL.md +89 -0
- package/templates/project/skills/web-performance/SKILL.md +72 -0
- package/boilerplates/02-saas-starter/.env.example +0 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
- package/boilerplates/02-saas-starter/INFO.md +0 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
- package/boilerplates/02-saas-starter/START-HERE.md +0 -259
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
|
@@ -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.0
|
|
3
|
+
"version": "5.3.0",
|
|
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.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Spec: criterios-ligados-a-testes
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-053
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0007](../../memory/90-decisions/0007-sdd-pipeline.md) (SDD), ADR-0092 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
Uma spec diz o que é "pronto" nos critérios de aceite (`AC-N`), mas nada liga um critério ao teste
|
|
12
|
+
que o prova. Uma spec vira `done` com critérios sem teste, e um critério renumerado deixa testes
|
|
13
|
+
apontando para o critério errado, sem ninguém notar. A convenção existe por costume (`SPEC-029 AC-5`
|
|
14
|
+
no nome do teste), mas ninguém a confere. Medição hoje: não sabemos quantos ACs têm teste.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
`forja spec:trace` mostra, para cada critério de cada spec, os testes que o citam, e aponta os
|
|
18
|
+
critérios sem teste e as citações órfãs. Com `--strict`, vira gate para specs aprovadas ou prontas.
|
|
19
|
+
|
|
20
|
+
## 3. User stories
|
|
21
|
+
- **Como** governance, **quero** ver quais critérios de uma spec `done` não têm teste, **para que** "pronto" signifique provado.
|
|
22
|
+
- **Como** dev, **quero** saber que citar `SPEC-053 AC-2` no nome do teste basta, **para que** a ligação não custe nada.
|
|
23
|
+
- **Como** dev que editou a spec, **quero** ser avisado de testes citando um critério que não existe mais, **para que** a rastreabilidade não minta.
|
|
24
|
+
|
|
25
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
26
|
+
- [ ] AC-1: `forja spec:trace [slug]` lista cada `AC-N` da spec e os testes que o citam (arquivo:linha), e resume `N/M critérios com teste`.
|
|
27
|
+
- [ ] AC-2: um teste cita um critério escrevendo `SPEC-NNN AC-N`, `<slug> AC-N` ou listas (`SPEC-029 AC-5/AC-6`, `AC-1, AC-2`); `AC-N` sozinho vale para a spec quando o arquivo de teste cita uma única spec (pelo ID, pelo slug, por `specs/<slug>/` ou pelo nome do arquivo, `<slug>.test.js`) e o critério existe nela; senão, é listado como ambíguo.
|
|
28
|
+
- [ ] AC-3: citação qualificada de critério inexistente (`SPEC-053 AC-9` sem AC-9) aparece como órfã.
|
|
29
|
+
- [ ] AC-4: arquivos de teste são achados em qualquer stack (`*.test.*`, `*.spec.*`, `test_*.py`, `*_test.go`, pastas `test/`, `tests/`, `__tests__/`), ignorando `node_modules`, `dist`, `.git` e `coverage`.
|
|
30
|
+
- [ ] AC-5: `--strict` sai com 2 (`rejected`) quando uma spec `approved`, `implementing` ou `done` tem critério sem teste ou citação órfã; sem `--strict` o comando só informa (exit 0). `--json` segue o contrato (ADR-0082).
|
|
31
|
+
- [ ] AC-6: o `AGENTS.md` do projeto gerado e a skill `testing` ensinam a convenção.
|
|
32
|
+
|
|
33
|
+
## 5. Requisitos não-funcionais
|
|
34
|
+
- **Performance**: repo do Forja (~90 arquivos de teste, ~50 specs) em < 2 s.
|
|
35
|
+
- **Segurança**: somente leitura.
|
|
36
|
+
|
|
37
|
+
## 6. Fora de escopo
|
|
38
|
+
- Rodar os testes e marcar o critério como verde/vermelho (fica para o executor de testes de cada stack).
|
|
39
|
+
- Editar specs ou testes automaticamente.
|
|
40
|
+
|
|
41
|
+
## 7. Riscos e dependências
|
|
42
|
+
- `AC-N` sozinho num arquivo que cita várias specs é ambíguo: não conta para nenhuma (o relatório diz por quê).
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Spec: memoria-de-sessao
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-052
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0086](../../memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md) (projeto conectado), ADR-0091 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O que acontece numa sessão de IA só fica no transcript, que o Forja não lê. Quando o contexto é
|
|
12
|
+
compactado, a IA perde o fio (quais arquivos mexeu, qual spec estava seguindo, o que já commitou), e a
|
|
13
|
+
sessão seguinte começa do zero: o briefing do SessionStart mostra specs e handoffs, mas nada sobre o
|
|
14
|
+
que foi feito por último. Medição hoje: 0 registros de sessão em `memory/` de qualquer projeto.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
Toda sessão do Claude Code que muda alguma coisa deixa um checkpoint determinístico na memória do
|
|
18
|
+
projeto, atualizado ao fim de cada turno e antes de cada compactação. Depois de compactar, a IA recebe
|
|
19
|
+
o checkpoint de volta; numa sessão nova, vê onde a anterior parou. Sem chamar LLM, sem custo.
|
|
20
|
+
|
|
21
|
+
## 3. User stories
|
|
22
|
+
- **Como** dev numa sessão longa, **quero** que a IA, depois da compactação, saiba quais arquivos já
|
|
23
|
+
editou e qual spec estava seguindo, **para que** ela não refaça nem contradiga o trabalho.
|
|
24
|
+
- **Como** dev abrindo uma sessão nova, **quero** ver onde a última parou, **para que** eu retome sem reler o histórico.
|
|
25
|
+
- **Como** dono do projeto, **quero** que nenhum texto de prompt ou comando inteiro vá para a memória
|
|
26
|
+
commitada, **para que** um segredo colado no chat não acabe no git.
|
|
27
|
+
|
|
28
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
29
|
+
- [x] AC-1: `forja hook:session-memory` lê o JSON do hook (stdin: `session_id`, `transcript_path`, `cwd`, `hook_event_name`) e grava `memory/60-runs/sessions/<AAAA-MM-DD>-<id8>.md` com: título da sessão (`ai-title`), branch, arquivos editados (Edit/Write/MultiEdit/NotebookEdit, relativos ao projeto), comandos `forja <cmd>` (só o nome), specs tocadas (citadas em caminhos editados ou em comandos `forja spec:*`) e assuntos de `git commit -m`.
|
|
30
|
+
- [x] AC-2: sessão sem edição, sem comando forja e sem commit não grava nada; o mesmo `session_id` reescreve o mesmo arquivo (idempotente); o arquivo não contém texto de prompt.
|
|
31
|
+
- [x] AC-3: o hook nunca derruba a sessão: transcript ausente, JSON inválido ou projeto sem `memory/` saem com 0 e sem saída.
|
|
32
|
+
- [x] AC-4: `project:wire` registra o hook nos eventos `Stop` e `PreCompact` do `.claude/settings.json`, e `project:wire --check` (check `claude-hooks`) falha se faltar algum dos quatro eventos.
|
|
33
|
+
- [x] AC-5: `hook:session-start` lê o `source` do stdin: em `compact` injeta o checkpoint da própria sessão; em `startup`/`resume` injeta uma linha com a última sessão registrada (data, título, nº de arquivos, specs).
|
|
34
|
+
- [x] AC-6: a jornada (`lib/core/journey.ts`) cobre o caminho: transcript sintético → checkpoint gravado → SessionStart `compact` o devolve.
|
|
35
|
+
|
|
36
|
+
## 5. Requisitos não-funcionais
|
|
37
|
+
- **Performance**: transcript de 10 MB processado em < 1 s (linhas sem `tool_use`/`ai-title` são descartadas antes do `JSON.parse`); timeout do hook 10 s.
|
|
38
|
+
- **Segurança/LGPD**: sem texto de prompt, sem argumentos de comando além do nome do subcomando `forja`, sem saída de ferramenta.
|
|
39
|
+
- **Observabilidade**: não audita (hooks já são excluídos da trilha, `bin/forja.ts`).
|
|
40
|
+
|
|
41
|
+
## 6. Fora de escopo
|
|
42
|
+
- Resumo por LLM da sessão (custo; pode vir depois, alimentado por este checkpoint).
|
|
43
|
+
- Gate de "pronto" no Stop (bloquear o fim do turno com testes vermelhos).
|
|
44
|
+
- Codex/Gemini/Copilot: não têm eventos equivalentes de fim de turno e compactação com transcript em disco.
|
|
45
|
+
|
|
46
|
+
## 7. Riscos e dependências
|
|
47
|
+
- Formato do transcript do Claude Code não é contrato público: o parser ignora o que não reconhece e degrada para "nada a gravar".
|
|
48
|
+
- Checkpoints entram no git do projeto como o resto de `memory/`; quem não quiser ignora `memory/60-runs/sessions/`.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Plan: skills-do-projeto
|
|
2
|
+
|
|
3
|
+
- **Spec**: [spec.md](spec.md) (SPEC-051)
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
|
|
8
|
+
## 1. Abordagem técnica
|
|
9
|
+
As skills vivem em `templates/project/skills/<nome>/SKILL.md` (cópia versionada do ledger em pt-BR, commit
|
|
10
|
+
`0097ed7`, com seções "No Forja"). O `wireProject` as instala em `.claude/skills/` (Claude) e
|
|
11
|
+
`.agents/skills/` (Codex) com a marca `forja:managed`; o `checkProjectWiring` valida frontmatter,
|
|
12
|
+
referências entre skills e os comandos `forja` que elas citam. O gerador deixa de emitir `skills/`.
|
|
13
|
+
|
|
14
|
+
## 2. Módulos afetados
|
|
15
|
+
- `templates/project/skills/` (novo), `templates/project/agents/*.md`, `templates/project/AGENTS.md`
|
|
16
|
+
- `lib/project-wiring.ts` (instalação + checks `skills-claude`/`skills-codex`)
|
|
17
|
+
- `lib/generators/memory-generator.ts`, `lib/validators/structure-validator.ts`, `lib/generators/readme-generator.ts`
|
|
18
|
+
- `lib/core/journey.ts`, `test/project-skills.test.js`
|
|
19
|
+
|
|
20
|
+
## 3. Diagrama de fluxo
|
|
21
|
+
`project:new` / `project:upgrade` / `project:wire` → `wireProject` → `.claude/skills/*`, `.agents/skills/*` → `project:wire --check`.
|
|
22
|
+
|
|
23
|
+
## 4. Contratos (API/CLI/Schema)
|
|
24
|
+
Sem comando novo. `project:wire --check --json` ganha os checks `skills-claude` e `skills-codex`.
|
|
25
|
+
|
|
26
|
+
## 5. Decisões e alternativas
|
|
27
|
+
- Instalar todas as skills, inclusive `ts-*`, em vez de filtrar por linguagem: filtrar deixaria referências quebradas (ADR-0089).
|
|
28
|
+
- Cópia versionada em vez de dependência do repositório do ledger em tempo de geração.
|
|
29
|
+
|
|
30
|
+
## 6. Dependências
|
|
31
|
+
Nenhuma dependência de pacote nova.
|
|
32
|
+
|
|
33
|
+
## 7. Rollout
|
|
34
|
+
Projetos novos recebem na geração; existentes via `forja project:upgrade --apply`.
|
|
35
|
+
|
|
36
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
37
|
+
IAs não carregam as skills nos diretórios escolhidos; ou skills disparam em contexto errado com frequência.
|
|
38
|
+
|
|
39
|
+
## Evidências e estado real
|
|
40
|
+
- `npm test` 556/556; jornada com o passo `skills` (30 + 30).
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Spec: skills-do-projeto
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-051
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.1
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0086](../../memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md) (projeto conectado), ADR-0089 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
Todo projeto gerado recebe 9 "skills" de 5 a 10 linhas em `skills/` na raiz, sem frontmatter.
|
|
12
|
+
Nenhuma IA as carrega: o Claude Code lê `.claude/skills/<nome>/SKILL.md`, o Codex lê
|
|
13
|
+
`.agents/skills/`, e ambos exigem `name`/`description` no frontmatter. Na prática o Forja não
|
|
14
|
+
entrega skills; os papéis (product, sdd-architect, governance…) não têm um método escrito para
|
|
15
|
+
seguir. Medição hoje: 0 skills carregáveis por projeto.
|
|
16
|
+
|
|
17
|
+
## 2. Proposta de valor
|
|
18
|
+
Todo projeto passa a ter as 29 skills do ledger (pt-BR), carregáveis pelas IAs, ligadas aos papéis
|
|
19
|
+
e aos artefatos do Forja (specs, ADRs, handoffs, incidentes), e verificadas pelo `project:wire --check`.
|
|
20
|
+
|
|
21
|
+
## 3. User stories
|
|
22
|
+
- **Como** dev usando Claude Code ou Codex num projeto Forja, **quero** que a IA encontre sozinha a
|
|
23
|
+
skill certa (requisitos, modelagem, ADR, code review…), **para que** o método seja seguido sem eu colar prompts.
|
|
24
|
+
- **Como** sdd-architect, **quero** que `architecture-decision-record` grave no formato do Forja
|
|
25
|
+
(`memory/90-decisions/`, `forja adr:list`), **para que** a skill e o processo não divirjam.
|
|
26
|
+
- **Como** dono de um projeto em Python, **quero** que as skills de TypeScript só sejam usadas em
|
|
27
|
+
código TS/JS, **para que** a IA não aplique idiomas da linguagem errada.
|
|
28
|
+
|
|
29
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
30
|
+
- [ ] AC-1: `project:new` instala as skills em `.claude/skills/<nome>/SKILL.md` (Claude) e em `.agents/skills/<nome>/SKILL.md` (Codex), com frontmatter válido e `name` igual à pasta.
|
|
31
|
+
- [ ] AC-2: todas as skills são instaladas, inclusive as `ts-*`: outras skills as citam pelo nome (`testing` → `ts-testing`), e omiti-las deixaria referências quebradas. O que restringe o uso é a descrição ("TypeScript ou JavaScript"), que é o que a IA usa para decidir quando carregar a skill.
|
|
32
|
+
- [ ] AC-3: as skills que produzem artefatos do Forja trazem uma seção "No Forja" com o destino e o comando (ADR → `memory/90-decisions/`; requisitos/backlog → `specs/<slug>/`; prompt-spec → handoff ADR-0005; postmortem → `forja incident:record`; release-notes → `### O que melhorou`).
|
|
33
|
+
- [ ] AC-4: `project:wire --check` tem um check `skills` que falha com skill ausente, frontmatter inválido ou referência a skill inexistente; `wire` é idempotente e não sobrescreve skill editada pelo usuário (sem a marca `forja:managed`).
|
|
34
|
+
- [ ] AC-5: as 9 skills de esboço deixam de ser geradas; `llm-provider-routing` vira skill com frontmatter.
|
|
35
|
+
- [ ] AC-6: cada sub-agent de `.claude/agents/` lista as skills do seu papel.
|
|
36
|
+
- [ ] AC-7: a jornada (`lib/core/journey.ts`) verifica as skills instaladas no pacote instalado; `project:upgrade` as traz para projetos existentes.
|
|
37
|
+
|
|
38
|
+
## 5. Escopo
|
|
39
|
+
**Dentro**:
|
|
40
|
+
- 29 skills do ledger + `llm-provider-routing`, com seções "No Forja".
|
|
41
|
+
- Instalação/verificação no `project:wire`; remoção das skills de esboço do gerador.
|
|
42
|
+
|
|
43
|
+
**Fora** (explícito, evita scope creep):
|
|
44
|
+
- Sincronização automática com o repositório do ledger (cópia versionada no Forja; atualizar é um PR).
|
|
45
|
+
- Diretório de skills do Gemini CLI (descoberta por pasta não verificada; uso via `gemini skills link`).
|
|
46
|
+
- Skills para o próprio repositório do framework.
|
|
47
|
+
|
|
48
|
+
## 6. NFRs / restrições
|
|
49
|
+
- Compatibilidade: projetos existentes recebem as skills só via `project:upgrade --apply`; nada é sobrescrito sem a marca.
|
|
50
|
+
- Idioma: pt-BR; `name` em inglês (identificador).
|
|
51
|
+
|
|
52
|
+
## 7. Riscos e mitigação
|
|
53
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
54
|
+
|---|---|---|---|
|
|
55
|
+
| Skill ensina comando do Forja que não existe | M | A | check `commands` do wire já cobre todo `forja <cmd>` citado; skills entram nos textos verificados |
|
|
56
|
+
| Divergência entre a cópia do Forja e o ledger | A | M | cópia versionada; seção "No Forja" separada facilita reaplicar |
|
|
57
|
+
| Skills demais poluem o contexto | B | M | as IAs carregam só nome+descrição até a skill ser usada |
|
|
58
|
+
|
|
59
|
+
## 8. Métricas de sucesso
|
|
60
|
+
Projeto novo: 0 → 30 skills carregáveis. `project:wire --check` verde.
|
|
61
|
+
|
|
62
|
+
## Evidências e estado real
|
|
63
|
+
- AC-1..AC-7: ver tasks.md e os testes `test/project-skills.test.js` e `test/journey.test.js`.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Tasks: skills-do-projeto
|
|
2
|
+
|
|
3
|
+
- **Plan**: [plan.md](plan.md)
|
|
4
|
+
- **Status**: done
|
|
5
|
+
|
|
6
|
+
## T1 — Skills versionadas com seções "No Forja" (AC-3, AC-5)
|
|
7
|
+
- [x] 29 skills do ledger + `llm-provider-routing` em `templates/project/skills/`; 15 com "No Forja".
|
|
8
|
+
- Evidência: `test/project-skills.test.js`.
|
|
9
|
+
|
|
10
|
+
## T2 — Instalação e verificação no project:wire (AC-1, AC-2, AC-4)
|
|
11
|
+
- [x] `.claude/skills/` e `.agents/skills/`; marca `forja:managed`; checks `skills-claude`/`skills-codex`.
|
|
12
|
+
- Evidência: teste manual de idempotência e de skill editada preservada; `project:wire --check`.
|
|
13
|
+
|
|
14
|
+
## T3 — Gerador sem as skills de esboço (AC-5)
|
|
15
|
+
- [x] Removidas as 9 skills e o `skill-loader.mjs`; validador não exige `skills/`.
|
|
16
|
+
|
|
17
|
+
## T4 — Sub-agents e AGENTS.md (AC-6)
|
|
18
|
+
- [x] Seção "Skills" por papel; teste garante que as citadas existem.
|
|
19
|
+
|
|
20
|
+
## T5 — Jornada e upgrade (AC-7)
|
|
21
|
+
- [x] Passo `skills` na jornada; `project:upgrade` instala via `wireProject`.
|
|
22
|
+
|
|
23
|
+
## Handoffs entre agentes
|
|
24
|
+
Nenhum.
|
|
25
|
+
|
|
26
|
+
## Evidências e estado real
|
|
27
|
+
- `npm test` 556/556.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Spec: v6-agent-runtime-portable
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-059
|
|
4
|
+
- **Status**: draft
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-08
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 2
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O forja fala com agentes de IA por subprocesso, e essa fronteira foi escrita para unix. Estado validado em 2026-11-08 (`packages/llm/src/index.ts`, `scripts/llm-fit.ts`, `lib/agent-evals.ts`, log da rodada 4 da célula `windows-latest` no PR #83, v5.2.0):
|
|
12
|
+
|
|
13
|
+
- **`llm:run` não spawnar o provedor** — `runLlm()` faz `spawn(executable, args, { shell: false, detached: true })` (`packages/llm/src/index.ts:123`). No Windows o que `npm i -g` instala é `claude.cmd`/`codex.cmd`, e o Node recusa spawnar `.bat`/`.cmd` sem `shell: true` desde o endurecimento da CVE-2024-27980 (18.20.2 / 20.12.2 / 21.7.3), com `EINVAL`. Toda execução termina em `errorCode: 'SPAWN_FAILED'`, exit 127, antes de falar com o provedor. **Não existe versão de Node suportada em que isso funcione**: a matriz do CI roda 22 e 24, ambas do lado endurecido.
|
|
14
|
+
- **`llm:doctor`/`llm:probe` mentem sobre o que está instalado** — as seis sondagens de binário usam `shell: false` explícito (`scripts/llm-fit.ts:76,84,86,91,104,108`). O mesmo `EINVAL` vira `available: false`, e o comando reporta "provedor indisponível" para uma CLI instalada e funcionando, saindo com código 1 se o perfil estiver habilitado. O `detail` traz o errno cru, não o diagnóstico.
|
|
15
|
+
- **`eval:agents` tem duas frentes unix** — `timed()`/`cliVersion()` spawnam o binário direto (`lib/agent-evals.ts:177,183`, mesma restrição do probe), e o check `type: 'command'` roda via `spawnSync('sh', ['-c', …])` (`lib/agent-evals.ts:254`). Sem `sh`, checks declarativos como `"run": "node --test"` (`templates/evals/agents/teste-do-criterio.json:21`) são inaplicáveis — ainda que o comando em si seja perfeitamente portável.
|
|
16
|
+
- **Timeout não derruba a árvore** — `killGroup()` mata com `process.kill(-pid, 'SIGTERM')` (`packages/llm/src/index.ts:132-140`). Grupo de processo por pid negativo é POSIX; no Windows lança e cai no `child.kill(signal)`, que (a) não alcança os netos — o CLI real que o shim `.cmd` spawnou sobrevive — e (b) não tem o grace de `SIGTERM_GRACE_MS`, porque sinal em Windows é emulação: `kill('SIGTERM')` termina incondicionalmente. O orçamento de custo do forja pressupõe que um agente estourando o timeout para de queimar token.
|
|
17
|
+
|
|
18
|
+
Quem sente: usuário Windows (`llm:run`/`llm:doctor`/`eval:agents` não funcionam, e um agente em timeout continua rodando e cobrando), agente de IA consumindo o doctor (relatório falso de disponibilidade), maintainer (esta família é 6 dos 10 casos que seguram o `continue-on-error` da célula Windows, SPEC-056 AC-4).
|
|
19
|
+
|
|
20
|
+
**Honestidade sobre os 6 casos do CI**: eles falham porque os testes modelam o CLI do agente como script com shebang + `chmod 0o755` (`test/agent-evals.test.js` AC-4/AC-5/AC-6, `test/llm-resume-validation.test.js:142` → `spawn EFTYPE`, `test/llm-claude-adapter.test.js:99`, `test/llm-integration.test.js:111`). O fixture é unix-cêntrico, mas o que ele expõe é o caminho real do produto: em Windows um binário de agente **é** um `.cmd`, e o produto não resolve `.cmd`. Consertar só o fixture — um stub em Node, por exemplo — deixaria a suíte verde com `llm:run` quebrado em produção. Por isso o AC-3 obriga o stub falso a passar pelo `.cmd`, em vez de desviar dele.
|
|
21
|
+
|
|
22
|
+
## 2. Proposta de valor
|
|
23
|
+
Um único módulo de execução de subprocesso (`lib/exec.ts`) que resolve o binário do agente (`where`/`PATHEXT`), escapa argumentos para `cmd.exe` quando o SO exige, derruba a árvore do processo no timeout e oferece um launcher de shell portável para checks declarativos. `llm:run`, `llm:doctor`, `llm:probe` e `eval:agents` passam a funcionar nos três SOs, e o primeiro item do inventário da SPEC-056 AC-4 — o único que quebra o produto do usuário em produção, e não o CI — zera.
|
|
24
|
+
|
|
25
|
+
Sem dependência nova, de propósito: o que falta são ~40 linhas de quoting que conseguimos testar exaustivamente, inclusive contra injeção. Importar `cross-spawn` para isso colocaria na cadeia de suprimento de uma CLI publicada um pacote que já teve o seu próprio CVE (ReDoS, CVE-2024-21538) — é o mesmo defeito que a SPEC-058 ataca, importar uma segunda máquina para o que a primeira já faz. A decisão fica registrada em ADR, com a alternativa documentada em vez de esquecida (R-1).
|
|
26
|
+
|
|
27
|
+
## 3. User stories
|
|
28
|
+
- **Como** usuário Windows, **quero** que `forja llm:run` encontre o `claude`/`codex` que o npm instalou, **para que** eu use o framework sem depender de WSL.
|
|
29
|
+
- **Como** operador, **quero** que o `llm:doctor` distinga "não instalado" de "instalado mas o forja não conseguiu executar", **para que** o relatório não me mande reinstalar o que já está lá.
|
|
30
|
+
- **Como** maintainer rodando `eval:agents` com orçamento, **quero** que o timeout derrube a árvore inteira do agente, **para que** um caso estourado não continue queimando token depois do resultado sair.
|
|
31
|
+
- **Como** contribuidor, **quero** escrever checks `type: 'command'` com comandos portáveis e vê-los rodar em qualquer SO, **para que** a suíte de evals não seja um ativo só de unix.
|
|
32
|
+
|
|
33
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
34
|
+
- [ ] AC-1: os quatro call sites de fronteira de agente passam por `lib/exec.ts` (`resolveCommand`, `spawnAgent`, `runShell`, `killTree`): `packages/llm/src/index.ts:123`, `scripts/llm-fit.ts:76,84,86,91,104,108`, `lib/agent-evals.ts:177,183` e `lib/agent-evals.ts:254`. Spawn de `git`, `node` e `process.execPath` continua como está — não é a fronteira em questão e mexer nele seria escopo emprestado.
|
|
35
|
+
- [ ] AC-2 (segurança): o quoting de argumentos para `cmd.exe` é provado por teste com argumentos hostis — `"`, `&`, `|`, `>`, `<`, `%VAR%`, `^`, espaço, caminho com `\` — chegando ao processo-filho byte a byte como foi passado, e nenhum deles executando um segundo comando. O prompt do usuário e o comando do perfil são argumentos: sem este AC, o AC-1 trocava `EINVAL` por injeção. `shell: true` do Node nunca é usado (ele não escapa argumentos).
|
|
36
|
+
- [ ] AC-3 (fixture não desvia do produto): o stub de agente dos testes é um `.cmd` no Windows e continua script com shebang em unix, executado pelo mesmo resolver do produto. Os 6 casos do inventário ficam verdes na célula Windows **sem skip**.
|
|
37
|
+
- [ ] AC-4 (a árvore morre junto): em timeout, `runLlm` derruba filho e netos nos três SOs — no Windows por `taskkill /pid <pid> /T /F` ou equivalente, em POSIX pelo pid negativo como hoje. Teste: agente falso de dois níveis cujo neto escreve a cada 100ms para de escrever depois do grace, nos dois SOs. `exitCode: 124` / `errorCode: 'TIMEOUT'` não mudam.
|
|
38
|
+
- [ ] AC-5 (diagnóstico honesto): binário não encontrável → `available: false` com `detail` dizendo o que foi procurado (caminho resolvido, `PATHEXT`); binário encontrável que falha ao executar → outro detail. O contrato `--json` (ADR-0082) e os campos existentes não mudam, só o conteúdo de `detail`.
|
|
39
|
+
- [ ] AC-6 (checks `command`): `type: 'command'` roda por `runShell`, que usa `sh -c` em POSIX e `%ComSpec% /d /s /c` no Windows; as suítes de `templates/evals/agents/*.json` rodam inteiras nos três SOs. `CheckResult` não ganha estado novo nesta spec.
|
|
40
|
+
|
|
41
|
+
## 5. Escopo
|
|
42
|
+
**Dentro**:
|
|
43
|
+
- `lib/exec.ts` (novo) + `test/exec.test.js` (novo): resolver, quoting, `killTree`, `runShell`.
|
|
44
|
+
- `packages/llm/src/index.ts`: `runLlm` aceita launcher injetável — o pacote hoje importa só `node:child_process` e continua assim; quem injeta é o `scripts/llm-fit.ts`.
|
|
45
|
+
- `scripts/llm-fit.ts`: as seis sondagens do doctor e a chamada de `runLlm`.
|
|
46
|
+
- `lib/agent-evals.ts`: `timed()`, `cliVersion()` e o check `command`.
|
|
47
|
+
- Fixtures dos quatro arquivos de teste do inventário: stub portável.
|
|
48
|
+
|
|
49
|
+
**Fora**:
|
|
50
|
+
- `cross-spawn`/`execa`/qualquer dependência nova (§2, R-1).
|
|
51
|
+
- Estado `skipped` em `CheckResult` — muda o JSON que o dashboard de evals consome; decisão separada.
|
|
52
|
+
- Os outros dois itens do inventário Windows (`git worktree` em `test/simulate-cli.test.js`, `spec:trace 0/0` na jornada) e a linha `continue-on-error` do `ci.yml`, que só sai quando o inventário inteiro zerar.
|
|
53
|
+
- WSL como caminho suportado: é contorno, não solução, e o framework já é usado fora dele.
|
|
54
|
+
- Reescrever checks `command` de usuários em Node: o launcher portável resolve sem exigir migração.
|
|
55
|
+
|
|
56
|
+
## 6. NFRs / restrições
|
|
57
|
+
- Segurança: fronteira de subprocesso com argumento vindo de usuário (prompt) e de configuração (comando do perfil). Quoting é requisito, não otimização.
|
|
58
|
+
- Compatibilidade: em POSIX/macOS nenhum comportamento muda — o caminho direto continua vencendo quando existe, como no `inside()` da SPEC-056. Zero regressão nos 666 testes das células ubuntu/macos.
|
|
59
|
+
- Superfície: um módulo, quatro funções. `hasBinary()` (`lib/project-wiring.ts:98`) já resolve binário por plataforma com `where`/`which` — o módulo segue essa convenção em vez de inventar outra, e ela passa a ser caso particular de `resolveCommand`.
|
|
60
|
+
- Custo: zero minuto novo de CI (os testes rodam na matriz que já existe).
|
|
61
|
+
|
|
62
|
+
## 7. Riscos e mitigação
|
|
63
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| Quoting de `cmd.exe` escrito à mão deixar passar injeção | M | A | AC-2 com casos hostis explícitos; ADR registra o que foi testado; alternativa (dependência) documentada em vez de esquecida |
|
|
66
|
+
| `taskkill /T` não alcançar neto de shim `.cmd` encadeado | M | M | AC-4 mede com agente falso de dois níveis; se não alcançar, o detail do timeout reporta quantos processos restaram |
|
|
67
|
+
| Consertar o fixture e não o produto (suíte verde, `llm:run` quebrado) | M | A | AC-3 obriga o stub a ser `.cmd` no Windows e a passar pelo resolver do produto |
|
|
68
|
+
| Launcher injetável em `runLlm` quebrar o contrato dos adapters | B | M | Injeção com default = comportamento atual; testes existentes de resume/timeout continuam provando o mesmo contrato |
|
|
69
|
+
| `resolveCommand` escolher binário errado (PATH com duplicados) | B | M | `where` lista todos; o módulo usa o primeiro e o AC-5 expõe o caminho resolvido no `detail` |
|
|
70
|
+
| `runShell` executar comando de check com semântica diferente por SO | M | M | AC-6 roda as suítes template nos três SOs; comando que não é portável falha com o launcher no detail, não silenciosamente |
|
|
71
|
+
|
|
72
|
+
## 8. Métricas de sucesso
|
|
73
|
+
30 dias após: `llm:run`, `llm:doctor` e `eval:agents` verdes na célula Windows do CI; inventário da SPEC-056 AC-4 de 3 causas/10 casos para 2 causas/4 casos; zero relato de "provedor indisponível" em máquina com o provedor instalado; nenhum caso novo nos testes de injeção de argumento.
|
|
74
|
+
|
|
75
|
+
## Evidências e estado real
|
|
76
|
+
Levantamento de 2026-11-08, branch `feat/v6-wave1` (PR #83), por leitura de código e log da rodada 4 — sem patch adivinhado:
|
|
77
|
+
|
|
78
|
+
- **Call sites lidos, um a um**: `packages/llm/src/index.ts:123` (`spawn` com `shell: false, detached: true`), `:132-140` (`killGroup` com `process.kill(-pid)` e fallback `child.kill`), `scripts/llm-fit.ts:76,84,86,91,104,108` (seis sondagens com `shell: false`), `lib/agent-evals.ts:177,183` (spawn direto do binário do agente), `:254` (`spawnSync('sh', ['-c', check.run])`).
|
|
79
|
+
- **Os 6 casos da célula Windows**: `test/llm-resume-validation.test.js:142` (`spawn EFTYPE`), `test/agent-evals.test.js` AC-4/AC-5/AC-6 (`agent.args` nunca escrito), `test/llm-claude-adapter.test.js:99`, `test/llm-integration.test.js:111`. Os 2 casos do AC-1 da SPEC-054, que eram desta família, ficaram verdes na rodada 2 — o que confirma que a causa deles era o CRLF das skills, não o stub, e é o motivo de esta spec não reivindicá-los.
|
|
80
|
+
- **Restrição do Node**: spawn de `.bat`/`.cmd` sem `shell: true` lança `EINVAL` desde 18.20.2 / 20.12.2 / 21.7.3 (endurecimento da CVE-2024-27980). A matriz do CI roda Node 22 e 24: as duas células estão do lado endurecido, então não há versão suportada em que o código atual funcione no Windows.
|
|
81
|
+
- **Comando do check template é portável, o launcher não**: `"run": "node --test"` em `templates/evals/agents/teste-do-criterio.json:21` roda igual em `cmd.exe`; o que impede é o `sh` fixo na linha 254.
|
|
82
|
+
- **Convenção que já existe no repo**: `lib/project-wiring.ts:98` usa `where` no Windows e `which` no resto. Também por isso o caminho é um módulo só — não quatro remendos de plataforma espalhados pelos call sites.
|
|
83
|
+
- **Estado**: spec em draft, nenhuma linha de produto escrita. A implementação depende de aprovação e roda na mesma branch da Wave 2.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Spec: v6-core-consolidation
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-058
|
|
4
|
+
- **Status**: draft
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-05
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 2
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O núcleo do forja cresceu por acréscimo e hoje há múltiplas implementações para a mesma responsabilidade. Estado validado em 2026-11-05 (v5.2.0):
|
|
12
|
+
|
|
13
|
+
- **6 leitores independentes** do audit trail `.context/forja-runs.jsonl` (`lib/governance-report.ts`, `lib/status-model.ts`, `lib/audit.ts`, `scripts/memory-schema.ts`, `scripts/risk.ts`, `scripts/audit-sync.ts`) — cada um com seu parsing; um bug de formato precisa ser corrigido 6×.
|
|
14
|
+
- **`process.exit(1)` em 32 arquivos** e `cli-output.ts` adotado em apenas **8 de 54 scripts** — saída e códigos de erro inconsistentes entre comandos.
|
|
15
|
+
- **`audit()` silencia sem workspace**: `bin/forja.ts` tem `if (!info.exists) return;` — comandos rodados fora de projeto forja não geram trilha (por design atual, mas sem alternativa de log mínimo).
|
|
16
|
+
- **`any` em 360 pontos** do código do repo (341 `: any` + 19 `as any`; 0 em `packages/` e `apps/`) — fronteiras internas sem contrato de tipo.
|
|
17
|
+
- Dispatch de comandos via processos `node:` separados (99 dos 104 comandos do registry) — overhead de spawn por comando e estado não compartilhado.
|
|
18
|
+
- Gates declarados em apenas **39 dos 104 comandos**, sem middleware uniforme de execução.
|
|
19
|
+
- `apps/worker` dormente desde 2026-08-01; `specs/clean-arch-boilerplate` ainda "approved" sem implementação — ativos ambíguos no repo.
|
|
20
|
+
|
|
21
|
+
Quem sente: maintainer (cada mudança toca N pontos), agentes de IA (saída inconsistente), contribuidores (sem contrato claro).
|
|
22
|
+
|
|
23
|
+
## 2. Proposta de valor
|
|
24
|
+
Uma única implementação por responsabilidade no núcleo: módulo de auditoria único, camada de saída/erros uniforme, gates como middleware e dispatch in-process — mudanças de comportamento passam de "editar N arquivos" para "editar 1 módulo", com tipos contratuais nas fronteiras.
|
|
25
|
+
|
|
26
|
+
## 3. User stories
|
|
27
|
+
- **Como** maintainer, **quero** um único módulo `audit` que lê/grava o JSONL, **para que** formato e migrações mudem em um só lugar.
|
|
28
|
+
- **Como** agente de IA consumindo saída do forja, **quero** formato e códigos de saída uniformes em todos os comandos, **para que** eu possa parsear sem casos especiais por comando.
|
|
29
|
+
- **Como** contribuidor, **quero** gates executados por um middleware do registry, **para que** adicionar gate a um comando seja declarativo, não código novo.
|
|
30
|
+
- **Como** usuário, **quero** dispatch in-process dos comandos `node:`, **para que** cada comando tenha menos latência de spawn.
|
|
31
|
+
|
|
32
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
33
|
+
- [ ] AC-1: Módulo único de auditoria (`lib/audit-core.ts` ou equivalente) é a **única** implementação de leitura/escrita do JSONL; os 6 consumidores atuais o utilizam (grep confirma zero parsing direto remanescente).
|
|
34
|
+
- [ ] AC-2: Camada uniforme de saída/erros: `cli-output` (ou sucessor) adotado nos 54 scripts; `process.exit(1)` direto eliminado ou restrito ao entrypoint `bin/forja.ts`.
|
|
35
|
+
- [ ] AC-3: Gates executados por middleware do dispatch: comando declara gate no registry e o runner aplica (pré/pós), sem código de gate por script; os 39 gates atuais preservados com mesmo comportamento (testes).
|
|
36
|
+
- [ ] AC-4: Dispatch in-process para comandos `node:` com fallback a spawn quando o módulo exigir (documentado); latência média por comando medida antes/depois nas evidências.
|
|
37
|
+
- [ ] AC-5: Fronteiras dos módulos públicos tipadas: `any` reduzido em ≥ 50% da baseline (360 → ≤ 180), com teto do lint (SPEC-056) acompanhando a redução.
|
|
38
|
+
- [ ] AC-6: Destino de `apps/worker` e `specs/clean-arch-boilerplate` decidido e executado (arquivar com status explícito ou reativar) — zero ativos "aprovados/dormentes" sem decisão.
|
|
39
|
+
|
|
40
|
+
## 5. Escopo
|
|
41
|
+
**Dentro**:
|
|
42
|
+
- Consolidação de auditoria, saída/erros, gates middleware, dispatch.
|
|
43
|
+
- Tipagem das fronteiras (redução de `any`).
|
|
44
|
+
- Decisão sobre worker/specs stale.
|
|
45
|
+
|
|
46
|
+
**Fora**:
|
|
47
|
+
- Mudança do formato do JSONL de auditoria (compatibilidade com trilhas existentes é obrigatória; migração só se inevitável, com ADR).
|
|
48
|
+
- Consolidação de `packages/` do monorepo além do necessário para o dispatch (pode virar ADR própria).
|
|
49
|
+
- Reescrita de comandos `bin:` (4) — continuam via shell.
|
|
50
|
+
- Redução de `any` em código gerado por templates de projeto.
|
|
51
|
+
|
|
52
|
+
## 6. NFRs / restrições
|
|
53
|
+
- Compatibilidade: trilhas JSONL antigas continuam legíveis; `forja-runs.jsonl` sem breaking change de schema.
|
|
54
|
+
- Performance: dispatch in-process não pode aumentar p95 de comando simples; AC-4 mede.
|
|
55
|
+
- Segurança: auditoria continua imutável (append-only); nenhum caminho novo permite edição de trilha.
|
|
56
|
+
- Observabilidade: erros uniformes incluem código estável de erro por classe de falha.
|
|
57
|
+
|
|
58
|
+
## 7. Riscos e mitigação
|
|
59
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
60
|
+
|---|---|---|---|
|
|
61
|
+
| Refatorar 6 leitores + 54 scripts em um PR gigante | A | A | Fatiar: AC-1 primeiro (audit-core), depois AC-2, cada um com testes e merge próprio |
|
|
62
|
+
| Dispatch in-process vazar estado entre comandos | M | A | Isolamento por contexto explícito; fallback spawn; testes de concorrência |
|
|
63
|
+
| Redução de `any` introduzir regressões de runtime | M | M | Teto decrescente (SPEC-056) + suíte completa multi-OS antes de cada merge |
|
|
64
|
+
| Mudar gates quebrar `release:check`/`project:smoke` | B | A | Gates atuais com snapshot de comportamento antes da migração |
|
|
65
|
+
|
|
66
|
+
## 8. Métricas de sucesso
|
|
67
|
+
30 dias após: 1 implementação de auditoria (grep = 0 duplicatas); 100% dos scripts na camada de saída uniforme; `any` ≤ 180; latência média de comando ≤ valor pré-refatoração; zero issues de trilha de auditoria ilegível.
|
|
68
|
+
|
|
69
|
+
## Evidências e estado real
|
|
70
|
+
- Diagnóstico validado em 2026-11-05 contra v5.2.0: 6 leitores JSONL confirmados por grep; `process.exit(1)` em 32 arquivos; `cli-output` em 8/54 scripts; `any`=360 (0 em packages/apps); registry 104 comandos (99 node:, 4 bin:, 1 outro; 39 com gates); `audit()` skip sem workspace em `bin/forja.ts`; worker último commit 2026-08-01; spec clean-arch "approved".
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Spec: v6-docs-drift
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-055
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-05
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 1
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
A documentação (README.md, README.pt-BR.md, docs/) deriva do código e ninguém detecta a deriva até um usuário tropeçar nela. Estado validado em 2026-11-05 no repo (v5.2.0):
|
|
12
|
+
|
|
13
|
+
- `forja setup` não era mencionado em nenhum dos dois READMEs (0 ocorrências) — o onboarding não estava documentado.
|
|
14
|
+
- O registry tem 104 comandos; o README EN documentava **72** únicos e o pt-BR **42** — 32 comandos não apareciam em lugar nenhum (não havia referência completa).
|
|
15
|
+
- **12 comandos** não declaravam `usage` no registry, embora os READMEs documentassem suas flags (`agent:route --open/--mine`, `llm:run --profile`, `audit:query --failed` etc.) — a fonte única estava incompleta, e não o README errado.
|
|
16
|
+
- Drift de sintaxe de flags: registry declara `[-- --ai ...]` em `project:new`, `README.md:139` documenta `--ai` direto (as duas formas funcionam — o `--` é repassado e ignorado pelo gerador; o check passa a validar **existência** da flag, não o estilo do separador).
|
|
17
|
+
- `README.pt-BR.md` **não estava em `DOC_SURFACES`**: o scanner de "doc como dado" lia README.md/README.en.md e era cego para a superfície em português.
|
|
18
|
+
- Contagem de skills nos READMEs ("34") **estava correta**: `templates/project/skills/` tem 34 pastas + 1 README.md (35 entradas). A regra de contagem existe para impedir drift futuro, não para corrigir o atual.
|
|
19
|
+
|
|
20
|
+
Quem sente: novos usuários (onboarding quebrado), agentes de IA que leem o README como fonte de verdade, e o maintainer (correção manual tardia).
|
|
21
|
+
|
|
22
|
+
## 2. Proposta de valor
|
|
23
|
+
As regras de coerência doc × código vivem **no catálogo do doctor** (`lib/core/health.ts`), que já é gate no CI e na bateria `check:all` — deriva de documentação vira falha `critical` no PR, sem criar uma segunda máquina de ler markdown (princípio do repo: duas máquinas iguais divergem com o tempo; é exatamente o defeito que a SPEC-058 ataca). A referência completa de comandos (`docs/commands.md`) passa a ser **gerada** do registry por `forja docs:gen`, e o check `commands-ref` garante que ninguém a edita à mão.
|
|
24
|
+
|
|
25
|
+
## 3. User stories
|
|
26
|
+
- **Como** maintainer, **quero** que o doctor compare registry ↔ doc, **para que** nenhum comando novo seja publicado sem documentação.
|
|
27
|
+
- **Como** novo usuário, **quero** que o README documente o fluxo real de instalação e `forja setup`, **para que** eu consiga começar sem ler o código.
|
|
28
|
+
- **Como** agente de IA consumindo o README, **quero** números gerados do código (skills, comandos), **para que** o contexto injetado não contenha fato falso.
|
|
29
|
+
|
|
30
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
31
|
+
- [x] AC-1: `forja docs:gen` regenera `docs/commands.md` a partir do registry (idempotente) e `forja tools:doctor` sai 0 no estado corrigido do repo.
|
|
32
|
+
- [x] AC-2: O doctor detecta (a) comando `tier: 'core'` ausente de **qualquer um dos dois** READMEs (`core-in-readme`, critical), (b) comando documentado que não existe no registry (`docs-commands`, já existia), (c) flag documentada que o comando não declara em `usage`/`examples` (`docs-flags`, critical), (d) contagem de skills divergente de `templates/project/skills/` (`docs-skills-count`, warn), (e) `docs/commands.md` fora de sincronia com o registry (`commands-ref`, critical).
|
|
33
|
+
- [x] AC-3: README.md e README.pt-BR.md documentam instalação + `forja setup` + fluxo mínimo (workspace:init → project:new → spec:new → …).
|
|
34
|
+
- [x] AC-4: Drifts reais corrigidos — `forja setup` nos dois READMEs, `forja next`/orientação no pt-BR, `usage` declarado nas 15 entradas que não tinham, `demo:workspace --path`, `project:new --skip-backend` e `llm:run --context/--output-schema/--validation` declarados, `--verbose` (flag que nunca existiu) removido do quick-reference, e referência completa dos 105 comandos em `docs/commands.md` ligada na seção Documentação dos dois READMEs.
|
|
35
|
+
- [x] AC-5: Os checks rodam no CI (job `test`, passo "Doctor do núcleo", todas as células da matriz) **e** na bateria `check:all` pelo grupo de saúde do núcleo — `critical` que falha bloqueia (exit 1).
|
|
36
|
+
- [x] AC-6: `docs-flags` não produz falso positivo nas classes medidas no repo real: citação de comando sem prefixo `forja`/`npm run` (prosa), flag de binário de terceiro na mesma linha (`llm:run` → `claude -p`), clítico do português ("consultá-lo" ≠ `-lo`) e comando inexistente de superfície planejada (`docs/2x/*`).
|
|
37
|
+
|
|
38
|
+
## 5. Escopo
|
|
39
|
+
**Dentro**:
|
|
40
|
+
- `lib/core/doc-graph.ts`: `README.pt-BR.md` em `DOC_SURFACES`; `scanFlags`, `scanSkillCounts`, `flagTokens` (tokenizer único de flags).
|
|
41
|
+
- `lib/docs-reference.ts` (novo): o lado código da comparação — `declaredFlags`, `skillsCount`, `renderCommandsDoc`.
|
|
42
|
+
- `scripts/gen-commands-doc.ts` (novo) + entrada `docs:gen` no registry + script npm.
|
|
43
|
+
- 4 checks novos em `lib/core/health.ts` (`docs-flags`, `core-in-readme`, `docs-skills-count`, `commands-ref`), todos `scope: 'repo'`.
|
|
44
|
+
- `docs/commands.md` gerado do registry (referência completa, 105 comandos).
|
|
45
|
+
- `usage`/`examples` declarados nos comandos que não tinham (fonte única completa).
|
|
46
|
+
- Correção factual dos READMEs (setup, orientação, link da referência) e do `docs/quick-reference.md`.
|
|
47
|
+
- Testes em `test/health.test.js` (18 novos).
|
|
48
|
+
|
|
49
|
+
**Fora**:
|
|
50
|
+
- Gate paralelo próprio (`docs:check`, `lib/docs-check.ts`, `lib/core/docs-gate.ts`): construído na primeira passada e **removido** — dobrado no doctor.
|
|
51
|
+
- Reescrever prosa/marketing dos READMEs.
|
|
52
|
+
- Estilo do separador `--` (as duas formas funcionam; o check valida existência de flag).
|
|
53
|
+
- CHANGELOG (registro histórico — e nem está em `DOC_SURFACES`).
|
|
54
|
+
- `docs/2x/*`, `specs/`, `memory/` (superfície planejada e registro histórico).
|
|
55
|
+
- Documentação de projetos gerados (têm a sua).
|
|
56
|
+
|
|
57
|
+
## 6. NFRs / restrições
|
|
58
|
+
- Orçamento do hook SessionStart intacto: os 4 checks são `scope: 'repo'`, logo não rodam no `scope: 'runtime'` (5s, nenhuma tolerância a travar a sessão).
|
|
59
|
+
- Determinismo: `renderCommandsDoc` segue a ordem do registry (domínios por primeira aparição), sem depender de ordem de `readdir`; `skillsCount` recebe o diretório pronto, sem impor separador de caminho (portável entre SOs).
|
|
60
|
+
- Compatibilidade: não muda a saída de nenhum comando existente; `docs:gen` é aditivo.
|
|
61
|
+
|
|
62
|
+
## 7. Riscos e mitigação
|
|
63
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| Check estrito bloqueia PR legítimo (comando experimental) | M | M | Comando que o registry não conhece é ignorado por `docs-flags`; flag citada em nome de outro comando da mesma linha absolve |
|
|
66
|
+
| Falsos positivos em parsing de markdown | M | M | Dono de flag é só invocação prefixada; as 4 classes medidas viraram teste (AC-6) |
|
|
67
|
+
| Duplicar a máquina de ler doc | M | A | Sem scanner próprio: leitura em `doc-graph.ts`, juízo em `health.ts`, tokenizer de flags um só (`flagTokens`) |
|
|
68
|
+
| Correção dos READMEs conflitar com PRs em andamento | B | B | Branch dedicada, merge rápido na Wave 1 |
|
|
69
|
+
|
|
70
|
+
## 8. Métricas de sucesso
|
|
71
|
+
30 dias após o release: zero issues de "comando não documentado"; `tools:doctor` verde em todos os PRs; README pt-BR com paridade de comandos documentados ≥ 95% do EN.
|
|
72
|
+
|
|
73
|
+
## Evidências e estado real
|
|
74
|
+
Medições de 2026-11-05, branch `feat/v6-wave1`:
|
|
75
|
+
|
|
76
|
+
- **Primeira passada no repo real: 35 divergências** — 3 de comando core fora do README (`setup` nos dois, `next` no pt-BR) e 32 de flag. A contagem de skills não disparou: os "34 skills" dos READMEs conferem com as 34 pastas reais (o 35 que circulava na análise contava o `README.md` do diretório).
|
|
77
|
+
- Investigação das 32 flags: **todas existem nos scripts** (`--mine/--open` em agent-router.ts, `--role` em agent.ts, `--title` em incident.ts, `--code` em code-context.ts, `--task` em build-smart-context.ts, `--profile/--scope/--id` em llm-fit.ts, `--publish` em release-check.ts, `--full` em gates.ts, `--failed/--cmd/--since` em audit-query.ts). O drift estava no **registry sem `usage`**, não na prosa → 15 entradas ganharam `usage`/`examples` (`agent:route`, `agent:register`, `agent:recommend`, `agent:score`, `agent:monitor`, `incident:record`, `code:context`, `context:smart` (estendido), `llm:recommend`, `llm:run`, `llm:eval`, `drift:check`, `release:check`, `check:all`, `audit:query`).
|
|
78
|
+
- **Drift real achado na segunda passada** (com a regra já dobrada no doctor): `demo:workspace --path` (`scripts/demo-workspace.ts:27`) e `project:new --skip-backend` (`scripts/agent-harness.ts:468`) existiam e não estavam no registry — corrigidos; `llm:run --context/--output-schema/--validation` existem em `scripts/llm-fit.ts:126` e não no `usage` — corrigido; `npm run project:new -- --verbose` em `docs/quick-reference.md:57` documentava flag que **não existe** em lugar nenhum — linha removida.
|
|
79
|
+
- **Falsos positivos eliminados** (todos viraram teste): (1) citação sem prefixo — "`llm:probe` executa `--version`" e "`llm:run --profile claude` → `claude -p …`" atribuíam flags de terceiros ao Forja → dono de flag passou a exigir `forja`/`npm run`; (2) flag de outro comando citado na linha — "(project:new --template)" dentro da célula de `project:templates` → o check absolve quando qualquer comando citado na linha declara a flag; (3) clítico português — "consultá-lo" casava como `-lo` → traço simples só casa com uma letra; (4) comando inexistente (`capabilities:list` de `docs/2x/*`) → ignorado, quem julga citação é `docs-commands`.
|
|
80
|
+
- **Estado final: `forja tools:doctor` com os 4 checks OK** (`docs-flags`, `core-in-readme`, `docs-skills-count` = 34 skills, `commands-ref` = 105 comandos).
|
|
81
|
+
- `docs/commands.md` gerado: **105 comandos** em 9 domínios, 34 skills, `|` escapado nas células, cabeçalho "Gerado por `forja docs:gen` … não edite à mão".
|
|
82
|
+
- Testes: `test/health.test.js` **72/72 verdes** (18 novos: 6 de `docs-flags`, 2 de `core-in-readme`, 2 de `docs-skills-count`, 3 de `commands-ref`, 1 de não-aplicação fora do repo do framework, 3 de `lib/docs-reference.ts`). Suíte completa: **615/615 verdes** (`npm test`, ~18s). O fs de fixture (`repoStub`) passou a honrar `readdirSync(p, { withFileTypes: true })`, como o `node:fs` real.
|
|
83
|
+
- `npm run types:check` (tsc --noEmit): **0 erros**.
|
|
84
|
+
- Wiring: `package.json` (`docs:gen`), registry (`docs:gen`, domínio governanca, `next: ['tools:doctor']`); CI inalterado — o passo "Doctor do núcleo" já existente no job `test` (matriz 22.x/24.x) é o que bloqueia.
|
|
85
|
+
- Limitação registrada: os checks leem a doc do **framework**; projetos gerados têm a sua própria documentação e não são cobertos aqui.
|