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
@@ -0,0 +1,155 @@
1
+ # Referência de comandos
2
+
3
+ > Gerado por `forja docs:gen` a partir de `lib/core/registry.ts` — **não edite à mão.**
4
+ > 106 comandos · 34 skills distribuídas aos projetos gerados.
5
+
6
+ ## workspace
7
+
8
+ | Comando | O que faz | Uso | Tier | Gates |
9
+ |---|---|---|---|---|
10
+ | `forja workspace:init` | Cria a estrutura base do workspace (~/forja-workspace) | `forja workspace:init` | core | — |
11
+ | `forja project:new` | Cria projeto no workspace e registra ficha em 30-projects/ | `forja project:new <nome> [-- --ai claude,copilot --skip-backend] [--template <nome>]` | core | workspace |
12
+ | `forja setup` | Rotina de primeiro uso: workspace:init + sync:universal, atrás de confirmação | `forja setup [--yes]` | core | — |
13
+ | `forja project:list` | Lista projetos do workspace | `forja project:list` | advanced | — |
14
+ | `forja project:upgrade` | Traz peças novas de scaffold e religa a IA num projeto (ou --all) — aditivo; --apply aplica | `forja project:upgrade [--apply] [--project <path> \| --all] [--json]` | advanced | — |
15
+ | `forja workspace:project:check` | Valida padrões em um projeto do workspace | `forja workspace:project:check` | advanced | workspace |
16
+ | `forja project:templates` | Lista os boilerplates: quais são templates validados (project:new --template) e quais são referência | `forja project:templates [--json]` | advanced | — |
17
+ | `forja project:wire` | Conecta o projeto à inteligência do Forja: instruções nativas, hooks, sub-agents e MCP | `forja project:wire [--check] [--ai claude,codex,gemini,copilot] [--json]` | advanced | — |
18
+
19
+ ## sdd
20
+
21
+ | Comando | O que faz | Uso | Tier | Gates |
22
+ |---|---|---|---|---|
23
+ | `forja spec:new` | Cria specs/<slug>/spec.md a partir do template | `forja spec:new <slug>` | core | — |
24
+ | `forja spec:plan` | Deriva plan.md de uma spec | `forja spec:plan <slug>` | core | — |
25
+ | `forja spec:tasks` | Decompõe plan.md em tasks.md | `forja spec:tasks <slug>` | core | — |
26
+ | `forja spec:trace` | Critérios de aceite × testes que os citam (SPEC-NNN AC-N): cobertos, sem teste e órfãos | `forja spec:trace [slug] [--strict] [--json]` | advanced | — |
27
+ | `forja spec:check` | Valida completude da spec (gate de governança) | `forja spec:check [slug] [--json]` | core | — |
28
+ | `forja spec:set-status` | Atualiza o status de um artefato SDD | `forja spec:set-status` | advanced | — |
29
+
30
+ ## gsd
31
+
32
+ | Comando | O que faz | Uso | Tier | Gates |
33
+ |---|---|---|---|---|
34
+ | `forja status` | Retrato único do estado: workspace, sprint, corrida, specs, runs, handoffs | `forja status [--json]` | core | workspace-warn |
35
+ | `forja next` | A próxima ação recomendada + o comando exato para executá-la | `forja next [--json]` | core | workspace-warn |
36
+ | `forja orchestrate` | Abre uma corrida: a cadeia SDD/GSD como máquina de estados guardada por gates | `forja orchestrate "<objetivo>" --slug <slug>` | core | — |
37
+ | `forja orchestrate:status` | O estado da corrida: etapas feitas, aberta, gates e vereditos | `forja orchestrate:status <slug>` | core | — |
38
+ | `forja orchestrate:advance` | Roda o gate da etapa aberta; verde → abre a próxima; vermelho → trava com o parecer | `forja orchestrate:advance <slug>` | core | — |
39
+ | `forja gsd:plan` | Cria runbook GSD em .context/ | `forja gsd:plan` | advanced | — |
40
+ | `forja gsd:handoff` | Registra handoff GSD padronizado (ADR-0005) | `forja gsd:handoff` | advanced | — |
41
+ | `forja gsd:check` | Valida gates básicos do runbook GSD | `forja gsd:check` | advanced | — |
42
+ | `forja hermes:handoff` | Registra handoff ADR-0005 bruto via agent-router | `forja hermes:handoff` | advanced | — |
43
+ | `forja agent:route` | Roteia/inspeciona handoffs (agent-router) | `forja agent:route <append\|list [--open] [--mine\|--project <nome>] [--to <papel>]\|show\|done\|in_progress\|cancel\|archive\|schema> [args]` | advanced | — |
44
+ | `forja sprint:start` | Inicia sprint | `forja sprint:start` | advanced | — |
45
+ | `forja sprint:status` | Status da sprint atual | `forja sprint:status` | advanced | — |
46
+ | `forja sprint:complete` | Encerra sprint | `forja sprint:complete` | advanced | — |
47
+
48
+ ## design
49
+
50
+ | Comando | O que faz | Uso | Tier | Gates |
51
+ |---|---|---|---|---|
52
+ | `forja design:check` | Valida brief visual antes do handoff | `forja design:check` | advanced | — |
53
+ | `forja design:select` | Sugere referências design-md por superfície | `forja design:select` | advanced | — |
54
+
55
+ ## code
56
+
57
+ | Comando | O que faz | Uso | Tier | Gates |
58
+ |---|---|---|---|---|
59
+ | `forja code:check` | Valida índice codegraph (worktree + freshness) | `forja code:check` | advanced | — |
60
+ | `forja code:impact` | Chamadores + blast radius de um símbolo | `forja code:impact` | advanced | — |
61
+ | `forja graph:sync` | Indexa arquivos rastreáveis do workspace no GraphLoop por checksum | `forja graph:sync` | advanced | workspace-warn |
62
+ | `forja drift:check` | Reindexa e sinaliza relações verified que a extração atual não reproduz mais (SPEC-030). --domain <d> restringe; --all roda por projeto do workspace | `forja drift:check [--domain <d>] [--all]` | advanced | workspace-warn |
63
+ | `forja adr:list` | Lista ADRs (memory/90-decisions/) com status, via Engineering Graph (SPEC-032) | `forja adr:list` | advanced | workspace-warn |
64
+ | `forja adr:show` | Mostra uma ADR: status, arquivo, constraints (SPEC-032) | `forja adr:show` | advanced | workspace-warn |
65
+ | `forja adr:impact` | Componentes/documentos alcançáveis a partir de uma ADR, via GraphLoop.impact (SPEC-032) | `forja adr:impact` | advanced | workspace-warn |
66
+ | `forja adr:graph` | Subgrafo (JSON) de nós ADR/SPEC + vizinhança (SPEC-032) | `forja adr:graph` | advanced | workspace-warn |
67
+ | `forja architecture:compile` | ADRs (## Constraints) → .context/architecture/constitution.json (SPEC-033) | `forja architecture:compile` | advanced | — |
68
+ | `forja architecture:check` | Verifica o código real contra a Architecture Constitution compilada (SPEC-033) | `forja architecture:check` | advanced | workspace-warn |
69
+ | `forja architecture:status` | Resumo da Constitution: regras active/proposed, última compilação (SPEC-033) | `forja architecture:status` | advanced | — |
70
+ | `forja architecture:explain` | Explica uma regra da Constitution: ADR de origem, severidade, texto original (SPEC-033) | `forja architecture:explain` | advanced | — |
71
+ | `forja architecture:approve` | Promove uma regra proposed a active via ApprovalLedger (SPEC-033) | `forja architecture:approve` | advanced | — |
72
+ | `forja risk:assess` | Score de risco 0-100 (7 fatores) sobre o diff de um ref (default: working tree) (SPEC-034) | `forja risk:assess` | advanced | workspace-warn |
73
+ | `forja risk:explain` | Reexibe um assessment de risco já calculado, com todos os fatores (SPEC-034) | `forja risk:explain` | advanced | — |
74
+ | `forja evidence:show` | View agregada de evidência de um run: intent, agente, testes, aprovações (SPEC-035) | `forja evidence:show` | advanced | workspace-warn |
75
+ | `forja engineer` | Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado | `forja engineer "<objetivo>" [--ref <ref>] [--role <role>] [--json]` | core | workspace-warn |
76
+ | `forja agent:register` | Registra/atualiza um agente (role/provider/model/capabilities/domains) (SPEC-036) | `forja agent:register <id> --role <role> [--provider <p>] [--model <m>] [--capabilities <c1,c2>] [--domains <d1,d2>] [--max-files <n>] [--max-cost-usd <n>]` | advanced | workspace-warn |
77
+ | `forja agent:list` | Lista agentes registrados, com trustLevel se já pontuados (SPEC-036) | `forja agent:list` | advanced | workspace-warn |
78
+ | `forja agent:show` | Detalhe de um agente registrado (SPEC-036) | `forja agent:show` | advanced | workspace-warn |
79
+ | `forja agent:score` | Computa e persiste trustLevel/autonomyLevel a partir de Observation reais (SPEC-036) | `forja agent:score <id> [--domain <d>]` | advanced | workspace-warn |
80
+ | `forja agent:history` | Observations de um agente, mais recentes primeiro (SPEC-036) | `forja agent:history` | advanced | workspace-warn |
81
+ | `forja agent:recommend` | Ranking de agentes registrados por adequação a um papel/domínio — informação, não atribuição (SPEC-037) | `forja agent:recommend --role <role> [--domain <d>]` | advanced | workspace-warn |
82
+ | `forja agent:monitor` | Compara comportamento recente de um agente contra a linha de base histórica — informação, não bloqueio (SPEC-040) | `forja agent:monitor <id> [--window-hours <n>]` | advanced | workspace-warn |
83
+ | `forja incident:record` | Grava um incidente no Engineering Graph (SPEC-041) | `forja incident:record --title <t> [--description <d>]` | advanced | workspace-warn |
84
+ | `forja incident:list` | Incidentes registrados, mais recentes primeiro (SPEC-041) | `forja incident:list` | advanced | workspace-warn |
85
+ | `forja incident:similar` | Sugere incidentes parecidos por palavra-chave — sugestão, nunca aplicação automática (SPEC-041) | `forja incident:similar` | advanced | workspace-warn |
86
+ | `forja simulate` | Testa+arquitetura+risco de um ref num worktree isolado, nunca promove | `forja simulate <ref> [--command "npm test"] [--json]` | advanced | workspace-warn |
87
+ | `forja provenance:record` | Extrai proveniência (arquivo↔agente) de um RuntimeRun já persistido (SPEC-039) | `forja provenance:record` | advanced | workspace-warn |
88
+ | `forja blame` | Histórico de proveniência de um arquivo — granularidade de arquivo, não linha (SPEC-039) | `forja blame` | advanced | workspace-warn |
89
+ | `forja sbom` | AI-SBOM: relatório de proveniência agregado por agente (SPEC-039) | `forja sbom` | advanced | workspace-warn |
90
+ | `forja code:context` | Pacote de contexto mínimo de um domínio: o mapa (context.md), + código com --code (ADR-0009) | `forja code:context <domínio> [termo] [--code] [--full] [--project <path>]` | advanced | — |
91
+ | `forja code:index` | Inicializa índice codegraph | `forja code:index` | advanced | — |
92
+ | `forja code:sync` | Sincroniza índice codegraph | `forja code:sync` | advanced | — |
93
+ | `forja code:status` | Status do índice codegraph | `forja code:status` | advanced | — |
94
+ | `forja code:query` | Consulta o índice codegraph | `forja code:query` | advanced | — |
95
+
96
+ ## memoria
97
+
98
+ | Comando | O que faz | Uso | Tier | Gates |
99
+ |---|---|---|---|---|
100
+ | `forja sync:universal` | Reindexa a memória universal (SQLite FTS5) | `forja sync:universal` | core | workspace-warn |
101
+ | `forja query:universal` | Busca FTS5 na memória universal | `forja query:universal "<termo>"` | core | workspace-warn |
102
+ | `forja memory:compress` | Arquiva runs antigos e compacta memória de projeto | `forja memory:compress` | advanced | — |
103
+ | `forja memory:vacuum` | Comprime e limpa memória (archive + VACUUM) | `forja memory:vacuum` | advanced | — |
104
+ | `forja memory:schema` | Garante schema do SQLite de memória | `forja memory:schema` | advanced | — |
105
+ | `forja memory:extract` | Extrai conhecimento global da memória | `forja memory:extract` | advanced | — |
106
+ | `forja memory:audit` | Coerência mapa↔código: mapa não cita código morto (falha) + módulo sem mapa (aviso). SPEC-017 | `forja memory:audit` | advanced | — |
107
+
108
+ ## contexto
109
+
110
+ | Comando | O que faz | Uso | Tier | Gates |
111
+ |---|---|---|---|---|
112
+ | `forja context:smart` | Gera smart-context (3 modos: global \| domain \| task) | `forja context:smart [--mode global\|domain\|task] [--domain <d>] [--task <termo>] [--keyword <k>] [--project <nome>] [--full-context]` | core | workspace-warn |
113
+ | `forja context:budget` | Orçamento de tokens do contexto | `forja context:budget` | advanced | — |
114
+ | `forja context:sprint` | Pacote de contexto da sprint | `forja context:sprint` | advanced | — |
115
+ | `forja agent:brief` | Brief de contexto para um agente | `forja agent:brief` | advanced | — |
116
+ | `forja catalog:assets` | Catálogo de assets do repo | `forja catalog:assets` | advanced | — |
117
+ | `forja catalog:manifests` | Catálogo de manifests | `forja catalog:manifests` | advanced | — |
118
+ | `forja token:benchmark` | Benchmark de consumo de tokens | `forja token:benchmark` | advanced | — |
119
+ | `forja token:economy` | Economia de token: eixos arquitetura + memória; --project mede seus domínios reais | `forja token:economy [--project <path>] [--json]` | advanced | — |
120
+ | `forja benchmark:context` | Benchmark JSON determinístico de baseline, contexto mínimo, checksum e cache | `forja benchmark:context` | advanced | — |
121
+
122
+ ## llm
123
+
124
+ | Comando | O que faz | Uso | Tier | Gates |
125
+ |---|---|---|---|---|
126
+ | `forja llm:profiles:init` | Cria perfis de adapters LLM no workspace | `forja llm:profiles:init` | advanced | workspace |
127
+ | `forja llm:doctor` | Verifica adapters LLM configurados sem usar credenciais | `forja llm:doctor` | advanced | workspace |
128
+ | `forja llm:probe` | Executa probe seguro de disponibilidade dos adapters LLM | `forja llm:probe` | advanced | workspace |
129
+ | `forja llm:recommend` | Recomenda perfil LLM por papel, tarefa e evidência local | `forja llm:recommend [--role <papel>] [--task <tarefa>] [--json]` | advanced | workspace |
130
+ | `forja llm:run` | Executa um perfil LLM e registra observação normalizada. --engineer "<objetivo>" monta o contexto pelo façade | `forja llm:run [--profile <perfil>] [--task <caminho>] [--prompt <texto>] [--engineer "<objetivo>"] [--context <caminho>...] [--output-schema <arquivo>] [--validation <arquivo>] [--resume <id>] [--json]` | advanced | workspace |
131
+ | `forja llm:sessions` | Lista/mostra sessões LLM registradas (o SESSION_ID de llm:run --resume) — somente leitura (SPEC-048) | `forja llm:sessions <list\|show> [id] [--json]` | advanced | workspace |
132
+ | `forja llm:eval` | Avalia execuções LLM com métricas determinísticas | `forja llm:eval [--scope <escopo>] [--id <id>] [--json]` | advanced | workspace |
133
+ | `forja eval:agents` | Avalia agentes reais (Claude, Codex) numa suíte de tarefas do Forja, em projeto descartável — custa | `forja eval:agents --agent claude\|codex [--case a,b] [--model m] [--budget-usd n] [--timeout s] [--keep] [--list] [--json]` | advanced | — |
134
+ | `forja cost:economy` | Custo real acumulado (USD) das execuções LLM registradas, por modelo — tabela de preço local | `forja cost:economy [--json]` | advanced | workspace |
135
+
136
+ ## governanca
137
+
138
+ | Comando | O que faz | Uso | Tier | Gates |
139
+ |---|---|---|---|---|
140
+ | `forja project:check` | Standards check do framework (pre-commit) | `forja project:check` | core | — |
141
+ | `forja tools:doctor` | Raio-x do núcleo (gate, exit 1) + ferramentas de processo | `forja tools:doctor [--json]` | core | — |
142
+ | `forja hook:session-start` | Hook SessionStart: briefing de specs, handoffs e saúde do núcleo para a IA | `forja hook:session-start` | advanced | — |
143
+ | `forja hook:user-prompt` | Hook UserPromptSubmit: injeta o contexto da spec citada no prompt | `forja hook:user-prompt` | advanced | — |
144
+ | `forja hook:session-memory` | Hook Stop/PreCompact: grava o checkpoint da sessão em memory/60-runs/sessions/ | `forja hook:session-memory` | advanced | — |
145
+ | `forja demo:autonomy` | Executa a prova offline de autonomia supervisionada com Git worktree real | `forja demo:autonomy` | advanced | — |
146
+ | `forja demo:workspace` | Cria um workspace isolado e rotulado para demonstração do produto | `forja demo:workspace [--path <diretório>] [--json]` | advanced | — |
147
+ | `forja release:check` | Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito | `forja release:check [--publish]` | advanced | — |
148
+ | `forja project:smoke` | Gate do projeto gerado: gera isolado e prova que é coerente. --full instala e builda o backend; --ai <lista> valida as instruções nativas | `forja project:smoke [--full] [--ai claude,copilot,gemini,codex] [--template <nome>]` | advanced | — |
149
+ | `forja check:all` | Roda a bateria inteira de gates e dá um veredito (SPEC-020). --full inclui tarball e build | `forja check:all [--full] [--with-architecture] [--with-drift]` | advanced | — |
150
+ | `forja project:dashboard` | Gera dashboard estático de status | `forja project:dashboard` | advanced | — |
151
+ | `forja audit:sync` | Projeta a trilha de auditoria (.jsonl) numa tabela consultável (SPEC-014) | `forja audit:sync` | advanced | — |
152
+ | `forja audit:query` | Consulta a auditoria: --failed, --cmd <x>, --since 7d | `forja audit:query [--failed] [--cmd <comando>] [--gate <gate>] [--since <janela>]` | advanced | — |
153
+ | `forja docs:gen` | Regenera docs/commands.md a partir do registry — a referência completa de comandos (SPEC-055) | `forja docs:gen` | advanced | — |
154
+ | `forja quality:coverage` | Roda a suíte com a cobertura nativa do Node e cobra o piso versionado (SPEC-056) — exit 2 abaixo do piso | `forja quality:coverage [--json]` | advanced | — |
155
+ | `forja governance:dashboard` | Gera um painel HTML estático de governança (gates, SDD, auditoria) — leitura, sem servidor | `forja governance:dashboard` | advanced | — |
package/docs/fluxo.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Fluxo do 2-projeto-agents — mapa operacional
2
2
 
3
3
  **Princípio:** CLI-first. Todo o ciclo roda por linha de comando. O dashboard web
4
- (`npm run dashboard`, porta 7777) é **visão opcional read-only** — nunca é gate de
5
- spec, handoff, sprint ou entrega.
4
+ (`npm run dashboard:api` + `npm run dashboard:dev`, app na porta 3001) é **visão opcional
5
+ read-only** — nunca é gate de spec, handoff, sprint ou entrega.
6
6
 
7
7
  As 3 capacidades externas (ADR-0016) entram em pontos específicos do ciclo, sem mudar
8
8
  o pipeline SDD+GSD existente:
@@ -35,7 +35,7 @@ flowchart LR
35
35
  end
36
36
 
37
37
  ENTREGA(["✅ Entrega"])
38
- VISAO["👁 dashboard 7777 (opcional)"]
38
+ VISAO["👁 dashboard 3001 (opcional)"]
39
39
 
40
40
  IDEIA --> E1
41
41
  E6 --> ENTREGA
@@ -54,7 +54,7 @@ flowchart LR
54
54
  codegraph product sdd-arch tasks worker governance
55
55
  ai-eng (ref) spec:new spec:plan+ADR spec:tasks codegraph MCP spec:check
56
56
  harness (time) handoffs project:check
57
- ──────────────► 👁 dashboard 7777 (opcional, read-only)
57
+ ──────────────► 👁 dashboard 3001 (opcional, read-only)
58
58
  ```
59
59
 
60
60
  ---
@@ -95,9 +95,13 @@ então *opera* esses agentes pelos handoffs existentes — harness desenha, GSD
95
95
 
96
96
  ## Front (opcional)
97
97
 
98
- O dashboard sobe com `npm run dashboard` em `http://127.0.0.1:7777` e oferece uma visão
99
- read-only de specs, handoffs e agentes (`/api/health`, `/api/specs`, `/api/handoffs`,
100
- `/api/agents`). É conveniência de leitura — se não subir, **o fluxo segue 100% pela CLI**.
98
+ O dashboard sobe em dois terminais — `npm run dashboard:api` (API em `127.0.0.1:3000`) e
99
+ `npm run dashboard:dev` (app em `http://localhost:3001`) — e oferece cinco abas read-only:
100
+ Visão, Rastreio, Custo, Gates e Operação. A leitura passa por `POST /api/capabilities/:id/execute`
101
+ (só capacidades que o servidor declara sem escrita nem efeito colateral), `GET /api/graph/query`,
102
+ `GET /api/control-plane/metrics`, `GET /api/observability/observations` e `GET /api/approvals`.
103
+ É conveniência de leitura — se não subir, **o fluxo segue 100% pela CLI**. Tokens e roteiro:
104
+ `docs/produto/roteiro-demo.md`.
101
105
 
102
106
  Ver também: `docs/cli-first-operacao.md` (comandos), `docs/capacidades-externas.md`
103
107
  (detalhe das 3 capacidades), `AGENTS.md` (papéis), ADR-0016.
@@ -39,7 +39,9 @@ O workspace é resolvido por: `FORJA_WORKSPACE` → `workspaceRoot` em `~/.forja
39
39
  - `AGENTS.md` com o bloco do Forja (lido por Codex, Copilot agent e Gemini).
40
40
  - `CLAUDE.md` e `GEMINI.md` importando o `AGENTS.md`; `.github/copilot-instructions.md`.
41
41
  - `.claude/settings.json`: hooks `forja hook:session-start` (briefing da sessão) e
42
- `forja hook:user-prompt` (anexa a spec citada), mais a permissão `Bash(forja *)`.
42
+ `forja hook:user-prompt` (anexa a spec citada), `forja hook:session-memory` nos eventos `Stop` e
43
+ `PreCompact` (checkpoint da sessão em `memory/60-runs/sessions/`, ADR-0091), mais a permissão
44
+ `Bash(forja *)`.
43
45
  - `.claude/agents/`: orchestrator, product, sdd-architect, context-engineer, governance, marketing.
44
46
  - `.mcp.json`: servidor `forja mcp:start` (e `codegraph`, se instalado); o mesmo servidor em
45
47
  `.codex/config.toml` (Codex), `.gemini/settings.json` (Gemini) e `.vscode/mcp.json` (Copilot).
@@ -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 parcial via API; não é requisito do fluxo CLI-first.
137
- - **Dashboard React/Vite legado:** útil para demonstração local de telas e navegação. Em 2026-08-17,
138
- ele inicia em Node 24 com `better-sqlite3` 12 e expõe API local em `127.0.0.1:7777`; o frontend
139
- Vite fica em `http://127.0.0.1:5173`. Um workspace sem projetos ou handoffs mostra coleções vazias,
140
- não dados de demonstração inventados.
136
+ - **Dashboard 2.x (`apps/dashboard`):** superfície de supervisão via API; não é requisito do fluxo
137
+ CLI-first. O dashboard React/Vite legado foi removido (ADR-0087). Em 2026-11-08 o app Next sobe com
138
+ `npm run dashboard:api` (API em `127.0.0.1:3000`) e `npm run dashboard:dev` (app em
139
+ `http://localhost:3001`), com cinco abas: Visão, Rastreio, Custo, Gates e Operação. Um workspace sem
140
+ projetos ou handoffs mostra coleções vazias, não dados de demonstração inventados.
141
+ - O painel só executa capacidades que o servidor declara como leitura sem efeito colateral, e o proxy
142
+ falha fechado: sem `FORJA_DASHBOARD_TOKEN` nenhuma requisição é encaminhada.
141
143
  - O dashboard não executa LLMs diretamente: essa ação foi direcionada para `forja llm:run` para manter
142
144
  policy, auditoria e privacidade.
143
145
 
@@ -17,11 +17,18 @@ app com o mesmo workspace (dois terminais):
17
17
 
18
18
  ```bash
19
19
  npm --prefix apps/dashboard install
20
- FORJA_WORKSPACE=~/forja-demo-workspace npm run dashboard:api # API local em 127.0.0.1:3000
21
- npm run dashboard:dev # app em http://localhost:3001
20
+ FORJA_WORKSPACE=~/forja-demo-workspace FORJA_AUTH_TOKEN=local-demo npm run dashboard:api # API em 127.0.0.1:3000
21
+ FORJA_API_URL=http://127.0.0.1:3000 FORJA_API_TOKEN=local-demo FORJA_DASHBOARD_TOKEN=demo-local npm run dashboard:dev # app em http://localhost:3001
22
22
  ```
23
23
 
24
- No Windows PowerShell, defina `$env:FORJA_WORKSPACE = "$HOME\forja-demo-workspace"` antes de `npm run dashboard:api`.
24
+ No Windows PowerShell, defina `$env:FORJA_WORKSPACE = "$HOME\forja-demo-workspace"` e
25
+ `$env:FORJA_AUTH_TOKEN = "local-demo"` antes de `npm run dashboard:api`; no segundo terminal,
26
+ `$env:FORJA_API_URL`, `$env:FORJA_API_TOKEN = "local-demo"` e `$env:FORJA_DASHBOARD_TOKEN = "demo-local"`.
27
+
28
+ Ao abrir `http://localhost:3001` o painel pede o `FORJA_DASHBOARD_TOKEN` (`demo-local` acima) e guarda
29
+ um cookie de sessão. Os dois tokens são locais e descartáveis: `FORJA_API_TOKEN` é a credencial do
30
+ proxy para a API, `FORJA_DASHBOARD_TOKEN` é a de quem acessa o painel. Sem o segundo, o proxy recusa
31
+ toda requisição — não existe modo aberto.
25
32
 
26
33
  O dashboard mostra o estado vazio apenas se a API não estiver recebendo a variável `FORJA_WORKSPACE`
27
34
  do cenário.
@@ -32,8 +39,10 @@ do cenário.
32
39
  estado do projeto, spec aprovada, plano, tarefas e a próxima ação com o comando exato.
33
40
  2. `forja project:wire --check`: a IA, os hooks e o MCP estão conectados ao projeto.
34
41
  3. `forja context:smart --mode task --task pix`: o pack mínimo da tarefa, com a contagem de tokens.
35
- 4. No dashboard (**Control Plane**): **GraphLoop** mostra specs, ADRs e evidências ligadas;
36
- **Approvals** e **Atividade recente** mostram as decisões e execuções auditadas.
42
+ 4. No dashboard (**Forja Control Plane**), cinco abas: **Visão** (próxima ação com o comando copiável,
43
+ sprint, specs e execuções recentes), **Rastreio** (cobertura de critérios de aceite por spec),
44
+ **Custo** (USD acumulado por modelo), **Gates** (veredito do núcleo e ferramentas) e **Operação**
45
+ (**Aprovações**, **GraphLoop** com impacto por nó e **Atividade recente** auditada).
37
46
  5. Mostre `forja demo:autonomy` separadamente para a prova de sandbox Git, aprovação e promoção real.
38
47
 
39
48
  ## Regras de uso
@@ -54,7 +54,6 @@ npm run project:new meu-projeto
54
54
  # Com flags
55
55
  npm run project:new meu-projeto -- --ai claude,copilot
56
56
  npm run project:new meu-projeto -- --skip-backend
57
- npm run project:new meu-projeto -- --verbose
58
57
 
59
58
  # Dentro do projeto: conferir a conexão com a IA
60
59
  forja project:wire --check
@@ -91,8 +90,9 @@ npm run start:prod
91
90
  # Health check
92
91
  curl http://localhost:3000/api/health
93
92
 
94
- # Dashboard legado/opcional
95
- npm run dashboard
93
+ # Dashboard opcional (dois terminais; ver docs/produto/roteiro-demo.md para os tokens)
94
+ npm run dashboard:api # API em 127.0.0.1:3000
95
+ npm run dashboard:dev # app em http://localhost:3001
96
96
  ```
97
97
 
98
98
  ---
@@ -59,7 +59,7 @@ Caps em `.memoryrc.json::hooks.userPromptCap` (default 4KB). Cache em `/tmp/fram
59
59
  **Cost**: $0.0001 per request
60
60
 
61
61
  ```bash
62
- node lib/context-builder.js global my-project
62
+ forja context:smart --mode global --project my-project
63
63
  ```
64
64
 
65
65
  ---
@@ -79,7 +79,7 @@ node lib/context-builder.js global my-project
79
79
  **Cost**: $0.005 per request
80
80
 
81
81
  ```bash
82
- node lib/context-builder.js domain my-project
82
+ forja context:smart --mode domain --project my-project
83
83
  ```
84
84
 
85
85
  ---
@@ -97,9 +97,12 @@ node lib/context-builder.js domain my-project
97
97
  **Cost**: $0.008 per request
98
98
 
99
99
  ```bash
100
- node lib/context-builder.js task my-project "auth backend"
100
+ forja context:smart --mode task --task "auth backend" --project my-project
101
101
  ```
102
102
 
103
+ Nó longo entra como **trecho casado** (especificado pelo `snippet()` do FTS5), não por inteiro; o rodapé do
104
+ pacote diz quantos nós vieram cortados, e `--full-context` traz a fatia inteira quando o corte atrapalha.
105
+
103
106
  ---
104
107
 
105
108
  ## 🧠 Smart Context - How It Works
@@ -360,11 +363,12 @@ nodes = nodes.slice(0, maxFiles); // Keep top N
360
363
  ### For Backend Worker
361
364
 
362
365
  ```javascript
363
- import ContextBuilder from '../lib/context-builder.js';
366
+ import ContextBuilder from '../lib/context-builder.ts';
364
367
 
365
368
  // On task start
366
369
  const builder = new ContextBuilder(process.cwd(), dbPath);
367
- const context = builder.build('task', 'my-project', 'backend auth');
370
+ const context = builder.build('task', 'my-project', 'backend auth'); // nós longos em trecho
371
+ const integral = builder.build('task', 'my-project', 'backend auth', { full: true });
368
372
  const stats = builder.stats('task', 'my-project', 'backend auth');
369
373
 
370
374
  console.log(`📊 Using ${stats.tokens} tokens (cost: $${stats.estimatedCost})`);
@@ -394,7 +398,7 @@ const context = builder.build('global', 'my-project');
394
398
  ## 📋 Pre-Flight Checklist
395
399
 
396
400
  - [ ] `.memoryrc.json` created with token limits
397
- - [ ] `lib/context-builder.js` integrated
401
+ - [ ] `lib/context-builder.ts` integrated
398
402
  - [ ] `scripts/compress-memory.mjs` tested
399
403
  - [ ] Cache directory created: `.context/cache/`
400
404
  - [ ] Archive directory created: `.memory/archive/`
@@ -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.