forjajs 2.0.4 → 3.0.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 (798) hide show
  1. package/.claude/agents/context-engineer.md +25 -25
  2. package/.claude/agents/governance.md +55 -55
  3. package/.claude/agents/marketing.md +24 -24
  4. package/.claude/agents/orchestrator.md +31 -31
  5. package/.claude/agents/product.md +26 -26
  6. package/.claude/agents/release-auditor.md +50 -50
  7. package/.claude/agents/sdd-architect.md +34 -34
  8. package/.claude/settings.json +76 -76
  9. package/.claude/skills/new-adr/SKILL.md +61 -61
  10. package/.claude/skills/new-command/SKILL.md +67 -67
  11. package/.gemini-instructions.md +87 -87
  12. package/.github/copilot-instructions.md +87 -87
  13. package/.memoryrc.json +104 -104
  14. package/.openai-instructions.md +87 -87
  15. package/AGENTS.md +133 -133
  16. package/CHANGELOG.md +619 -555
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +64 -60
  19. package/LICENSE +21 -21
  20. package/README.md +404 -343
  21. package/README.pt-BR.md +374 -345
  22. package/boilerplates/01-api-rest/README.md +336 -336
  23. package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
  24. package/boilerplates/02-saas-starter/.env.example +25 -25
  25. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
  26. package/boilerplates/02-saas-starter/INFO.md +252 -252
  27. package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
  28. package/boilerplates/02-saas-starter/README.md +305 -305
  29. package/boilerplates/02-saas-starter/START-HERE.md +259 -259
  30. package/boilerplates/02-saas-starter/backend/package.json +87 -87
  31. package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
  32. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
  33. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
  34. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
  35. package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
  36. package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
  37. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
  38. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
  39. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
  40. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
  41. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
  42. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
  43. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
  44. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
  45. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
  46. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
  47. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
  48. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
  49. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
  50. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
  51. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
  52. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
  53. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
  54. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
  55. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
  56. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
  57. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
  58. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
  59. package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
  60. package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
  61. package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
  62. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
  63. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
  64. package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
  65. package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
  66. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
  67. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
  68. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
  69. package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
  70. package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
  71. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
  72. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
  73. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
  74. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
  75. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
  76. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
  77. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
  78. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
  79. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
  80. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
  81. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
  82. package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
  83. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
  84. package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
  85. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
  86. package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
  87. package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
  88. package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
  89. package/boilerplates/03-ecommerce-starter/README.md +465 -465
  90. package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
  91. package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
  92. package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
  93. package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
  94. package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
  95. package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
  96. package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
  97. package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
  98. package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
  99. package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
  100. package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
  101. package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
  102. package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
  103. package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
  104. package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
  105. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
  106. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
  107. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
  108. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
  109. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
  110. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
  111. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
  112. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
  113. package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
  114. package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
  115. package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
  116. package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
  117. package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
  118. package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
  119. package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
  120. package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
  121. package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
  122. package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
  123. package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
  124. package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
  125. package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
  126. package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
  127. package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
  128. package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
  129. package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
  130. package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
  131. package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
  132. package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
  133. package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
  134. package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
  135. package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
  136. package/boilerplates/04-microservices-starter/.env.example +43 -43
  137. package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
  138. package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
  139. package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
  140. package/boilerplates/04-microservices-starter/INDEX.md +377 -377
  141. package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
  142. package/boilerplates/04-microservices-starter/README.md +466 -466
  143. package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
  144. package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
  145. package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
  146. package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
  147. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
  148. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
  149. package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
  150. package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
  151. package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
  152. package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
  153. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
  154. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
  155. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
  156. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
  157. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
  158. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
  159. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
  160. package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
  161. package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
  162. package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
  163. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
  164. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
  165. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
  166. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
  167. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
  168. package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
  169. package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
  170. package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
  171. package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
  172. package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
  173. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
  174. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
  175. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
  176. package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
  177. package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
  178. package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
  179. package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
  180. package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
  181. package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
  182. package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
  183. package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
  184. package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
  185. package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
  186. package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
  187. package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
  188. package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
  189. package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
  190. package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
  191. package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
  192. package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
  193. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
  194. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
  195. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
  196. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
  197. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
  198. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
  199. package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
  200. package/boilerplates/04-microservices-starter/package.json +21 -21
  201. package/boilerplates/05-monorepo-starter/.env.example +1 -1
  202. package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
  203. package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
  204. package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
  205. package/boilerplates/05-monorepo-starter/README.md +318 -318
  206. package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
  207. package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
  208. package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
  209. package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
  210. package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
  211. package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
  212. package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
  213. package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
  214. package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
  215. package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
  216. package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
  217. package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
  218. package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
  219. package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
  220. package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
  221. package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
  222. package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
  223. package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
  224. package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
  225. package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
  226. package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
  227. package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
  228. package/boilerplates/05-monorepo-starter/package.json +30 -30
  229. package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
  230. package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
  231. package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
  232. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
  233. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
  234. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
  235. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
  236. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
  237. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
  238. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
  239. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
  240. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
  241. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
  242. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
  243. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
  244. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
  245. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
  246. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
  247. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
  248. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
  249. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
  250. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
  251. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
  252. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
  253. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
  254. package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
  255. package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
  256. package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
  257. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
  258. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
  259. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
  260. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
  261. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
  262. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
  263. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
  264. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
  265. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
  266. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
  267. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
  268. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
  269. package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
  270. package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
  271. package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
  272. package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
  273. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
  274. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
  275. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
  276. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
  277. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
  278. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
  279. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
  280. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
  281. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
  282. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
  283. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
  284. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
  285. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
  286. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
  287. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
  288. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
  289. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
  290. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
  291. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
  292. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
  293. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
  294. package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
  295. package/boilerplates/05-monorepo-starter/turbo.json +35 -35
  296. package/boilerplates/06-clean-arch/README.md +48 -48
  297. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
  298. package/boilerplates/06-clean-arch/backend/package.json +43 -43
  299. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
  300. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
  301. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
  302. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
  303. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
  304. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
  305. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
  306. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
  307. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
  308. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
  309. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
  310. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
  311. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
  312. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
  313. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
  314. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
  315. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
  316. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
  317. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
  318. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
  319. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
  320. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
  321. package/boilerplates/README.md +427 -427
  322. package/design-md/BRIEF-TEMPLATE.md +47 -47
  323. package/design-md/INDEX.md +35 -35
  324. package/design-md/MATRIX.md +24 -24
  325. package/design-md/PLAYBOOK.md +35 -35
  326. package/design-md/examples/agent-console-brief.md +48 -48
  327. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  328. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  329. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  330. package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
  331. package/dist/apps/server/src/forja-nest.module.js +9 -4
  332. package/dist/apps/server/src/main.js +10 -1
  333. package/dist/bin/create-memory-nest-kit.js +17 -17
  334. package/dist/bin/init-project.js +38 -38
  335. package/dist/lib/audit.js +7 -7
  336. package/dist/lib/code-context.js +6 -0
  337. package/dist/lib/context-builder.js +32 -32
  338. package/dist/lib/core/architecture-gate.d.ts +20 -0
  339. package/dist/lib/core/architecture-gate.js +60 -0
  340. package/dist/lib/core/drift-gate.d.ts +18 -0
  341. package/dist/lib/core/drift-gate.js +55 -0
  342. package/dist/lib/core/gates.d.ts +9 -2
  343. package/dist/lib/core/gates.js +13 -2
  344. package/dist/lib/core/health.js +15 -0
  345. package/dist/lib/core/incident-search.d.ts +19 -0
  346. package/dist/lib/core/incident-search.js +32 -0
  347. package/dist/lib/core/model-pricing.d.ts +31 -0
  348. package/dist/lib/core/model-pricing.js +74 -0
  349. package/dist/lib/core/registry.d.ts +194 -0
  350. package/dist/lib/core/registry.js +194 -0
  351. package/dist/lib/core/release.d.ts +194 -0
  352. package/dist/lib/core/risk-collect.d.ts +19 -0
  353. package/dist/lib/core/risk-collect.js +173 -0
  354. package/dist/lib/drift-sentinel.d.ts +59 -0
  355. package/dist/lib/drift-sentinel.js +126 -0
  356. package/dist/lib/generators/memory-generator.js +691 -691
  357. package/dist/lib/generators/nest-generator.js +412 -398
  358. package/dist/lib/generators/readme-generator.js +180 -180
  359. package/dist/lib/governance-report.js +39 -39
  360. package/dist/lib/workspace.js +29 -29
  361. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  362. package/dist/packages/adapter-git/src/index.js +11 -6
  363. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  364. package/dist/packages/adapter-nest/src/index.js +26 -1
  365. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  366. package/dist/packages/adapter-sqlite/src/index.js +61 -12
  367. package/dist/packages/contracts/src/index.d.ts +33 -0
  368. package/dist/packages/contracts/src/index.js +13 -0
  369. package/dist/packages/core/src/index.d.ts +12 -0
  370. package/dist/packages/core/src/index.js +29 -0
  371. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  372. package/dist/packages/engineering/architecture/src/index.js +131 -0
  373. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  374. package/dist/packages/engineering/evidence/src/index.js +31 -0
  375. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  376. package/dist/packages/engineering/identity/src/index.js +88 -0
  377. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  378. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  379. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  380. package/dist/packages/engineering/provenance/src/index.js +21 -0
  381. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  382. package/dist/packages/engineering/risk/src/index.js +120 -0
  383. package/dist/packages/graph/src/index.d.ts +23 -1
  384. package/dist/packages/graph/src/index.js +88 -15
  385. package/dist/packages/llm/src/index.js +27 -4
  386. package/dist/packages/mcp/src/index.js +27 -8
  387. package/dist/packages/orchestration/src/index.d.ts +11 -1
  388. package/dist/packages/orchestration/src/index.js +34 -7
  389. package/dist/packages/policy/src/index.d.ts +40 -0
  390. package/dist/packages/policy/src/index.js +39 -4
  391. package/dist/packages/runtime/src/index.js +3 -0
  392. package/dist/packages/sandbox/src/index.d.ts +47 -0
  393. package/dist/packages/sandbox/src/index.js +59 -0
  394. package/dist/packages/validator/src/index.d.ts +8 -0
  395. package/dist/packages/validator/src/index.js +21 -6
  396. package/dist/scripts/adr.d.ts +17 -0
  397. package/dist/scripts/adr.js +152 -0
  398. package/dist/scripts/agent-harness.js +72 -64
  399. package/dist/scripts/agent-router.js +20 -20
  400. package/dist/scripts/agent.d.ts +27 -0
  401. package/dist/scripts/agent.js +249 -0
  402. package/dist/scripts/architecture.d.ts +16 -0
  403. package/dist/scripts/architecture.js +186 -0
  404. package/dist/scripts/build-smart-context.js +22 -22
  405. package/dist/scripts/compress-memory.js +8 -8
  406. package/dist/scripts/context-ops.js +29 -29
  407. package/dist/scripts/cost-economy.d.ts +2 -0
  408. package/dist/scripts/cost-economy.js +79 -0
  409. package/dist/scripts/demo-autonomy.js +13 -6
  410. package/dist/scripts/dev.js +13 -13
  411. package/dist/scripts/drift-check.d.ts +17 -0
  412. package/dist/scripts/drift-check.js +63 -0
  413. package/dist/scripts/engineer.d.ts +20 -0
  414. package/dist/scripts/engineer.js +208 -0
  415. package/dist/scripts/evidence.d.ts +12 -0
  416. package/dist/scripts/evidence.js +55 -0
  417. package/dist/scripts/extract-global-knowledge.js +5 -5
  418. package/dist/scripts/gates.d.ts +6 -2
  419. package/dist/scripts/gates.js +14 -4
  420. package/dist/scripts/generate-dashboard.js +11 -11
  421. package/dist/scripts/incident.d.ts +19 -0
  422. package/dist/scripts/incident.js +103 -0
  423. package/dist/scripts/llm-fit.js +32 -3
  424. package/dist/scripts/memory-schema.js +48 -48
  425. package/dist/scripts/provenance.d.ts +14 -0
  426. package/dist/scripts/provenance.js +114 -0
  427. package/dist/scripts/query-universal-memory.js +13 -13
  428. package/dist/scripts/risk.d.ts +15 -0
  429. package/dist/scripts/risk.js +81 -0
  430. package/dist/scripts/simulate.d.ts +20 -0
  431. package/dist/scripts/simulate.js +150 -0
  432. package/dist/scripts/sprint-manager.js +39 -39
  433. package/dist/scripts/sync-universal-memory.js +44 -44
  434. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  435. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  436. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  437. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  438. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  439. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  440. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  441. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  442. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  443. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  444. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  445. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  446. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  447. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  448. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  449. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  450. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  451. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  452. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  453. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  454. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  455. package/docs/agent-harnesses.md +149 -149
  456. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  457. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  458. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  459. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  460. package/docs/archive/FASE2-SUMMARY.md +263 -263
  461. package/docs/archive/FASE3-PROGRESS.md +355 -355
  462. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  463. package/docs/archive/INDICE-MASTER.md +282 -282
  464. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  465. package/docs/archive/README-REFINAMENTO.md +293 -293
  466. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  467. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  468. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  469. package/docs/archive/START-HERE.md +319 -319
  470. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  471. package/docs/archive/examples/v1/AGENTS.md +10 -10
  472. package/docs/archive/examples/v1/README.md +36 -36
  473. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  474. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  475. package/docs/archive/examples/v1/backend/package.json +42 -42
  476. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  477. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  478. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  479. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  480. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  481. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  482. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  483. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  484. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  485. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  486. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  487. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  488. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  489. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  490. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  491. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  492. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  493. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  494. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  495. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  496. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  497. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  498. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  499. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  500. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  501. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  502. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  503. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  504. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  505. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  506. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  507. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  508. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  509. package/docs/archive/examples/v2/AGENTS.md +16 -16
  510. package/docs/archive/examples/v2/README.md +35 -35
  511. package/docs/archive/examples/v2/agents/README.md +3 -3
  512. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  513. package/docs/archive/examples/v2/agents/dba.md +4 -4
  514. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  515. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  516. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  517. package/docs/archive/examples/v2/agents/security.md +4 -4
  518. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  519. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  520. package/docs/archive/examples/v2/backend/package.json +42 -42
  521. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  522. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  523. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  524. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  525. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  526. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  527. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  528. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  529. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  530. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  531. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  532. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  533. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  534. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  535. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  536. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  537. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  538. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  539. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  540. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  541. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  542. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  543. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  544. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  545. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  546. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  547. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  548. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  549. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  550. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  551. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  552. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  553. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  554. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  555. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  556. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  557. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  558. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  559. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  560. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  561. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  562. package/docs/archive/examples/v2/memory/README.md +8 -8
  563. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  564. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  565. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  566. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  567. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  568. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  569. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  570. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  571. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  572. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  573. package/docs/capacidades-externas.md +86 -86
  574. package/docs/cli-first-operacao.md +74 -74
  575. package/docs/dev-workflow.md +421 -421
  576. package/docs/examples.md +546 -546
  577. package/docs/fluxo.md +103 -103
  578. package/docs/glossary.md +453 -453
  579. package/docs/init-project.md +457 -457
  580. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  581. package/docs/personas/architect/README.md +333 -333
  582. package/docs/personas/developer/README.md +371 -371
  583. package/docs/personas/executive/README.md +172 -172
  584. package/docs/personas/qa/README.md +350 -350
  585. package/docs/processo-projeto.md +138 -138
  586. package/docs/publishing.md +377 -377
  587. package/docs/quick-reference.md +409 -409
  588. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  589. package/docs/structure.md +360 -360
  590. package/docs/token-optimization.md +502 -502
  591. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  592. package/memory/00-global/mission.md +15 -15
  593. package/memory/00-global/shared-knowledge.md +8 -8
  594. package/memory/00-global/standards.md +47 -47
  595. package/memory/10-product/personas.md +21 -21
  596. package/memory/10-product/vision.md +27 -27
  597. package/memory/30-projects/README.md +15 -15
  598. package/memory/40-delivery/backlog.md +15 -15
  599. package/memory/40-delivery/current-sprint.md +20 -20
  600. package/memory/50-orchestration/gsd-harness.md +55 -55
  601. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  602. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  603. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  604. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  605. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  606. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  607. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  608. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  609. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  610. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  611. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  612. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  613. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  614. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  615. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  616. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  617. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  618. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  619. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  620. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  621. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  622. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  623. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  624. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  625. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  626. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  627. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  628. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  629. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  630. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  631. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  632. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  633. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  634. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  635. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  636. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  637. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  638. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  639. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  640. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  641. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  642. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  643. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  644. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  645. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  646. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  647. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  648. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  649. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  650. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  651. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  652. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  653. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  654. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  655. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  656. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  657. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  658. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  659. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  660. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  661. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  662. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  663. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  664. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  665. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  666. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  667. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  668. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  669. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  670. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  671. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  672. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  673. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  674. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  675. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  676. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  677. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  678. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  679. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  680. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  681. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  682. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  683. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  684. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  685. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  686. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  687. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  688. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  689. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  690. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  691. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  692. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  693. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  694. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  695. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  696. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  697. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  698. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  699. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  700. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  701. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  702. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  703. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  704. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  705. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  706. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  707. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  708. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  709. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  710. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  711. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  712. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  713. package/memory/90-decisions/_template.md +28 -28
  714. package/package.json +157 -157
  715. package/prompts/context-engineer-agent.md +19 -19
  716. package/prompts/governance-agent.md +16 -16
  717. package/prompts/marketing-agent.md +13 -13
  718. package/prompts/orchestrator-agent.md +18 -18
  719. package/prompts/product-agent.md +13 -13
  720. package/prompts/sdd-architect-agent.md +20 -20
  721. package/specs/README.md +70 -70
  722. package/specs/_templates/plan.md +43 -43
  723. package/specs/_templates/spec.md +43 -43
  724. package/specs/_templates/tasks.md +32 -32
  725. package/specs/agent-identity-reputation/plan.md +133 -0
  726. package/specs/agent-identity-reputation/spec.md +125 -0
  727. package/specs/agent-identity-reputation/tasks.md +51 -0
  728. package/specs/agent-runtime-monitoring/plan.md +78 -0
  729. package/specs/agent-runtime-monitoring/spec.md +92 -0
  730. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  731. package/specs/ai-code-provenance/plan.md +71 -0
  732. package/specs/ai-code-provenance/spec.md +97 -0
  733. package/specs/ai-code-provenance/tasks.md +39 -0
  734. package/specs/architecture-constitution/plan.md +110 -0
  735. package/specs/architecture-constitution/spec.md +114 -0
  736. package/specs/architecture-constitution/tasks.md +58 -0
  737. package/specs/change-risk-engine/plan.md +130 -0
  738. package/specs/change-risk-engine/spec.md +119 -0
  739. package/specs/change-risk-engine/tasks.md +72 -0
  740. package/specs/clean-arch-boilerplate/plan.md +137 -137
  741. package/specs/clean-arch-boilerplate/spec.md +121 -121
  742. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  743. package/specs/cli-first-operacao/plan.md +53 -53
  744. package/specs/cli-first-operacao/spec.md +53 -53
  745. package/specs/cli-first-operacao/tasks.md +53 -53
  746. package/specs/code-context/spec.md +56 -56
  747. package/specs/coerencia-do-sistema/plan.md +155 -155
  748. package/specs/coerencia-do-sistema/spec.md +123 -123
  749. package/specs/coerencia-do-sistema/tasks.md +115 -115
  750. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  751. package/specs/dev-token-assets-db/plan.md +71 -71
  752. package/specs/dev-token-assets-db/spec.md +58 -58
  753. package/specs/dev-token-assets-db/tasks.md +58 -58
  754. package/specs/doctor-do-nucleo/plan.md +165 -165
  755. package/specs/doctor-do-nucleo/spec.md +139 -139
  756. package/specs/doctor-do-nucleo/tasks.md +172 -172
  757. package/specs/drift-sentinel/spec.md +117 -0
  758. package/specs/engineer-facade-extension/plan.md +71 -0
  759. package/specs/engineer-facade-extension/spec.md +98 -0
  760. package/specs/engineer-facade-extension/tasks.md +36 -0
  761. package/specs/engineering-evidence-ledger/plan.md +121 -0
  762. package/specs/engineering-evidence-ledger/spec.md +90 -0
  763. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  764. package/specs/engineering-graph-extensions/plan.md +92 -0
  765. package/specs/engineering-graph-extensions/spec.md +101 -0
  766. package/specs/engineering-graph-extensions/tasks.md +60 -0
  767. package/specs/engineering-intelligence/spec.md +177 -0
  768. package/specs/forja-core/spec.md +71 -71
  769. package/specs/gates/spec.md +63 -63
  770. package/specs/governanca-visivel/plan.md +122 -122
  771. package/specs/governanca-visivel/spec.md +112 -112
  772. package/specs/governanca-visivel/tasks.md +60 -60
  773. package/specs/harness-codegraph/spec.md +71 -71
  774. package/specs/learning-loop-incidents/plan.md +59 -0
  775. package/specs/learning-loop-incidents/spec.md +93 -0
  776. package/specs/learning-loop-incidents/tasks.md +36 -0
  777. package/specs/memory-audit/spec.md +54 -54
  778. package/specs/orchestrate/spec.md +108 -108
  779. package/specs/orchestration-coherent/spec.md +95 -95
  780. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  781. package/specs/predictive-change-simulation/plan.md +109 -0
  782. package/specs/predictive-change-simulation/spec.md +107 -0
  783. package/specs/predictive-change-simulation/tasks.md +41 -0
  784. package/specs/project-smoke/spec.md +96 -96
  785. package/specs/project-upgrade/spec.md +58 -58
  786. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  787. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  788. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  789. package/specs/release-auditor-health/spec.md +23 -23
  790. package/specs/release-gate/plan.md +174 -174
  791. package/specs/release-gate/spec.md +122 -122
  792. package/specs/release-gate/tasks.md +183 -183
  793. package/specs/smart-agent-routing/plan.md +55 -0
  794. package/specs/smart-agent-routing/spec.md +85 -0
  795. package/specs/smart-agent-routing/tasks.md +26 -0
  796. package/specs/ts-migration/plan.md +200 -200
  797. package/specs/ts-migration/spec.md +119 -119
  798. package/specs/ts-migration/tasks.md +110 -110
