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.
Files changed (268) hide show
  1. package/CHANGELOG.md +114 -2
  2. package/README.md +40 -5
  3. package/README.pt-BR.md +42 -4
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/apps/cli/src/index.d.ts +0 -1
  50. package/dist/apps/cli/src/index.js +43 -32
  51. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  52. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  53. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  54. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  55. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  56. package/dist/apps/server/src/forja-nest.module.js +55 -0
  57. package/dist/apps/server/src/main.d.ts +21 -4
  58. package/dist/apps/server/src/main.js +79 -57
  59. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  60. package/dist/apps/server/src/task-planning-service.js +195 -0
  61. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  62. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  63. package/dist/bin/forja.js +3 -2
  64. package/dist/bin/init-project.js +1 -0
  65. package/dist/lib/agent-evals.d.ts +138 -0
  66. package/dist/lib/agent-evals.js +349 -0
  67. package/dist/lib/cli-output.js +14 -2
  68. package/dist/lib/code-context.d.ts +33 -5
  69. package/dist/lib/code-context.js +70 -5
  70. package/dist/lib/context-builder.d.ts +49 -4
  71. package/dist/lib/context-builder.js +114 -47
  72. package/dist/lib/core/coverage-gate.d.ts +59 -0
  73. package/dist/lib/core/coverage-gate.js +58 -0
  74. package/dist/lib/core/doc-graph.d.ts +38 -0
  75. package/dist/lib/core/doc-graph.js +83 -0
  76. package/dist/lib/core/health.js +286 -5
  77. package/dist/lib/core/journey.js +36 -0
  78. package/dist/lib/core/registry.js +81 -6
  79. package/dist/lib/docs-reference.d.ts +35 -0
  80. package/dist/lib/docs-reference.js +57 -0
  81. package/dist/lib/generators/memory-generator.d.ts +0 -11
  82. package/dist/lib/generators/memory-generator.js +5 -161
  83. package/dist/lib/generators/readme-generator.js +1 -1
  84. package/dist/lib/llm/json-output.d.ts +14 -0
  85. package/dist/lib/llm/json-output.js +77 -0
  86. package/dist/lib/project-wiring.d.ts +8 -0
  87. package/dist/lib/project-wiring.js +79 -3
  88. package/dist/lib/session-memory.d.ts +38 -0
  89. package/dist/lib/session-memory.js +206 -0
  90. package/dist/lib/spec-trace.d.ts +46 -0
  91. package/dist/lib/spec-trace.js +184 -0
  92. package/dist/lib/validators/structure-validator.js +0 -1
  93. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  94. package/dist/packages/adapter-nest/src/index.js +59 -1
  95. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  96. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  97. package/dist/packages/context/src/index.d.ts +2 -0
  98. package/dist/packages/context/src/index.js +36 -15
  99. package/dist/packages/contracts/src/index.d.ts +64 -0
  100. package/dist/packages/core/src/index.d.ts +9 -1
  101. package/dist/packages/core/src/index.js +28 -3
  102. package/dist/packages/graph/src/index.js +14 -5
  103. package/dist/packages/llm/src/index.js +12 -2
  104. package/dist/packages/mcp/src/index.d.ts +8 -0
  105. package/dist/packages/mcp/src/index.js +12 -1
  106. package/dist/packages/observability/src/index.d.ts +11 -0
  107. package/dist/packages/observability/src/index.js +3 -0
  108. package/dist/packages/orchestration/src/index.d.ts +15 -1
  109. package/dist/packages/orchestration/src/index.js +127 -21
  110. package/dist/packages/planner/src/index.d.ts +7 -1
  111. package/dist/packages/planner/src/index.js +67 -10
  112. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  113. package/dist/packages/planner/src/proposal-store.js +109 -0
  114. package/dist/packages/policy/src/index.d.ts +9 -16
  115. package/dist/packages/policy/src/index.js +114 -31
  116. package/dist/packages/runtime/src/index.d.ts +16 -2
  117. package/dist/packages/runtime/src/index.js +176 -61
  118. package/dist/scripts/build-smart-context.d.ts +2 -0
  119. package/dist/scripts/build-smart-context.js +12 -3
  120. package/dist/scripts/code-context.d.ts +3 -1
  121. package/dist/scripts/code-context.js +13 -3
  122. package/dist/scripts/coverage-gate.d.ts +2 -0
  123. package/dist/scripts/coverage-gate.js +101 -0
  124. package/dist/scripts/eval-agents.d.ts +11 -0
  125. package/dist/scripts/eval-agents.js +96 -0
  126. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  127. package/dist/scripts/gen-commands-doc.js +18 -0
  128. package/dist/scripts/hook-session-memory.d.ts +9 -0
  129. package/dist/scripts/hook-session-memory.js +20 -0
  130. package/dist/scripts/hook-session-start.js +34 -0
  131. package/dist/scripts/llm-fit.js +23 -1
  132. package/dist/scripts/spec-trace.d.ts +10 -0
  133. package/dist/scripts/spec-trace.js +73 -0
  134. package/dist/scripts/sync-universal-memory.js +69 -4
  135. package/dist/scripts/token-benchmark.d.ts +33 -1
  136. package/dist/scripts/token-benchmark.js +179 -5
  137. package/dist/scripts/token-economy.js +3 -1
  138. package/dist/scripts/tools-doctor.d.ts +16 -1
  139. package/dist/scripts/tools-doctor.js +58 -17
  140. package/docs/commands.md +155 -0
  141. package/docs/fluxo.md +11 -7
  142. package/docs/init-project.md +3 -1
  143. package/docs/llm-fit-loop.md +36 -0
  144. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  145. package/docs/produto/factsheet-marketing.md +7 -5
  146. package/docs/produto/roteiro-demo.md +14 -5
  147. package/docs/quick-reference.md +3 -3
  148. package/docs/token-optimization.md +10 -6
  149. package/memory/90-decisions/0088-templates-validados.md +3 -0
  150. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  151. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  152. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  153. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  154. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  155. package/package.json +4 -2
  156. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  157. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  158. package/specs/memoria-de-sessao/spec.md +48 -0
  159. package/specs/skills-do-projeto/plan.md +40 -0
  160. package/specs/skills-do-projeto/spec.md +63 -0
  161. package/specs/skills-do-projeto/tasks.md +27 -0
  162. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  163. package/specs/v6-core-consolidation/spec.md +70 -0
  164. package/specs/v6-docs-drift/spec.md +85 -0
  165. package/specs/v6-quality-gates/spec.md +99 -0
  166. package/specs/v6-token-economy/spec.md +84 -0
  167. package/templates/evals/agents/adr.json +25 -0
  168. package/templates/evals/agents/memoria.json +32 -0
  169. package/templates/evals/agents/proxima-acao.json +29 -0
  170. package/templates/evals/agents/spec-nova.json +26 -0
  171. package/templates/evals/agents/teste-do-criterio.json +29 -0
  172. package/templates/project/AGENTS.md +16 -0
  173. package/templates/project/CLAUDE.md +3 -2
  174. package/templates/project/agents/context-engineer.md +3 -0
  175. package/templates/project/agents/governance.md +3 -0
  176. package/templates/project/agents/marketing.md +3 -0
  177. package/templates/project/agents/orchestrator.md +3 -0
  178. package/templates/project/agents/product.md +3 -0
  179. package/templates/project/agents/sdd-architect.md +3 -0
  180. package/templates/project/skills/README.md +14 -0
  181. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  182. package/templates/project/skills/api-design/SKILL.md +77 -0
  183. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  184. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  185. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  186. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  187. package/templates/project/skills/commit-message/SKILL.md +143 -0
  188. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  189. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  190. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  191. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  192. package/templates/project/skills/event-storming/SKILL.md +95 -0
  193. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  194. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  195. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  196. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  197. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  198. package/templates/project/skills/observability/SKILL.md +93 -0
  199. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  200. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  201. package/templates/project/skills/pull-request/SKILL.md +101 -0
  202. package/templates/project/skills/query-performance/SKILL.md +83 -0
  203. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  204. package/templates/project/skills/release-notes/SKILL.md +87 -0
  205. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  206. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  207. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  208. package/templates/project/skills/testing/SKILL.md +109 -0
  209. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  210. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  211. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  212. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  213. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  214. package/templates/project/skills/web-performance/SKILL.md +72 -0
  215. package/boilerplates/02-saas-starter/.env.example +0 -25
  216. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  217. package/boilerplates/02-saas-starter/INFO.md +0 -252
  218. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  219. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  220. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  221. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  222. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  223. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  224. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  225. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  226. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  227. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  228. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  229. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  230. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  231. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  232. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  233. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  234. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  235. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  236. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  237. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  238. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  239. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  240. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  241. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  242. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  243. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  244. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  245. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  246. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  247. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  248. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  249. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  250. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  251. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  252. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  253. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  254. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  255. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  256. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  257. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  258. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  259. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  260. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  261. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  262. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  263. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  264. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  265. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  266. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  267. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  268. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
