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
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
|
@@ -152,6 +152,42 @@ forja llm:run --profile claude --resume SESSION_ID --prompt "Continue a análise
|
|
|
152
152
|
- **Custo**: o `total_cost_usd` do provedor **não** substitui a estimativa local de
|
|
153
153
|
`model-pricing.json` — a evidência de custo continua vindo do preço declarado no Forja.
|
|
154
154
|
|
|
155
|
+
## Outros agentes: Gemini, Copilot CLI, Cursor e opencode (ADR-0090)
|
|
156
|
+
|
|
157
|
+
Rodam sempre em modo somente leitura/planejamento: quem aplica mudanças é o fluxo do Forja.
|
|
158
|
+
|
|
159
|
+
| Perfil | Comando | Modo | Uso de tokens |
|
|
160
|
+
|---|---|---|---|
|
|
161
|
+
| `gemini-cli` | `gemini -p … --approval-mode plan -o json` | plano | sim (`stats.models`) |
|
|
162
|
+
| `copilot` | `copilot -s -p …` (GitHub Copilot CLI, sem `--allow-*`) | ferramentas com aprovação negadas | não |
|
|
163
|
+
| `cursor` | `cursor-agent -p … --mode plan --output-format json` | plano | sim |
|
|
164
|
+
| `opencode` | `opencode run --agent plan …` | agente `plan` | não |
|
|
165
|
+
|
|
166
|
+
`copilot`, `cursor` e `opencode` vêm desligados em `llm:profiles:init`; habilite no perfil do
|
|
167
|
+
workspace. `forja llm:doctor` confere se a CLI instalada oferece as flags de somente leitura; sem
|
|
168
|
+
elas, o perfil fica incompatível em vez de rodar com permissões que o Forja não pediu. Retomada
|
|
169
|
+
(`--resume`) continua só em Codex e Claude.
|
|
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
|
+
|
|
155
191
|
## Métricas e recomendação por custo/latência (SPEC-049)
|
|
156
192
|
|
|
157
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/`
|
|
@@ -51,5 +51,8 @@ compilação, então nada disso aparecia.
|
|
|
51
51
|
## Consequências
|
|
52
52
|
|
|
53
53
|
- `clean-arch` é o primeiro template. Promover outro exige migrá-lo e incluí-lo na matriz do CI.
|
|
54
|
+
- 5.1: `saas-starter` (02) promovido depois de reescrito do zero (o backend antigo não compilava e
|
|
55
|
+
tinha segredo JWT padrão e valor de cobrança vindo do cliente). Mesma regra de dependência do
|
|
56
|
+
`clean-arch`, contexts `identity` e `billing`, testes de isolamento entre tenants.
|
|
54
57
|
- Projetos gerados antes da v5 continuam em CommonJS + Jest. O `project:upgrade` é aditivo e não
|
|
55
58
|
migra o backend existente.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# ADR-0089: Skills do projeto carregáveis pelas IAs, vindas do skill ledger
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-10-21
|
|
5
|
+
- **Autor(es)**: Allan Pablo / Claude
|
|
6
|
+
- **Tags**: generation, llm, skills, sdd
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Todo projeto gerado recebia 9 "skills" de 5 a 10 linhas em `skills/` na raiz, sem frontmatter. O
|
|
11
|
+
Claude Code lê `.claude/skills/<nome>/SKILL.md`, o Codex lê `.agents/skills/`, e ambos exigem `name` e
|
|
12
|
+
`description` no frontmatter. Assim, nenhuma IA carregava essas skills, e os papéis do Forja não tinham
|
|
13
|
+
método escrito para seguir. Existia, fora do Forja, um catálogo pessoal de 29 skills completas (o
|
|
14
|
+
"skill ledger", convertido para TypeScript e traduzido para pt-BR) que cobre exatamente esses papéis.
|
|
15
|
+
|
|
16
|
+
## Decisão
|
|
17
|
+
|
|
18
|
+
1. **As 29 skills do ledger e a `llm-provider-routing` passam a ser as skills do projeto**, versionadas
|
|
19
|
+
em `templates/project/skills/` (cópia do ledger no commit `0097ed7`). O `name` fica em inglês, porque
|
|
20
|
+
é identificador, e o texto fica em pt-BR.
|
|
21
|
+
2. **Integração com o Forja em seção própria.** As skills que produzem artefatos ganham uma seção
|
|
22
|
+
"No Forja" (ADR em `memory/90-decisions/`, requisitos em `specs/<slug>/spec.md`, prompt-spec como
|
|
23
|
+
handoff ADR-0005, postmortem com `forja incident:record`, release com `### O que melhorou`). O resto
|
|
24
|
+
da skill continua portável, e atualizar a partir do ledger é reaplicar só essa seção.
|
|
25
|
+
3. **Instalação onde cada IA procura:** `.claude/skills/` (Claude) e `.agents/skills/` (Codex), pelo
|
|
26
|
+
`project:wire`, com a marca `forja:managed`. Uma skill editada pelo usuário (sem a marca) não é
|
|
27
|
+
sobrescrita. O `project:wire --check` valida frontmatter, referências entre skills e os comandos
|
|
28
|
+
`forja` que elas citam.
|
|
29
|
+
4. **Todas as skills são instaladas, inclusive as `ts-*`.** O que restringe o uso é a descrição, que a
|
|
30
|
+
IA consulta para decidir quando carregar a skill.
|
|
31
|
+
5. As 9 skills de esboço e o `scripts/lib/skill-loader.mjs` deixam de ser gerados.
|
|
32
|
+
|
|
33
|
+
## Alternativas consideradas
|
|
34
|
+
|
|
35
|
+
- **Instalar as `ts-*` só em projetos TypeScript.** Rejeitada: `testing`, `prompt-spec` e
|
|
36
|
+
`requirements-gathering` citam `ts-testing`/`ts-code-review` pelo nome, e omiti-las deixaria
|
|
37
|
+
referências quebradas.
|
|
38
|
+
- **Ler as skills do repositório do ledger em tempo de geração.** Rejeitada: o gerador passaria a depender
|
|
39
|
+
de um caminho externo e de rede; a cópia versionada é testada no CI e viaja no pacote.
|
|
40
|
+
- **Reescrever as skills do zero dentro do Forja.** Rejeitada: o ledger já é completo e revisado; a
|
|
41
|
+
seção "No Forja" é o que falta.
|
|
42
|
+
- **Instalar também em `.gemini/skills/`.** Adiada: a descoberta por pasta do Gemini CLI não foi
|
|
43
|
+
verificada nesta máquina. Hoje, o caminho é `gemini skills link <pasta>`.
|
|
44
|
+
|
|
45
|
+
## Consequências
|
|
46
|
+
|
|
47
|
+
- Projeto novo: de 0 para 30 skills carregáveis por IA conectada. Projetos existentes recebem as skills
|
|
48
|
+
com `forja project:upgrade --apply`.
|
|
49
|
+
- A cópia pode divergir do ledger. Atualizar é um PR que copia as skills e reaplica as seções "No Forja".
|
|
50
|
+
- Skill nova que cite um comando `forja` inexistente reprova no `project:wire --check` e no teste
|
|
51
|
+
`test/project-skills.test.js`.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# ADR-0090: Adapters de agente em modo somente leitura (Gemini, Copilot CLI, Cursor, opencode)
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-10-21
|
|
5
|
+
- **Autor(es)**: Allan Pablo / Claude
|
|
6
|
+
- **Tags**: llm, adapters, security
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O `llm:run` só tinha adapters completos para Codex e Claude (ADR-0081, ADR-0085). O adapter
|
|
11
|
+
`gemini-cli` chamava `gemini -p` em texto: sem uso de tokens e com as permissões padrão da CLI. O
|
|
12
|
+
`copilot` chamava `gh copilot suggest -t shell`, um sugeridor de comandos de shell, não um agente. Hoje
|
|
13
|
+
existem CLIs de agente com modo não interativo e somente leitura: Gemini CLI (`--approval-mode plan`,
|
|
14
|
+
`-o json`), GitHub Copilot CLI (`copilot -p`), Cursor Agent (`--print --mode plan --output-format json`)
|
|
15
|
+
e opencode (`run --agent plan`). Os formatos JSON do Gemini e do Cursor foram conferidos no código das
|
|
16
|
+
próprias CLIs instaladas (Gemini 0.64.0, Cursor Agent 2026.10.19).
|
|
17
|
+
|
|
18
|
+
## Decisão
|
|
19
|
+
|
|
20
|
+
1. **Todo adapter de agente roda em modo somente leitura/planejamento.** O `llm:run` é supervisionado
|
|
21
|
+
e quem aplica mudanças é o fluxo do Forja, não o provedor. Isso já valia para o Codex (`--sandbox
|
|
22
|
+
read-only`) e agora vale para Gemini (`--approval-mode plan`), Cursor (`--mode plan`), opencode
|
|
23
|
+
(`--agent plan`) e Copilot CLI (`-p` sem `--allow-*`, que nega as ferramentas que pedem aprovação).
|
|
24
|
+
2. **Saída normalizada** para Gemini (`response`, `session_id`, tokens somados de
|
|
25
|
+
`stats.models[*].tokens`) e Cursor (o mesmo envelope do Claude, com `usage` em camelCase ou
|
|
26
|
+
snake_case). Uso ausente fica indefinido, e o custo fica `null`; nunca se inventa zero.
|
|
27
|
+
3. **`llm:doctor` verifica a compatibilidade** de cada adapter conferindo que a CLI oferece as flags de
|
|
28
|
+
somente leitura que ele usa. Sem elas, o perfil é incompatível em vez de rodar com permissões que o
|
|
29
|
+
Forja não pediu.
|
|
30
|
+
4. Os perfis padrão ganham `copilot`, `cursor` e `opencode`, **desligados** até o usuário habilitar.
|
|
31
|
+
5. Retomada de sessão continua só em Codex e Claude: o `--resume` do Gemini aceita "latest" ou um índice,
|
|
32
|
+
não um ID explícito, e o Forja exige ID explícito (ADR-0081).
|
|
33
|
+
|
|
34
|
+
## Alternativas consideradas
|
|
35
|
+
|
|
36
|
+
- **Rodar os agentes com as permissões padrão de cada CLI.** Rejeitada: o comportamento mudaria de
|
|
37
|
+
provedor para provedor e algumas CLIs editam arquivos sem perguntar no modo não interativo.
|
|
38
|
+
- **Manter o `gh copilot suggest`.** Rejeitada: ele não responde a tarefas, só sugere comandos de shell.
|
|
39
|
+
- **Retomada no Gemini com `--resume latest`.** Rejeitada: "a última sessão" é ambígua com execuções
|
|
40
|
+
concorrentes e quebra a garantia de sessão explícita.
|
|
41
|
+
|
|
42
|
+
## Consequências
|
|
43
|
+
|
|
44
|
+
- `forja llm:run --profile gemini|copilot|cursor|opencode` funciona em modo de análise. Para editar
|
|
45
|
+
código, o caminho continua sendo o fluxo supervisionado (spec → tasks → handoff).
|
|
46
|
+
- O perfil `copilot` muda de semântica (de `gh copilot` para o Copilot CLI). Perfis antigos com
|
|
47
|
+
`command: "gh"` falham no `llm:doctor` e precisam de `command: "copilot"`.
|
|
@@ -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.
|