@@ -0,0 +1,55 @@
1
+ # Plan: Smart Agent Routing
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-01
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ Extensão de `packages/engineering/identity` (mesmo pacote de SPEC-036, não um novo sub-domínio):
10
+ `recommendAgent(profiles, criteria)`, função pura, mesmo estilo de `recommendProfile`
11
+ (`packages/llm`) — soma pontos por critério casado, nunca esconde o porquê. `scripts/agent.ts`
12
+ ganha `agent:recommend`, reaproveitando `SqliteAgentProfileStore.list()` já existente.
13
+
14
+ ## 2. Módulos afetados
15
+
16
+ | Caminho | Mudança | Risco |
17
+ |---|---|---|
18
+ | `packages/engineering/identity/src/index.ts` | `recommendAgent` novo | Baixo — função pura pequena |
19
+ | `scripts/agent.ts` | `agent:recommend` novo subcomando | Baixo |
20
+ | `lib/core/registry.ts` | 1 comando novo | Baixo |
21
+ | `test/agent-identity-reputation.test.js` | testes unitários de `recommendAgent` | — |
22
+ | `test/agent-cli.test.js` | teste de CLI de `agent:recommend` | — |
23
+
24
+ ## 3. Contratos
25
+
26
+ ```ts
27
+ // packages/engineering/identity/src/index.ts
28
+ export interface AgentRecommendation { readonly agentId: string; readonly score: number; readonly reasons: readonly string[]; }
29
+ export function recommendAgent(profiles: readonly AgentProfile2[], criteria: { readonly role: string; readonly domain?: string }): readonly AgentRecommendation[];
30
+ ```
31
+
32
+ Fórmula (D1): `score = (role === criteria.role ? 100 : 0) + (domain casado em architectureDomains ?
33
+ 50 : 0) + (trustLevel ?? 0) * 10` (0-50). Pesos documentados aqui e no código — mesmo princípio de
34
+ `computeReputationScore`/`RiskEngine`. Sem `trustLevel`, o termo de reputação é 0 (não excluído do
35
+ ranking, AC-2) e o motivo declara "sem pontuação ainda".
36
+
37
+ ```bash
38
+ agent:recommend --role <role> [--domain <d>]
39
+ ```
40
+
41
+ ## 4. Decisões
42
+
43
+ **D1**: pesos 100/50/(0-50) espelham a proporção já usada em `recommendProfile` (100 pro papel, 50
44
+ pra tarefa/domínio) — reaproveita a mesma "linguagem de score" em vez de inventar uma nova escala,
45
+ mais fácil de comparar mentalmente entre os dois comandos irmãos.
46
+
47
+ ## 5. Rollout
48
+
49
+ Sem migração, sem feature flag — comando novo, opt-in por natureza.
50
+
51
+ ## 6. Kill criteria
52
+
53
+ Já coberto pelo mesmo princípio de SPEC-034/036: se o ranking não corresponder a julgamento humano
54
+ sobre dado real, os pesos de D1 são revisados antes de qualquer consumo automático (§5 do spec,
55
+ "Fora").
@@ -0,0 +1,85 @@
1
+ # Spec: Smart Agent Routing
2
+
3
+ - **ID**: SPEC-037
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-01
7
+ - **Sprint alvo**: Sprint 5 (segundo sprint da Fase 3 — a peça deixada de fora de SPEC-036 §5
8
+ deliberadamente: "consumo depende deste sprint já estar em produção")
9
+ - **ADRs relacionadas**: ADR-0078; depende de SPEC-036 (`AgentProfile2`/`trustLevel` — a fonte de
10
+ reputação que esta spec consome, não recalcula)
11
+
12
+ > Não confundir com `packages/llm.recommendProfile` (ADR-0074, "LLM Fit Loop") — aquele roteia
13
+ > entre **perfis de provider/model** (`codex`/`claude`/`gemini`/`ollama`) por papel/tarefa; esta
14
+ > spec roteia entre **agentes registrados** (`AgentProfile2`, SPEC-036) por papel/domínio/reputação.
15
+ > São dois problemas adjacentes, não o mesmo — por isso esta spec **estende
16
+ > `packages/engineering/identity`** (onde `AgentProfile2`/`computeReputationScore` já vivem), não
17
+ > `packages/llm`. O gap analysis original (`docs/architecture/...` §3) que sugeriu "estender
18
+ > `llm-fit`" previa isso antes de `AgentProfile2` existir; agora que existe, estender o pacote que
19
+ > já tem o dado é a composição certa, não duplicar o dado em `packages/llm`.
20
+
21
+ ## 1. Problema
22
+
23
+ `AgentProfile2` (SPEC-036) já tem `trustLevel`/`autonomyLevel` reais, derivados de comportamento —
24
+ mas nada usa esse dado pra recomendar **qual agente registrado** é o mais adequado pra um
25
+ papel/domínio. Hoje a escolha de agente é manual e não considera histórico de confiabilidade.
26
+
27
+ ## 2. Proposta de valor
28
+
29
+ `forja agent:recommend --role <role> [--domain <d>]` classifica os agentes já registrados por
30
+ adequação (papel, domínio de arquitetura, reputação), com razões explícitas — nunca um ranking sem
31
+ explicação, mesmo princípio já usado em `risk:assess`/`architecture:check`.
32
+
33
+ ## 3. User stories
34
+
35
+ - **Como** governance/orchestrator, **quero** uma recomendação de qual agente registrado atribuir a
36
+ uma tarefa de um papel/domínio específico, **para que** a escolha considere reputação real, não
37
+ só disponibilidade.
38
+
39
+ ## 4. Critérios de aceite (Definition of Done)
40
+
41
+ - [x] AC-1: `recommendAgent` (função pura, `packages/engineering/identity`, mesmo pacote de
42
+ `computeReputationScore` — SPEC-036) recebe `readonly AgentProfile2[]` + critério
43
+ (`role`, `domain?`) e devolve um ranking com `score` e `reasons[]` — nunca um número sem
44
+ explicação (mesmo padrão de `recommendProfile`/`risk:assess`).
45
+ - [x] AC-2: agente sem `trustLevel` ainda (nunca rodou `agent:score`) ainda aparece no ranking —
46
+ não é excluído, mas o motivo declara explicitamente "sem pontuação ainda", nunca finge um
47
+ trust level que não existe.
48
+ - [x] AC-3: `forja agent:recommend --role <role> [--domain <d>]` (novo subcomando de
49
+ `scripts/agent.ts` — mesmo domínio de comando de SPEC-036, não um script novo) funcional.
50
+ - [x] AC-4: recomendação é **informação**, não decisão — não bloqueia, não atribui, não chama
51
+ `PolicyEngine`/`RuntimeEngine`. Mesmo princípio de `RiskEngine`/SPEC-034 D3: o score informa,
52
+ quem decide continua sendo o humano/orquestrador.
53
+
54
+ ## 5. Escopo
55
+
56
+ **Dentro**: `recommendAgent` (motor puro); `agent:recommend` (CLI).
57
+
58
+ **Fora**: atribuição automática de agente a uma tarefa (decisão continua manual/orquestrador, AC-4);
59
+ routing entre provider/model (`packages/llm.recommendProfile` já existe e não muda aqui);
60
+ `PolicyEngine` consumir a recomendação automaticamente (mesmo raciocínio de SPEC-034/036 — consumo
61
+ é spec própria futura, quando/se fizer sentido).
62
+
63
+ ## 6. NFRs / restrições
64
+
65
+ - Determinístico, sem LLM — mesma fórmula de scoring documentada em código e aqui.
66
+ - Reaproveita `AgentProfile2`/`trustLevel` já persistido — nenhum cálculo de reputação novo (isso é
67
+ SPEC-036, não esta spec).
68
+
69
+ ## 7. Riscos e mitigação
70
+
71
+ | Risco | Probabilidade | Impacto | Mitigação |
72
+ |---|---|---|---|
73
+ | Confundir com `llm:recommend` (routing de provider/model) | Média (nomes parecidos) | Baixa (confusão, não bug) | Nota explícita no topo desta spec e no código; comandos com prefixos diferentes (`agent:` vs. `llm:`) |
74
+ | Ranking virar decisão automática por acidente | Baixa (mesmo padrão já seguido em RiskEngine) | Alta se acontecesse | AC-4 explícito; nenhum código nesta spec chama `PolicyEngine`/atribui trabalho |
75
+
76
+ ## 8. Métricas de sucesso
77
+
78
+ Registrar 2+ agentes com `role`/`architectureDomains`/`trustLevel` diferentes (reaproveitando os
79
+ dados de teste de SPEC-036) e confirmar que `agent:recommend` ordena corretamente por adequação —
80
+ revisão humana, mesma metodologia de SPEC-034/036 §8.
81
+
82
+ **Validado** (`test/agent-cli.test.js`): 3 agentes registrados — `agent-a` (role+domain casados,
83
+ mais reputação real via amostra sintética de SPEC-036: 4 sucessos/1 rollback), `agent-b` (só role),
84
+ `agent-c` (só domain). Ranking saiu `agent-a > agent-b > agent-c`, na ordem esperada por revisão
85
+ humana — nenhum redesenho de pesos necessário (kill criteria do plan não disparado).
@@ -0,0 +1,26 @@
1
+ # Tasks: Smart Agent Routing
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-01
7
+
8
+ ---
9
+
10
+ ## T1 — `recommendAgent` (motor puro) + `agent:recommend` (CLI)
11
+ - **Owner**: worker
12
+ - **Estimativa**: P
13
+ - **Depende de**: —
14
+ - **Paths**: `packages/engineering/identity/src/index.ts`, `scripts/agent.ts`, `lib/core/registry.ts`
15
+ - **Done quando**:
16
+ - [ ] `recommendAgent` implementa a fórmula de D1, agente sem `trustLevel` não é excluído (AC-2)
17
+ - [ ] `agent:recommend --role <role> [--domain <d>]` funcional
18
+ - [ ] testes unitários: role casado, domain casado, sem pontuação ainda, ordenação por score
19
+ - [ ] teste de CLI: 2+ agentes registrados com reputações diferentes, ranking correto
20
+ - [ ] `forja tools:doctor` continua verde
21
+
22
+ ---
23
+
24
+ ## Handoffs entre agentes
25
+
26
+ Sprint pequeno, sem handoff — T1 é a spec inteira.
@@ -1,200 +1,200 @@
1
- # Plan: ts-migration
2
-
3
- - **Spec**: ./spec.md
4
- - **Status**: approved
5
- - **Criado em**: 2026-07-18
6
-
7
- > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
-
9
- ## 1. Abordagem técnica
10
-
11
- O nó da migração não é renomear `.mjs → .ts` — é **como o core acha o script de um comando em dois
12
- runtimes**. Hoje `bin/forja.mjs:118` faz `spawnSync('node', [path.join(root, cmd.node)])`, e o
13
- registry guarda a extensão literal (`scripts/tools-doctor.mjs`). Em dev o alvo é `.ts`; no pacote
14
- publicado é `dist/scripts/tools-doctor.js`. O mesmo registry não pode cravar as duas.
15
-
16
- A saída é **desacoplar o registry da extensão**: a entrada passa a ser `scripts/tools-doctor` (sem
17
- extensão), e o core resolve o arquivo real tentando `.ts → .js → .mjs` conforme o que existe. Em dev
18
- acha o `.ts`; no publicado acha o `.js` sob `dist/`. Isso resolve o runtime duplo com uma mudança
19
- pequena e contida, e ainda limpa o registry.
20
-
21
- Tudo o mais é disciplina: `checkJs` primeiro para achar os erros de tipo com os arquivos ainda
22
- rodando como `.mjs`, depois renomear **leaf-first** com a suíte verde a cada passo. A rede de
23
- segurança é que a migração não muda semântica — se os 109 testes passam sem edição de lógica, a
24
- renomeação não quebrou nada.
25
-
26
- ## 2. Módulos afetados
27
-
28
- | Caminho | Mudança | Risco |
29
- |---|---|---|
30
- | `tsconfig.json` | **criar** — `checkJs` on-ramp, depois `outDir: dist`, `.d.ts` | M |
31
- | `lib/core/registry.mjs` → `.ts` | `node:` sem extensão; tipos `Command`/`Domain` | **A** |
32
- | `bin/forja.mjs` → `.ts` | resolver extension-agnostic (`.ts→.js→.mjs`) no dispatch | **A** |
33
- | `lib/core/checks.mjs` → `.ts` | `Check`/`Probe`/`Result`/`Env` viram tipos reais | M |
34
- | `lib/core/{health,release,doc-graph,workspace}.mjs` → `.ts` | tipam contra `checks.ts` | M |
35
- | `lib/core/release` | `build-fresh` novo; `smoke-commands` usa o `bin` do package.json, não path fixo | M |
36
- | `scripts/*.{mjs,js}` → `.ts` | ~20 arquivos, leaf-first; hooks incluídos | M |
37
- | `lib/generators/*.js` → `.ts` | tipa a assinatura; o **conteúdo** (template string) fica string | B |
38
- | `package.json` | `main`/`types`/`exports`/`bin` → `dist/`; `build`; `files[]` dist; `prepublishOnly` | **A** |
39
- | `.claude/settings.json` | hooks → `.ts` (dev roda nativo) | B |
40
- | `.github/workflows/ci.yml` | só o step `types:check` (o build vive no `release:check`, D4) | B |
41
- | `memory/90-decisions/0026-*.md` | **criar** — ADR | B |
42
-
43
- Os três `A` são o registry, o dispatch e o `package.json` — a tríade que decide se o comando roda
44
- nos dois runtimes. Tudo passa por eles.
45
-
46
- ## 3. Diagrama de fluxo
47
-
48
- ```
49
- DEV (Node 26, sem build) PUBLICADO (Node >=20, dist/)
50
- ────────────────────── ────────────────────────────
51
- node bin/forja.ts forja → dist/bin/forja.js
52
- │ │
53
- │ registry: 'scripts/tools-doctor' │ (mesma entrada, sem extensão)
54
- ▼ ▼
55
- resolve('<root>/scripts/tools-doctor')
56
- tenta .ts → .js → .mjs
57
- │ dev: acha .ts │ publicado: root=dist/, acha dist/scripts/tools-doctor.js
58
- ▼ ▼
59
- spawn node <arquivo resolvido> spawn node <arquivo resolvido>
60
-
61
- build (só p/ publicar): tsc rootDir=. outDir=dist → dist/ espelha a árvore
62
- build-fresh (release:check): recompila e compara com dist/ commitado → reprova se difere
63
- ```
64
-
65
- ## 4. Contratos (API/CLI/Schema)
66
-
67
- ```ts
68
- // lib/core/registry.ts
69
- export interface Command {
70
- domain: string;
71
- desc: string;
72
- node?: string; // caminho SEM extensão, relativo à raiz (dev) / a dist/ (publicado)
73
- bin?: string;
74
- args?: string[];
75
- }
76
- export const COMMANDS: Record<string, Command>;
77
-
78
- // lib/core/checks.ts — os contratos que hoje são @typedef viram tipos verificados
79
- export type Severity = 'critical' | 'warn';
80
- export type Status = 'ok' | 'warn' | 'fail' | 'skipped';
81
- export interface Probe { status: Status; detail: string; fix?: string | null; }
82
- export interface Check { id: string; title: string; severity: Severity; scope?: string;
83
- dependsOn?: string; probe: (env: Env) => Probe | Promise<Probe>; }
84
- ```
85
-
86
- **Resolução de script (o coração)** — `bin/forja.ts` calcula `root = dirname(selfPath)/..`
87
- (dev: repo; publicado: `dist/`) e resolve `cmd.node` tentando as extensões na ordem `.ts, .js,
88
- .mjs`. A primeira que existe vence. Sem extensão no registry, sem `if (isDev)`.
89
-
90
- **`package.json`**:
91
-
92
- | Campo | Valor |
93
- |---|---|
94
- | `bin.forja` | `dist/bin/forja.js` |
95
- | `main` / `types` | `dist/lib/index.js` / `.d.ts` |
96
- | `files[]` | troca `bin/ lib/ scripts/` por `dist/` (o resto — memory/, docs/, boilerplates/ — fica) |
97
- | `scripts.build` | `tsc` |
98
- | `scripts.prepublishOnly` | `node bin/forja.mjs release:check -- --publish` (o gate builda, D4) |
99
-
100
- ## 5. Decisões e alternativas
101
-
102
- **D1: Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
103
- `dist/lib`, `dist/scripts`. Alternativa rejeitada: mover a fonte para `src/`. Isso trocaria todo
104
- import, todo path do registry, os hooks do `settings.json`, o `files[]` e as smoke-commands do
105
- release — blast radius enorme, contra o "verde contínuo". O layout plano mantém a migração mecânica.
106
-
107
- **D2: Registry sem extensão + resolver (o coração).** `node: 'scripts/tools-doctor'`; o core tenta
108
- `.ts→.js→.mjs`. Desacopla o registry do runtime e limpa a entrada. Alternativa rejeitada: guardar
109
- `.js` e exigir build em dev — mata o "roda sem build" (o NFR inegociável). Alternativa rejeitada:
110
- dois registries — é como se chega a duas verdades divergentes, o defeito que a SPEC-009 matou.
111
-
112
- **D3: Runtime duplo.** Dev roda `.ts` nativo (confirmado: Node 26 executa `.ts` e `node --test`
113
- roda `.ts`); publicado roda `dist/.js`. `engines.node` fica `>=20` — por isso publicamos compilado.
114
- O usuário final não é obrigado a Node novo; o dev sim.
115
-
116
- **D4 (revisado na implementação): o gate builda o `dist/`, e o `dist/` não é commitado.** O plano
117
- original commitava `dist/` e um check `build-fresh` fazia diff contra a fonte — mas isso guarda um
118
- artefato de build no git e reintroduz staleness ("o `dist/` commitado bate com o `src/`?"). A versão
119
- que shipou é mais simples: `dist/` é gitignored e o `release:check` roda `npm run build` **antes de
120
- empacotar** (só quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
121
- empacota o mesmo disco recém-buildado, o tarball provado é exatamente o publicado — sem diff, sem
122
- artefato no git, sem janela de staleness. Efeito colateral que destravou a Fase 3: a prova fica
123
- self-contained e **não precisa de um step de `build` no `ci.yml`** (que exigiria escopo de workflow e
124
- acoplaria a prova ao CI). Uma máquina — o gate — constrói e prova.
125
-
126
- **D5: `checkJs` antes de renomear; leaf-first depois.** Ordem por dependência:
127
- `workspace → checks → registry → doc-graph → health/release → scripts → hooks → bin → generators`.
128
- Verde a cada arquivo. Alternativa rejeitada: renomear tudo e consertar no fim — big-bang, sinal sujo.
129
-
130
- **D6: `tsc` com `rewriteRelativeImportExtensions` (TS 5.7+).** A fonte importa `./x.ts`; o `tsc`
131
- reescreve para `./x.js` no emit. É o mecanismo oficial para fonte-`.ts`-roda-nativo + build. Sem
132
- ele, os imports estáticos não resolveriam nos dois mundos.
133
-
134
- **D7: `smoke-commands` do release usa o `bin` do package.json.** Hoje ele monta
135
- `path.join(pkgDir, 'bin', 'forja.mjs')` — quebraria com `dist/bin/forja.js`. Passa a ler o campo
136
- `bin`. Correção de robustez que a migração torna obrigatória.
137
-
138
- **D8: Fase 2 e Fase 3 se fundem (achado da implementação).** O plano tratava renomear (Fase 2) e
139
- buildar (Fase 3) como fases separadas. Não são: `.ts` **não roda em Node < 22.18**, e o
140
- `engines.node` é `>=20`. No instante em que a fonte vira `.ts`, um pacote publicado **sem `dist/`**
141
- quebra para quem está em Node 20/21, e o `release:check` (instalação limpa no CI) reprova. Não
142
- existe estado intermediário *publicável* meio-renomeado. Então a renomeação e o `dist/` andam
143
- juntos, mantendo o `release:check` verde o tempo todo. Em dev nada muda (Node 26 roda `.ts`); o
144
- acoplamento é só na fronteira do publicado. Estratégia de menor risco: **provar o pipeline de build
145
- + runtime duplo primeiro** (a parte nova e arriscada), depois a renomeação leaf-first vira grind
146
- mecânico sobre trilho provado.
147
-
148
- **D9: Publicar `dist/` desde já desacopla o risco (achado ao provar o pipeline).** O `tsc` emite um
149
- `dist/` que espelha a árvore, e `node dist/bin/forja.mjs` roda (o `resolveScript` acha
150
- `dist/scripts/`). A consequência: se o pacote **sempre embarca `dist/`** — mesmo enquanto a fonte
151
- ainda é `.mjs` (o build vira uma cópia) — o artefato publicado é sempre JS runnable, e o
152
- acoplamento de Node-floor do D8 **nunca morde**. Então a ordem certa inverte a intuição: primeiro a
153
- **infra de release** (build → `dist/`, `package.json` apontando para `dist/`, `prepublishOnly`),
154
- com a fonte ainda `.mjs` — a plumbing de release provada sobre código que não pode quebrar em
155
- runtime. **Depois** a renomeação `.mjs → .ts` vira mudança **interna**: a fonte muda, o `dist/`
156
- regenera como `.js`, e o publicado nunca vê `.ts` cru. O `.ts`-não-roda-em-Node-20 deixa de ser
157
- risco porque o publicado é sempre `dist/`.
158
-
159
- D2, D3 e D4 são estruturais → **ADR-0026**, referenciando ADR-0021 (o NFR "roda sem build" e a
160
- classe "dist mente") e ADR-0024 (o gate que ganha o `build-fresh`).
161
-
162
- ## 6. Dependências
163
-
164
- - **Specs**: SPEC-011 (o catálogo de doc-graph já na main — migra junto). Já `done`.
165
- - **Pacotes npm**: `typescript` como **devDependency** (≥ 5.7, por D6). Zero dependência de runtime
166
- nova — o publicado segue só com `better-sqlite3`.
167
- - **Migrações de dado**: nenhuma.
168
-
169
- ## 7. Rollout
170
-
171
- - [x] **Fase 0 — on-ramp.** `tsconfig` com `checkJs, strict, noEmit`; `types:check` no registry e
172
- no CI. Corrigir os erros com os arquivos ainda `.mjs`. Nada renomeado ainda.
173
- - [x] **Fase 1 — resolver.** Registry sem extensão (na verdade: registry mantém `.mjs` e o
174
- `resolveScript` faz strip + tenta `.ts/.js/.mjs`), dispatch pelo resolver. Suíte verde.
175
- - [x] **Fase 2 — renomear leaf-first + endurecer.** **Concluída.** Toda a fonte do framework é `.ts`
176
- (21 `.mjs` + 16 `.js`), e `noImplicitAny` está ON — os ~285 params foram anotados (tipo real
177
- onde agrega, `any` explícito onde é dinâmico). Shim `lib/vendor.d.ts` para o `better-sqlite3`
178
- sem tipos; `lib/templates` excluído do type-check (é conteúdo). O ratchet está armado.
179
- Achados recorrentes no `.ts` estrito: `[]`→`never[]` (anotação inline), os casts-comentário
180
- `/** @type */ (x)` não narram (viram `as`), e os typedefs JSDoc viram `interface`/`import type`
181
- reais. Armadilha corrigida em voo: o sed que atualizava os `node:` do registry atingiu também o
182
- array de fallback do `resolveScript` (`['.ts','.js','.mjs']`→`['.ts','.ts','.ts']`), quebrando a
183
- resolução do `dist/*.js` — pego pelo `release:check`, não pelo type-check nem pelos testes.
184
- - [x] **Fase 3 — build + publish.** `tsc` emitindo `dist/`; `package.json` apontando para `dist/`;
185
- `prepublishOnly` = gate (o gate builda, D4 revisado). Provado por `release:check` (#15).
186
- - [x] Doc/persona: governança ganha o `build-fresh`; `docs/` e `CONTRIBUTING` ganham o "dev roda
187
- `.ts`, publicado roda `dist`".
188
- - [ ] **Prova final**: `release:check` aprova o tarball com `dist/` fresco; reintroduzir um `dist/`
189
- defasado e confirmar que o `build-fresh` reprova.
190
-
191
- ## 8. Sinais de fracasso (kill criteria)
192
-
193
- - **O hook passa a exigir build em dev.** Se em algum ponto o `SessionStart` não rodar sem `dist/`,
194
- o design falhou o NFR inegociável — pausa e reavalia o runtime duplo antes de seguir.
195
- - **O resolver de extensão fica ambíguo** (um `.ts` e um `.js` do mesmo nome convivendo em dev).
196
- Mitigação: `.gitignore` do `dist/` em dev + o `build-fresh` garante que dist não anda solto.
197
- - **`strict` vira um poço sem fundo.** Se a Fase 0 não estabilizar em tempo razoável, afrouxa para
198
- `strict` incremental (por arquivo via `// @ts-expect-error` pontual), nunca desligando o gate.
199
- - **A migração começa a mudar comportamento pra agradar o compilador.** Se um teste precisar mudar
200
- de semântica, parou de ser migração — isola aquela mudança numa spec própria e segue.
1
+ # Plan: ts-migration
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-07-18
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ O nó da migração não é renomear `.mjs → .ts` — é **como o core acha o script de um comando em dois
12
+ runtimes**. Hoje `bin/forja.mjs:118` faz `spawnSync('node', [path.join(root, cmd.node)])`, e o
13
+ registry guarda a extensão literal (`scripts/tools-doctor.mjs`). Em dev o alvo é `.ts`; no pacote
14
+ publicado é `dist/scripts/tools-doctor.js`. O mesmo registry não pode cravar as duas.
15
+
16
+ A saída é **desacoplar o registry da extensão**: a entrada passa a ser `scripts/tools-doctor` (sem
17
+ extensão), e o core resolve o arquivo real tentando `.ts → .js → .mjs` conforme o que existe. Em dev
18
+ acha o `.ts`; no publicado acha o `.js` sob `dist/`. Isso resolve o runtime duplo com uma mudança
19
+ pequena e contida, e ainda limpa o registry.
20
+
21
+ Tudo o mais é disciplina: `checkJs` primeiro para achar os erros de tipo com os arquivos ainda
22
+ rodando como `.mjs`, depois renomear **leaf-first** com a suíte verde a cada passo. A rede de
23
+ segurança é que a migração não muda semântica — se os 109 testes passam sem edição de lógica, a
24
+ renomeação não quebrou nada.
25
+
26
+ ## 2. Módulos afetados
27
+
28
+ | Caminho | Mudança | Risco |
29
+ |---|---|---|
30
+ | `tsconfig.json` | **criar** — `checkJs` on-ramp, depois `outDir: dist`, `.d.ts` | M |
31
+ | `lib/core/registry.mjs` → `.ts` | `node:` sem extensão; tipos `Command`/`Domain` | **A** |
32
+ | `bin/forja.mjs` → `.ts` | resolver extension-agnostic (`.ts→.js→.mjs`) no dispatch | **A** |
33
+ | `lib/core/checks.mjs` → `.ts` | `Check`/`Probe`/`Result`/`Env` viram tipos reais | M |
34
+ | `lib/core/{health,release,doc-graph,workspace}.mjs` → `.ts` | tipam contra `checks.ts` | M |
35
+ | `lib/core/release` | `build-fresh` novo; `smoke-commands` usa o `bin` do package.json, não path fixo | M |
36
+ | `scripts/*.{mjs,js}` → `.ts` | ~20 arquivos, leaf-first; hooks incluídos | M |
37
+ | `lib/generators/*.js` → `.ts` | tipa a assinatura; o **conteúdo** (template string) fica string | B |
38
+ | `package.json` | `main`/`types`/`exports`/`bin` → `dist/`; `build`; `files[]` dist; `prepublishOnly` | **A** |
39
+ | `.claude/settings.json` | hooks → `.ts` (dev roda nativo) | B |
40
+ | `.github/workflows/ci.yml` | só o step `types:check` (o build vive no `release:check`, D4) | B |
41
+ | `memory/90-decisions/0026-*.md` | **criar** — ADR | B |
42
+
43
+ Os três `A` são o registry, o dispatch e o `package.json` — a tríade que decide se o comando roda
44
+ nos dois runtimes. Tudo passa por eles.
45
+
46
+ ## 3. Diagrama de fluxo
47
+
48
+ ```
49
+ DEV (Node 26, sem build) PUBLICADO (Node >=20, dist/)
50
+ ────────────────────── ────────────────────────────
51
+ node bin/forja.ts forja → dist/bin/forja.js
52
+ │ │
53
+ │ registry: 'scripts/tools-doctor' │ (mesma entrada, sem extensão)
54
+ ▼ ▼
55
+ resolve('<root>/scripts/tools-doctor')
56
+ tenta .ts → .js → .mjs
57
+ │ dev: acha .ts │ publicado: root=dist/, acha dist/scripts/tools-doctor.js
58
+ ▼ ▼
59
+ spawn node <arquivo resolvido> spawn node <arquivo resolvido>
60
+
61
+ build (só p/ publicar): tsc rootDir=. outDir=dist → dist/ espelha a árvore
62
+ build-fresh (release:check): recompila e compara com dist/ commitado → reprova se difere
63
+ ```
64
+
65
+ ## 4. Contratos (API/CLI/Schema)
66
+
67
+ ```ts
68
+ // lib/core/registry.ts
69
+ export interface Command {
70
+ domain: string;
71
+ desc: string;
72
+ node?: string; // caminho SEM extensão, relativo à raiz (dev) / a dist/ (publicado)
73
+ bin?: string;
74
+ args?: string[];
75
+ }
76
+ export const COMMANDS: Record<string, Command>;
77
+
78
+ // lib/core/checks.ts — os contratos que hoje são @typedef viram tipos verificados
79
+ export type Severity = 'critical' | 'warn';
80
+ export type Status = 'ok' | 'warn' | 'fail' | 'skipped';
81
+ export interface Probe { status: Status; detail: string; fix?: string | null; }
82
+ export interface Check { id: string; title: string; severity: Severity; scope?: string;
83
+ dependsOn?: string; probe: (env: Env) => Probe | Promise<Probe>; }
84
+ ```
85
+
86
+ **Resolução de script (o coração)** — `bin/forja.ts` calcula `root = dirname(selfPath)/..`
87
+ (dev: repo; publicado: `dist/`) e resolve `cmd.node` tentando as extensões na ordem `.ts, .js,
88
+ .mjs`. A primeira que existe vence. Sem extensão no registry, sem `if (isDev)`.
89
+
90
+ **`package.json`**:
91
+
92
+ | Campo | Valor |
93
+ |---|---|
94
+ | `bin.forja` | `dist/bin/forja.js` |
95
+ | `main` / `types` | `dist/lib/index.js` / `.d.ts` |
96
+ | `files[]` | troca `bin/ lib/ scripts/` por `dist/` (o resto — memory/, docs/, boilerplates/ — fica) |
97
+ | `scripts.build` | `tsc` |
98
+ | `scripts.prepublishOnly` | `node bin/forja.mjs release:check -- --publish` (o gate builda, D4) |
99
+
100
+ ## 5. Decisões e alternativas
101
+
102
+ **D1: Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
103
+ `dist/lib`, `dist/scripts`. Alternativa rejeitada: mover a fonte para `src/`. Isso trocaria todo
104
+ import, todo path do registry, os hooks do `settings.json`, o `files[]` e as smoke-commands do
105
+ release — blast radius enorme, contra o "verde contínuo". O layout plano mantém a migração mecânica.
106
+
107
+ **D2: Registry sem extensão + resolver (o coração).** `node: 'scripts/tools-doctor'`; o core tenta
108
+ `.ts→.js→.mjs`. Desacopla o registry do runtime e limpa a entrada. Alternativa rejeitada: guardar
109
+ `.js` e exigir build em dev — mata o "roda sem build" (o NFR inegociável). Alternativa rejeitada:
110
+ dois registries — é como se chega a duas verdades divergentes, o defeito que a SPEC-009 matou.
111
+
112
+ **D3: Runtime duplo.** Dev roda `.ts` nativo (confirmado: Node 26 executa `.ts` e `node --test`
113
+ roda `.ts`); publicado roda `dist/.js`. `engines.node` fica `>=20` — por isso publicamos compilado.
114
+ O usuário final não é obrigado a Node novo; o dev sim.
115
+
116
+ **D4 (revisado na implementação): o gate builda o `dist/`, e o `dist/` não é commitado.** O plano
117
+ original commitava `dist/` e um check `build-fresh` fazia diff contra a fonte — mas isso guarda um
118
+ artefato de build no git e reintroduz staleness ("o `dist/` commitado bate com o `src/`?"). A versão
119
+ que shipou é mais simples: `dist/` é gitignored e o `release:check` roda `npm run build` **antes de
120
+ empacotar** (só quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
121
+ empacota o mesmo disco recém-buildado, o tarball provado é exatamente o publicado — sem diff, sem
122
+ artefato no git, sem janela de staleness. Efeito colateral que destravou a Fase 3: a prova fica
123
+ self-contained e **não precisa de um step de `build` no `ci.yml`** (que exigiria escopo de workflow e
124
+ acoplaria a prova ao CI). Uma máquina — o gate — constrói e prova.
125
+
126
+ **D5: `checkJs` antes de renomear; leaf-first depois.** Ordem por dependência:
127
+ `workspace → checks → registry → doc-graph → health/release → scripts → hooks → bin → generators`.
128
+ Verde a cada arquivo. Alternativa rejeitada: renomear tudo e consertar no fim — big-bang, sinal sujo.
129
+
130
+ **D6: `tsc` com `rewriteRelativeImportExtensions` (TS 5.7+).** A fonte importa `./x.ts`; o `tsc`
131
+ reescreve para `./x.js` no emit. É o mecanismo oficial para fonte-`.ts`-roda-nativo + build. Sem
132
+ ele, os imports estáticos não resolveriam nos dois mundos.
133
+
134
+ **D7: `smoke-commands` do release usa o `bin` do package.json.** Hoje ele monta
135
+ `path.join(pkgDir, 'bin', 'forja.mjs')` — quebraria com `dist/bin/forja.js`. Passa a ler o campo
136
+ `bin`. Correção de robustez que a migração torna obrigatória.
137
+
138
+ **D8: Fase 2 e Fase 3 se fundem (achado da implementação).** O plano tratava renomear (Fase 2) e
139
+ buildar (Fase 3) como fases separadas. Não são: `.ts` **não roda em Node < 22.18**, e o
140
+ `engines.node` é `>=20`. No instante em que a fonte vira `.ts`, um pacote publicado **sem `dist/`**
141
+ quebra para quem está em Node 20/21, e o `release:check` (instalação limpa no CI) reprova. Não
142
+ existe estado intermediário *publicável* meio-renomeado. Então a renomeação e o `dist/` andam
143
+ juntos, mantendo o `release:check` verde o tempo todo. Em dev nada muda (Node 26 roda `.ts`); o
144
+ acoplamento é só na fronteira do publicado. Estratégia de menor risco: **provar o pipeline de build
145
+ + runtime duplo primeiro** (a parte nova e arriscada), depois a renomeação leaf-first vira grind
146
+ mecânico sobre trilho provado.
147
+
148
+ **D9: Publicar `dist/` desde já desacopla o risco (achado ao provar o pipeline).** O `tsc` emite um
149
+ `dist/` que espelha a árvore, e `node dist/bin/forja.mjs` roda (o `resolveScript` acha
150
+ `dist/scripts/`). A consequência: se o pacote **sempre embarca `dist/`** — mesmo enquanto a fonte
151
+ ainda é `.mjs` (o build vira uma cópia) — o artefato publicado é sempre JS runnable, e o
152
+ acoplamento de Node-floor do D8 **nunca morde**. Então a ordem certa inverte a intuição: primeiro a
153
+ **infra de release** (build → `dist/`, `package.json` apontando para `dist/`, `prepublishOnly`),
154
+ com a fonte ainda `.mjs` — a plumbing de release provada sobre código que não pode quebrar em
155
+ runtime. **Depois** a renomeação `.mjs → .ts` vira mudança **interna**: a fonte muda, o `dist/`
156
+ regenera como `.js`, e o publicado nunca vê `.ts` cru. O `.ts`-não-roda-em-Node-20 deixa de ser
157
+ risco porque o publicado é sempre `dist/`.
158
+
159
+ D2, D3 e D4 são estruturais → **ADR-0026**, referenciando ADR-0021 (o NFR "roda sem build" e a
160
+ classe "dist mente") e ADR-0024 (o gate que ganha o `build-fresh`).
161
+
162
+ ## 6. Dependências
163
+
164
+ - **Specs**: SPEC-011 (o catálogo de doc-graph já na main — migra junto). Já `done`.
165
+ - **Pacotes npm**: `typescript` como **devDependency** (≥ 5.7, por D6). Zero dependência de runtime
166
+ nova — o publicado segue só com `better-sqlite3`.
167
+ - **Migrações de dado**: nenhuma.
168
+
169
+ ## 7. Rollout
170
+
171
+ - [x] **Fase 0 — on-ramp.** `tsconfig` com `checkJs, strict, noEmit`; `types:check` no registry e
172
+ no CI. Corrigir os erros com os arquivos ainda `.mjs`. Nada renomeado ainda.
173
+ - [x] **Fase 1 — resolver.** Registry sem extensão (na verdade: registry mantém `.mjs` e o
174
+ `resolveScript` faz strip + tenta `.ts/.js/.mjs`), dispatch pelo resolver. Suíte verde.
175
+ - [x] **Fase 2 — renomear leaf-first + endurecer.** **Concluída.** Toda a fonte do framework é `.ts`
176
+ (21 `.mjs` + 16 `.js`), e `noImplicitAny` está ON — os ~285 params foram anotados (tipo real
177
+ onde agrega, `any` explícito onde é dinâmico). Shim `lib/vendor.d.ts` para o `better-sqlite3`
178
+ sem tipos; `lib/templates` excluído do type-check (é conteúdo). O ratchet está armado.
179
+ Achados recorrentes no `.ts` estrito: `[]`→`never[]` (anotação inline), os casts-comentário
180
+ `/** @type */ (x)` não narram (viram `as`), e os typedefs JSDoc viram `interface`/`import type`
181
+ reais. Armadilha corrigida em voo: o sed que atualizava os `node:` do registry atingiu também o
182
+ array de fallback do `resolveScript` (`['.ts','.js','.mjs']`→`['.ts','.ts','.ts']`), quebrando a
183
+ resolução do `dist/*.js` — pego pelo `release:check`, não pelo type-check nem pelos testes.
184
+ - [x] **Fase 3 — build + publish.** `tsc` emitindo `dist/`; `package.json` apontando para `dist/`;
185
+ `prepublishOnly` = gate (o gate builda, D4 revisado). Provado por `release:check` (#15).
186
+ - [x] Doc/persona: governança ganha o `build-fresh`; `docs/` e `CONTRIBUTING` ganham o "dev roda
187
+ `.ts`, publicado roda `dist`".
188
+ - [ ] **Prova final**: `release:check` aprova o tarball com `dist/` fresco; reintroduzir um `dist/`
189
+ defasado e confirmar que o `build-fresh` reprova.
190
+
191
+ ## 8. Sinais de fracasso (kill criteria)
192
+
193
+ - **O hook passa a exigir build em dev.** Se em algum ponto o `SessionStart` não rodar sem `dist/`,
194
+ o design falhou o NFR inegociável — pausa e reavalia o runtime duplo antes de seguir.
195
+ - **O resolver de extensão fica ambíguo** (um `.ts` e um `.js` do mesmo nome convivendo em dev).
196
+ Mitigação: `.gitignore` do `dist/` em dev + o `build-fresh` garante que dist não anda solto.
197
+ - **`strict` vira um poço sem fundo.** Se a Fase 0 não estabilizar em tempo razoável, afrouxa para
198
+ `strict` incremental (por arquivo via `// @ts-expect-error` pontual), nunca desligando o gate.
199
+ - **A migração começa a mudar comportamento pra agradar o compilador.** Se um teste precisar mudar
200
+ de semântica, parou de ser migração — isola aquela mudança numa spec própria e segue.