package/CHANGELOG.md CHANGED
@@ -13,11 +13,123 @@ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — v
13
13
 
14
14
  ---
15
15
 
16
- ## [Unreleased]
16
+ ## [5.3.0] — 2026-11-14 — Supervisão, execução vinculada e qualidade verificável
17
17
 
18
18
  ### O que melhorou
19
19
 
20
- _(preencher a cada release: diff de produto vs. a versão anterior, antes das seções técnicas)_
20
+ - **Supervisão num painel de leitura.** Cinco abas reúnem próxima ação, rastreabilidade dos
21
+ critérios, custos observados, gates e operação. O painel usa as capacidades de leitura
22
+ declaradas pelo servidor, exige autenticação e não inventa custo quando não há uso medido.
23
+ - **Planejamento conectado ao contexto real.** A composição do servidor pode produzir propostas
24
+ revisáveis a partir de tarefas, handoffs e memória, com orçamento e proveniência. A revisão
25
+ fica persistida e verifica mudanças nas fontes; aprovar um plano não dispara execução nem
26
+ substitui a autorização das capacidades.
27
+ - **Tarefas acompanham a execução supervisionada.** Runtime, tarefa e handoff mantêm vínculos e
28
+ recuperação persistente. Conclusão exige validação independente; falha ou ausência de checks
29
+ não libera dependências. Uma sprint pausada impede novos pedidos de execução ou retomada,
30
+ sem impedir cancelamento nem reconciliação de resultados terminais.
31
+ - **Contexto mais enxuto e qualidade mensurável.** Trechos FTS5, sincronização incremental e
32
+ orçamento no contexto de código reduzem conteúdo desnecessário. A documentação de comandos
33
+ é derivada do registro; o diagnóstico detecta divergências e a cobertura tem piso versionado.
34
+ - **Quem vem da 5.1.0 também recebe as melhorias descritas na seção 5.2.0:** checkpoints de
35
+ sessão, critérios de aceite ligados a testes, avaliação de agentes e isolamento da auditoria
36
+ durante a suíte de testes.
37
+
38
+ ### Segurança e correções
39
+
40
+ - A autorização de capacidades usa categorias registradas pelo host, não a classificação
41
+ fornecida pelo cliente. A correção protege o caminho de execução supervisionada contra
42
+ autorização incorreta de operações de escrita.
43
+ - Aprovações ficam vinculadas à operação, entrada validada e escopo. Mudanças incompatíveis
44
+ com uma aprovação anterior exigem nova aprovação; evidências contraditórias não sustentam aceite.
45
+ - Falhas do CLI preservam o diagnóstico e não são convertidas em sucesso do runtime.
46
+ - Caminhos e leitura de documentos toleram diferenças de separadores e CRLF; a saída JSON
47
+ extensa não é truncada ao encerrar o processo.
48
+
49
+ ### Uso e limites conhecidos
50
+
51
+ - Integrações que registram capacidades podem declarar `CapabilityRegistration.categories`;
52
+ quando ausente, a classificação usa `definition.permissions`. `categories` enviado numa
53
+ requisição não altera a autorização. Preserve as categorias específicas no registro do host.
54
+ - O servidor padrão continua somente leitura. Planejamento com escrita, revisão e conclusão
55
+ validada exigem política, revisor confiável e validator configurados na composição do host.
56
+ - O dashboard é opcional e operado a partir do checkout; a instalação npm continua CLI-first.
57
+ - Pausar uma sprint não interrompe um handler já em andamento nem torna atômicas pausas
58
+ concorrentes com um pedido de execução.
59
+ - O inventário Windows de runtime de agentes, `simulate` e jornada `spec:trace` permanece
60
+ aberto em `specs/v6-quality-gates/spec.md`; esta versão não declara portabilidade completa.
61
+
62
+ ## [5.2.0] — 2026-10-22 — Memória de sessão, critérios ligados a testes e avaliação de agentes
63
+
64
+ ### O que melhorou
65
+
66
+ - **A IA não perde o fio quando o contexto é compactado.** Em projetos conectados ao Claude Code, cada
67
+ sessão que muda alguma coisa deixa um checkpoint em `memory/60-runs/sessions/` (arquivos editados,
68
+ specs tocadas, comandos `forja`, commits), atualizado ao fim de cada turno e antes de compactar.
69
+ Depois da compactação o checkpoint volta para a IA; numa sessão nova, ela vê onde a anterior parou.
70
+ Nenhum texto de prompt nem comando inteiro entra na memória. Projetos existentes ganham os hooks com
71
+ `forja project:upgrade --apply` (SPEC-052, ADR-0091).
72
+ - **Dá para saber quais critérios de aceite têm teste.** `forja spec:trace` lista, para cada `AC-N`
73
+ de cada spec, os testes que o citam (`SPEC-NNN AC-N` no nome ou num comentário), os critérios sem
74
+ teste e as citações a critérios que não existem mais. `--strict` vira gate: spec aprovada ou pronta
75
+ com lacuna sai com 2. O `AGENTS.md` e a skill `testing` do projeto ensinam a convenção (SPEC-053,
76
+ ADR-0092). Fixture com citações de exemplo fica entre `spec-trace:off` e `spec-trace:on`. No
77
+ próprio Forja, 48 de 340 critérios têm teste citando — o ponto de partida.
78
+ - **Dá para medir se os agentes seguem o Forja.** `forja eval:agents --agent claude|codex` roda uma
79
+ suíte de tarefas (registrar decisão, começar feature, testar um critério, responder pela memória,
80
+ achar a próxima ação) com o agente real num projeto descartável, corrige pelo que ficou no disco e
81
+ guarda o histórico em `.context/agent-evals.jsonl`, comparando com a execução anterior. Custa uma
82
+ sessão real por caso: há teto de custo por caso no Claude e timeout nos dois (SPEC-054, ADR-0093).
83
+
84
+ ### Corrigido
85
+
86
+ - **`npm test` não grava mais na sua trilha de auditoria.** Dois testes chamavam o CLI com o ambiente
87
+ do shell e deixavam entradas `spec:new` e `simulate --json` em `~/forja-workspace/.context/forja-runs.jsonl`
88
+ a cada execução da suíte. A suíte agora roda inteira com um workspace isolado
89
+ (`test/isolate-workspace.mjs`, pré-carregado pelo script `test`), e `test/test-isolation.test.js`
90
+ falha se o isolamento sair.
91
+
92
+ ## [5.1.0] — 2026-10-21 — Skills, template de SaaS e mais agentes
93
+
94
+ ### O que melhorou
95
+
96
+ - **O projeto passa a ter skills que as IAs realmente carregam.** São 34 skills em pt-BR (avaliar
97
+ produto, levantar e fatiar requisitos, event storming, modelagem de domínio, ADR, API, migrações,
98
+ arquitetura de front-end, acessibilidade, desempenho web, atualização de dependências, testes,
99
+ code review TypeScript, modelagem de ameaças, LGPD, observabilidade, release e git), instaladas em
100
+ `.claude/skills/` (Claude Code) e `.agents/skills/` (Codex). As 9 "skills" anteriores eram esboços
101
+ que nenhuma IA lia.
102
+ - **As skills falam a língua do Forja.** As que produzem artefatos dizem onde gravar: ADR em
103
+ `memory/90-decisions/`, requisitos em `specs/<slug>/spec.md`, entrega como handoff, postmortem com
104
+ `forja incident:record`. Cada sub-agent de papel lista as skills que deve usar.
105
+ - **Conferido como o resto da conexão:** `forja project:wire --check` valida as skills (frontmatter,
106
+ referências entre elas e comandos citados), e uma skill que você editar não é sobrescrita.
107
+ - **Novo template: `forja project:new minha-saas --template saas-starter`.** Uma API NestJS 12
108
+ multi-tenant que instala, compila e passa nos testes: cadastro que cria a organização, login e
109
+ refresh com papéis, planos com transições validadas e fatura mensal. O tenant vem sempre do token
110
+ (recurso de outro tenant responde 404), o preço vem da tabela de planos, nunca do cliente, e a API
111
+ não sobe sem os segredos configurados. O boilerplate antigo não compilava.
112
+ - **Mais agentes no `llm:run`: Gemini CLI, GitHub Copilot CLI, Cursor e opencode**, todos em modo
113
+ somente leitura (o Forja aplica as mudanças, não o provedor). Gemini e Cursor reportam uso de
114
+ tokens. O perfil `copilot` deixou de chamar o `gh copilot suggest`, que só sugeria comandos de
115
+ shell.
116
+
117
+ ### Adicionado
118
+
119
+ - `templates/project/skills/` (SPEC-051, ADR-0089); checks `skills-claude`/`skills-codex` no
120
+ `project:wire`; passo `skills` na jornada; `test/project-skills.test.js`.
121
+ - `boilerplates/02-saas-starter` como template validado (`"template": true`), na matriz
122
+ `project-smoke-full` do CI; ADR-0088 atualizado.
123
+ - Adapters `gemini-cli` (`--approval-mode plan -o json`), `copilot` (`copilot -s -p`), `cursor`
124
+ (`cursor-agent -p --mode plan --output-format json`) e `opencode` (`run --agent plan`), com
125
+ normalizadores em `lib/llm/json-output.ts`; `llm:doctor` exige as flags de somente leitura
126
+ (ADR-0090). `copilot`, `cursor` e `opencode` vêm desligados nos perfis padrão.
127
+
128
+ ### Removido
129
+
130
+ - Skills de esboço do gerador (`skills/` na raiz do projeto) e `scripts/lib/skill-loader.mjs`.
131
+ - Do `02-saas-starter`: o backend antigo (segredo JWT padrão, cobrança com valor do cliente,
132
+ `Math.random` simulando pagamento), Redis sem uso no `docker-compose.yml` e os guias desatualizados.
21
133
 
22
134
  ## [5.0.1] — 2026-10-10 — Correção: o upgrade nunca toca o código do projeto
23
135
 
package/README.md CHANGED
@@ -98,13 +98,14 @@ process followed?", the answer is a file, not a promise.
98
98
  - **Projects born connected to your AI** — `project:new` scaffolds a full project (memory, agents,
99
99
  a NestJS backend as the default boilerplate) and wires it to the AI you use: native instructions
100
100
  (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), Claude Code hooks that open every session with the
101
- project state and attach the spec you mention, six role sub-agents, and the Forja MCP server in
101
+ project state, attach the spec you mention and save a checkpoint of each session to memory
102
+ (returned to the AI after compaction), six role sub-agents, and the Forja MCP server in
102
103
  Claude, Codex, Gemini and Copilot (VS Code). The
103
104
  memory is indexed from the first minute. `project:wire --check` proves it; `project:upgrade --apply`
104
105
  re-wires older projects without touching the user's code — or the whole workspace with `--all`
105
106
  (ADR-0086). The NestJS backend follows the official NestJS 12 layout (ESM, Vitest, oxlint) and its
106
107
  `/api/ops` page shows the project's specs, open handoffs and indexed memory.
107
- - **Validated templates** — `project:new <name> --template clean-arch` starts from a boilerplate whose
108
+ - **Validated templates** — `project:new <name> --template clean-arch` (DDD) or `--template saas-starter` (multi-tenant SaaS with subscriptions and billing) starts from a boilerplate whose
108
109
  install, build, tests and lint are proven in CI; `project:templates` lists what is a template and
109
110
  what is reference architecture (ADR-0088).
110
111
  - **The user journey is a gate** — `npm test` and `release:check` run the whole journey (workspace →
@@ -112,8 +113,10 @@ process followed?", the answer is a file, not a promise.
112
113
  against the installed tarball, and fail if any command writes into the package itself.
113
114
  - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
114
115
  (agent-team design), **ai-engineering** (knowledge base).
115
- - **LLM Fit Loop** — adapters de CLI, perfis no workspace, probes sem custo, observações e
116
- recomendação determinística por papel/tarefa; credenciais nunca entram no Forja.
116
+ - **LLM Fit Loop** — CLI adapters (Codex, Claude; Gemini, Copilot CLI, Cursor and opencode in
117
+ read-only mode), workspace profiles, no-cost probes, observations and deterministic recommendation
118
+ per role/task; credentials never enter Forja. `eval:agents` measures whether real agents follow the
119
+ Forja method on a task suite in a throwaway project (ADR-0093).
117
120
  - **Engineering Control Plane** (v3.0, ADR-0078) — the Engineering Graph turns ADRs/SPECs into
118
121
  first-class, queryable nodes; the Architecture Constitution checks real code against decisions
119
122
  already recorded; the Change Risk Engine scores a change 0-100 with named, evidenced factors;
@@ -122,6 +125,31 @@ process followed?", the answer is a file, not a promise.
122
125
  recommended agents, similar past incidents — before you start. Every score is information for a
123
126
  human/policy rule to consult, never an autonomous decision on its own.
124
127
 
128
+ ## What's new in 5.3.0
129
+
130
+ - **Read-only supervision dashboard:** overview, acceptance-criteria traceability, observed costs,
131
+ gates and operations share the server's capability registry. The optional dashboard runs from
132
+ this checkout and requires an access token; see the [demo guide](docs/produto/roteiro-demo.md).
133
+ Installing the npm package remains a CLI-first workflow.
134
+ - **Context-backed planning and linked execution:** server composition connects tasks, handoffs,
135
+ memory and budgets to persisted, reviewable proposals. Plan review does not authorize execution;
136
+ completion requires independent checks. The default server remains read-only: writable planning,
137
+ trusted review and validation require explicit host configuration.
138
+ - **Authorization belongs to the host:** registered capability categories determine policy, not
139
+ request-supplied categories. Custom registrations can set `CapabilityRegistration.categories`;
140
+ otherwise classification uses `definition.permissions`. Preserve custom categories in the host
141
+ registration rather than passing them only with execution requests.
142
+ - **Paused sprints reject new execute/resume requests** for linked runs, while cancellation and
143
+ terminal reconciliation remain available. This does not interrupt an in-flight handler or make
144
+ concurrent sprint changes atomic with dispatch.
145
+ - **Smaller context and measurable quality:** FTS5 snippets, incremental memory indexing, generated
146
+ command documentation and a versioned coverage floor. Upgrading from 5.1.0 also includes session
147
+ checkpoints, acceptance-criteria tracing and agent evaluations documented in the changelog.
148
+
149
+ Windows still has open agent-runtime, worktree simulation and `spec:trace` journey limitations;
150
+ see the [quality-gates inventory](specs/v6-quality-gates/spec.md). Full Windows portability is not
151
+ claimed. Details and upgrade notes: [CHANGELOG](CHANGELOG.md).
152
+
125
153
  ## ⚡ Quick start
126
154
 
127
155
  ```bash
@@ -129,7 +157,10 @@ process followed?", the answer is a file, not a promise.
129
157
  npm install -g forjajs
130
158
  forja # help grouped by domain
131
159
 
132
- # Prepare the production workspace (the fixed home for your projects)
160
+ # First run: creates the workspace and indexes the memory, confirming each step
161
+ forja setup # add --yes to accept every default
162
+
163
+ # Or prepare the production workspace by hand (the fixed home for your projects)
133
164
  forja workspace:init
134
165
 
135
166
  # Create a new project (generated in ~/forja-workspace/projects/<name>, already wired to your AI)
@@ -143,6 +174,7 @@ forja spec:new my-feature
143
174
  forja spec:plan my-feature
144
175
  forja spec:tasks my-feature
145
176
  forja spec:check my-feature
177
+ forja spec:trace my-feature # AC-N criteria × tests that cite them (SPEC-NNN AC-N)
146
178
  ```
147
179
 
148
180
  ### Already have a repository?
@@ -389,6 +421,8 @@ my-project/
389
421
  .claude/
390
422
  settings.json # hooks: forja hook:session-start / hook:user-prompt
391
423
  agents/ # orchestrator, product, sdd-architect, context-engineer, governance, marketing
424
+ skills/ # 34 skills (requirements, domain modeling, ADR, front-end, a11y, testing, TS code review, LGPD…)
425
+ .agents/skills/ # the same skills for Codex
392
426
  .mcp.json # forja MCP server (+ codegraph when installed)
393
427
  .codex/config.toml # forja MCP for Codex · .gemini/settings.json (Gemini) · .vscode/mcp.json (Copilot)
394
428
  .forja/models.json # AI fallback chain (engine switch)
@@ -406,6 +440,7 @@ The docs are written in **Brazilian Portuguese** — that's part of the project'
406
440
  output, code, and ADRs are readable regardless of language.
407
441
 
408
442
  - [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
443
+ - [`docs/commands.md`](docs/commands.md) — full command reference, generated from the registry (never hand-edited)
409
444
  - [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
410
445
  - [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
411
446
  - [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
package/README.pt-BR.md CHANGED
@@ -85,12 +85,38 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
85
85
  - **Pipeline SDD + GSD** — `spec → plan → tasks → check`, decisões registradas como ADRs.
86
86
  - **Auto-verificação (invariantes que rodam)** — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e `check:all` roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
87
87
  - **Economia de token medida, não afirmada** — a memória (`context.md` como mapa) economiza ~60% vs explorar no frio, e `token:economy` **prova** isso nos seus domínios. `code:context` entrega o mapa pronto; `memory:audit` garante que ele não mente sobre o código.
88
- - **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto e anexam a spec citada no prompt, seis sub-agents por papel e o servidor MCP do Forja no Claude, Codex, Gemini e Copilot (VS Code). A memória já nasce indexada. `project:wire --check` prova a conexão; `project:upgrade --apply` religa projetos antigos sem tocar no código do usuário — ou o workspace inteiro com `--all` (ADR-0086). O backend NestJS segue o padrão oficial do NestJS 12 (ESM, Vitest, oxlint), e a página `/api/ops` mostra specs, handoffs em aberto e a memória indexada do projeto.
89
- - **Templates validados** — `project:new <nome> --template clean-arch` parte de um boilerplate cuja instalação, build, testes e lint são provados no CI; `project:templates` lista o que é template e o que é arquitetura de referência (ADR-0088).
88
+ - **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto, anexam a spec citada no prompt e gravam um checkpoint de cada sessão na memória (devolvido à IA depois da compactação), seis sub-agents por papel e o servidor MCP do Forja no Claude, Codex, Gemini e Copilot (VS Code). A memória já nasce indexada. `project:wire --check` prova a conexão; `project:upgrade --apply` religa projetos antigos sem tocar no código do usuário — ou o workspace inteiro com `--all` (ADR-0086). O backend NestJS segue o padrão oficial do NestJS 12 (ESM, Vitest, oxlint), e a página `/api/ops` mostra specs, handoffs em aberto e a memória indexada do projeto.
89
+ - **Templates validados** — `project:new <nome> --template clean-arch` (DDD) ou `--template saas-starter` (SaaS multi-tenant com assinatura e faturamento) parte de um boilerplate cuja instalação, build, testes e lint são provados no CI; `project:templates` lista o que é template e o que é arquitetura de referência (ADR-0088).
90
+ - **LLM Fit Loop** — `llm:run` executa tarefas supervisionadas por CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), com perfis no workspace, probes sem custo, observações e recomendação por papel/tarefa; credenciais nunca entram no Forja (ADR-0090). `eval:agents` mede se agentes reais seguem o método do Forja numa suíte de tarefas em projeto descartável (ADR-0093).
90
91
  - **A jornada do usuário é gate** — `npm test` e `release:check` percorrem a jornada inteira (workspace → projeto → memória, contexto, specs, hooks, MCP e handoffs dentro do projeto), contra o fonte e contra o pacote instalado, e reprovam se algum comando escrever dentro do pacote.
91
92
  - **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
92
93
  - **Engineering Control Plane** (v3.0, ADR-0078) — o Engineering Graph vira ADRs/SPECs em nós de primeira classe consultáveis; a Architecture Constitution checa o código real contra decisões já registradas; o Change Risk Engine pontua uma mudança 0-100 com fatores nomeados e evidenciados; `forja simulate` testa um ref num worktree isolado e nunca promove sozinho. Uma façade só, `forja engineer "<objetivo>"`, compõe tudo isso — contexto, ADRs relevantes, checagem de arquitetura, risco, agentes recomendados, incidentes parecidos — antes de você começar. Todo score é informação pra um humano/regra de política consultar, nunca uma decisão autônoma por si só.
93
94
 
95
+ ## Novidades da 5.3.0
96
+
97
+ - **Painel de supervisão somente leitura:** visão, rastreabilidade de critérios, custos observados,
98
+ gates e operação usam o registro de capacidades do servidor. O dashboard opcional roda pelo
99
+ checkout e exige token de acesso; veja o [roteiro de demonstração](docs/produto/roteiro-demo.md).
100
+ A instalação do pacote npm continua CLI-first.
101
+ - **Planejamento com contexto e execução vinculada:** a composição do servidor conecta tarefas,
102
+ handoffs, memória e orçamento a propostas persistidas e revisáveis. Revisar um plano não autoriza
103
+ execução; concluir exige checks independentes. O servidor padrão continua somente leitura:
104
+ planejamento com escrita, revisão confiável e validação exigem configuração explícita do host.
105
+ - **A autorização pertence ao host:** as categorias registradas da capacidade determinam a
106
+ política, não as categorias enviadas na requisição. Registros próprios podem declarar
107
+ `CapabilityRegistration.categories`; na ausência, a classificação usa `definition.permissions`.
108
+ Preserve categorias próprias no registro do host, em vez de enviá-las só nos pedidos de execução.
109
+ - **Sprint pausada recusa novos pedidos de execução e retomada** de runs vinculados, preservando
110
+ cancelamento e reconciliação terminal. Isso não interrompe um handler em andamento nem torna
111
+ atômicas as mudanças concorrentes na sprint e o disparo de execução.
112
+ - **Contexto menor e qualidade mensurável:** trechos FTS5, indexação incremental de memória,
113
+ documentação de comandos gerada e piso de cobertura versionado. Quem atualiza da 5.1.0 também
114
+ recebe checkpoints de sessão, rastreabilidade de critérios e avaliação de agentes descritos no changelog.
115
+
116
+ O Windows ainda tem limitações abertas no runtime de agentes, na simulação por worktree e na
117
+ jornada `spec:trace`; veja o [inventário de qualidade](specs/v6-quality-gates/spec.md). Não há
118
+ promessa de portabilidade completa. Detalhes e notas de atualização: [CHANGELOG](CHANGELOG.md).
119
+
94
120
  ## ⚡ Quick start
95
121
 
96
122
  ```bash
@@ -98,7 +124,10 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
98
124
  npm install -g forjajs
99
125
  forja # help agrupado por domínio
100
126
 
101
- # Preparar o workspace de produção (canto fixo dos projetos)
127
+ # Primeiro uso: cria o workspace e indexa a memória, confirmando cada passo
128
+ forja setup # com --yes aceita todos os padrões
129
+
130
+ # Ou preparar o workspace de produção à mão (canto fixo dos projetos)
102
131
  forja workspace:init
103
132
 
104
133
  # Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>, já conectado à sua IA)
@@ -112,6 +141,7 @@ forja spec:new minha-feature
112
141
  forja spec:plan minha-feature
113
142
  forja spec:tasks minha-feature
114
143
  forja spec:check minha-feature
144
+ forja spec:trace minha-feature # critérios AC-N × testes que os citam (SPEC-NNN AC-N)
115
145
  ```
116
146
 
117
147
  ### Já tem um repositório?
@@ -202,6 +232,11 @@ Os scripts npm do repo são aliases finos que roteiam pelo core.
202
232
  ## Comandos essenciais
203
233
 
204
234
  ```bash
235
+ # Orientação — o caminho feliz
236
+ forja status # onde estou: workspace, sprint, specs, runs, handoffs
237
+ forja next # o que agora: uma linha — a próxima ação + o comando exato
238
+ forja help [<comando>|--all] # os essenciais, ou uso/args/exemplos de um comando
239
+
205
240
  # Workspace & projetos
206
241
  forja workspace:init # cria ~/forja-workspace
207
242
  forja project:new <nome> --ai claude,copilot # cria projeto no workspace, conectado à IA
@@ -212,7 +247,7 @@ forja project:list # lista projetos do workspace
212
247
  forja workspace:project:check <nome> # valida padrões num projeto do workspace
213
248
 
214
249
  # Pipeline SDD
215
- forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
250
+ forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check · spec:trace
216
251
 
217
252
  # Sprint & handoffs (GSD)
218
253
  forja sprint:start # também: sprint:status · sprint:complete
@@ -307,6 +342,8 @@ meu-projeto/
307
342
  .claude/
308
343
  settings.json # hooks: forja hook:session-start / hook:user-prompt
309
344
  agents/ # orchestrator, product, sdd-architect, context-engineer, governance, marketing
345
+ skills/ # 34 skills (requisitos, modelagem de domínio, ADR, front-end, acessibilidade, testes, code review TS, LGPD…)
346
+ .agents/skills/ # as mesmas skills para o Codex
310
347
  .mcp.json # servidor MCP do forja (+ codegraph quando instalado)
311
348
  .codex/config.toml # MCP do forja no Codex · .gemini/settings.json (Gemini) · .vscode/mcp.json (Copilot)
312
349
  .forja/models.json # cadeia de fallback entre IAs (troca de motor)
@@ -321,6 +358,7 @@ A parte gerenciada pelo Forja em cada arquivo de instrução fica entre `<!-- fo
321
358
  ## Documentação
322
359
 
323
360
  - [`DOC-MAP.md`](DOC-MAP.md) — mapa por papel e por tópico (comece aqui)
361
+ - [`docs/commands.md`](docs/commands.md) — referência completa de comandos, gerada do registry (nunca editada à mão)
324
362
  - [`docs/processo-projeto.md`](docs/processo-projeto.md) — criar vs atualizar projeto
325
363
  - [`docs/fluxo.md`](docs/fluxo.md) — mapa do ciclo CLI-first
326
364
  - [`AGENTS.md`](AGENTS.md) — os 6 papéis e a topologia