forjajs 2.0.4 → 4.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 (825) hide show
  1. package/.claude/agents/context-engineer.md +19 -25
  2. package/.claude/agents/governance.md +19 -55
  3. package/.claude/agents/marketing.md +19 -24
  4. package/.claude/agents/orchestrator.md +19 -31
  5. package/.claude/agents/product.md +19 -26
  6. package/.claude/agents/release-auditor.md +50 -50
  7. package/.claude/agents/sdd-architect.md +19 -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 +93 -87
  12. package/.github/copilot-instructions.md +93 -87
  13. package/.memoryrc.json +104 -104
  14. package/.openai-instructions.md +93 -87
  15. package/AGENTS.md +137 -134
  16. package/CHANGELOG.md +656 -555
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +68 -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 +17 -1
  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/release.js +3 -0
  353. package/dist/lib/core/risk-collect.d.ts +19 -0
  354. package/dist/lib/core/risk-collect.js +173 -0
  355. package/dist/lib/drift-sentinel.d.ts +59 -0
  356. package/dist/lib/drift-sentinel.js +126 -0
  357. package/dist/lib/generators/memory-generator.js +691 -691
  358. package/dist/lib/generators/nest-generator.js +412 -398
  359. package/dist/lib/generators/readme-generator.js +180 -180
  360. package/dist/lib/governance-report.js +39 -39
  361. package/dist/lib/llm/codex-output.d.ts +12 -0
  362. package/dist/lib/llm/codex-output.js +56 -0
  363. package/dist/lib/llm/context.d.ts +5 -0
  364. package/dist/lib/llm/context.js +17 -0
  365. package/dist/lib/llm/session.d.ts +18 -0
  366. package/dist/lib/llm/session.js +34 -0
  367. package/dist/lib/llm/validation.d.ts +37 -0
  368. package/dist/lib/llm/validation.js +88 -0
  369. package/dist/lib/workspace.js +29 -29
  370. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  371. package/dist/packages/adapter-git/src/index.js +11 -6
  372. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  373. package/dist/packages/adapter-nest/src/index.js +26 -1
  374. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  375. package/dist/packages/adapter-sqlite/src/index.js +61 -12
  376. package/dist/packages/contracts/src/index.d.ts +33 -0
  377. package/dist/packages/contracts/src/index.js +13 -0
  378. package/dist/packages/core/src/index.d.ts +12 -0
  379. package/dist/packages/core/src/index.js +29 -0
  380. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  381. package/dist/packages/engineering/architecture/src/index.js +131 -0
  382. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  383. package/dist/packages/engineering/evidence/src/index.js +31 -0
  384. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  385. package/dist/packages/engineering/identity/src/index.js +88 -0
  386. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  387. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  388. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  389. package/dist/packages/engineering/provenance/src/index.js +21 -0
  390. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  391. package/dist/packages/engineering/risk/src/index.js +120 -0
  392. package/dist/packages/evals/src/index.js +6 -0
  393. package/dist/packages/graph/src/index.d.ts +23 -1
  394. package/dist/packages/graph/src/index.js +88 -15
  395. package/dist/packages/llm/src/index.d.ts +8 -1
  396. package/dist/packages/llm/src/index.js +64 -7
  397. package/dist/packages/mcp/src/index.js +27 -8
  398. package/dist/packages/orchestration/src/index.d.ts +11 -1
  399. package/dist/packages/orchestration/src/index.js +34 -7
  400. package/dist/packages/policy/src/index.d.ts +40 -0
  401. package/dist/packages/policy/src/index.js +39 -4
  402. package/dist/packages/runtime/src/index.js +3 -0
  403. package/dist/packages/sandbox/src/index.d.ts +47 -0
  404. package/dist/packages/sandbox/src/index.js +59 -0
  405. package/dist/packages/validator/src/index.d.ts +8 -0
  406. package/dist/packages/validator/src/index.js +21 -6
  407. package/dist/scripts/adr.d.ts +17 -0
  408. package/dist/scripts/adr.js +152 -0
  409. package/dist/scripts/agent-harness.js +72 -64
  410. package/dist/scripts/agent-router.js +20 -20
  411. package/dist/scripts/agent.d.ts +27 -0
  412. package/dist/scripts/agent.js +249 -0
  413. package/dist/scripts/architecture.d.ts +16 -0
  414. package/dist/scripts/architecture.js +186 -0
  415. package/dist/scripts/build-smart-context.js +22 -22
  416. package/dist/scripts/compress-memory.js +8 -8
  417. package/dist/scripts/context-ops.js +29 -29
  418. package/dist/scripts/cost-economy.d.ts +2 -0
  419. package/dist/scripts/cost-economy.js +79 -0
  420. package/dist/scripts/demo-autonomy.js +13 -6
  421. package/dist/scripts/dev.js +13 -13
  422. package/dist/scripts/drift-check.d.ts +17 -0
  423. package/dist/scripts/drift-check.js +63 -0
  424. package/dist/scripts/engineer.d.ts +20 -0
  425. package/dist/scripts/engineer.js +208 -0
  426. package/dist/scripts/evidence.d.ts +12 -0
  427. package/dist/scripts/evidence.js +55 -0
  428. package/dist/scripts/extract-global-knowledge.js +5 -5
  429. package/dist/scripts/gates.d.ts +6 -2
  430. package/dist/scripts/gates.js +14 -4
  431. package/dist/scripts/generate-dashboard.js +11 -11
  432. package/dist/scripts/incident.d.ts +19 -0
  433. package/dist/scripts/incident.js +103 -0
  434. package/dist/scripts/llm-fit.js +85 -9
  435. package/dist/scripts/memory-schema.js +48 -48
  436. package/dist/scripts/provenance.d.ts +14 -0
  437. package/dist/scripts/provenance.js +114 -0
  438. package/dist/scripts/query-universal-memory.js +13 -13
  439. package/dist/scripts/risk.d.ts +15 -0
  440. package/dist/scripts/risk.js +81 -0
  441. package/dist/scripts/simulate.d.ts +20 -0
  442. package/dist/scripts/simulate.js +150 -0
  443. package/dist/scripts/sprint-manager.js +39 -39
  444. package/dist/scripts/sync-universal-memory.js +44 -44
  445. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  446. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  447. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  448. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  449. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  450. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  451. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  452. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  453. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  454. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  455. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  456. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  457. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  458. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  459. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  460. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  461. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  462. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  463. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  464. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  465. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  466. package/docs/agent-harnesses.md +149 -149
  467. package/docs/agent-operating-contract.md +26 -0
  468. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  469. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  470. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  471. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  472. package/docs/archive/FASE2-SUMMARY.md +263 -263
  473. package/docs/archive/FASE3-PROGRESS.md +355 -355
  474. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  475. package/docs/archive/INDICE-MASTER.md +282 -282
  476. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  477. package/docs/archive/README-REFINAMENTO.md +293 -293
  478. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  479. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  480. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  481. package/docs/archive/START-HERE.md +319 -319
  482. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  483. package/docs/archive/examples/v1/AGENTS.md +10 -10
  484. package/docs/archive/examples/v1/README.md +36 -36
  485. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  486. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  487. package/docs/archive/examples/v1/backend/package.json +42 -42
  488. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  489. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  490. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  491. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  492. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  493. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  494. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  495. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  496. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  497. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  498. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  499. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  500. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  501. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  502. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  503. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  504. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  505. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  506. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  507. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  508. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  509. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  510. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  511. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  512. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  513. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  514. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  515. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  516. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  517. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  518. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  519. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  520. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  521. package/docs/archive/examples/v2/AGENTS.md +16 -16
  522. package/docs/archive/examples/v2/README.md +35 -35
  523. package/docs/archive/examples/v2/agents/README.md +3 -3
  524. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  525. package/docs/archive/examples/v2/agents/dba.md +4 -4
  526. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  527. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  528. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  529. package/docs/archive/examples/v2/agents/security.md +4 -4
  530. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  531. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  532. package/docs/archive/examples/v2/backend/package.json +42 -42
  533. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  534. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  535. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  536. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  537. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  538. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  539. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  540. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  541. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  542. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  543. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  544. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  545. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  546. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  547. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  548. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  549. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  550. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  551. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  552. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  553. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  554. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  555. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  556. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  557. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  558. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  559. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  560. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  561. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  562. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  563. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  564. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  565. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  566. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  567. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  568. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  569. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  570. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  571. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  572. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  573. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  574. package/docs/archive/examples/v2/memory/README.md +8 -8
  575. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  576. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  577. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  578. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  579. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  580. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  581. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  582. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  583. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  584. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  585. package/docs/capacidades-externas.md +86 -86
  586. package/docs/cli-first-operacao.md +74 -74
  587. package/docs/dev-workflow.md +421 -421
  588. package/docs/examples.md +546 -546
  589. package/docs/fluxo.md +103 -103
  590. package/docs/glossary.md +453 -453
  591. package/docs/init-project.md +457 -457
  592. package/docs/llm-evolution.md +51 -0
  593. package/docs/llm-fit-loop.md +134 -5
  594. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  595. package/docs/personas/architect/README.md +333 -333
  596. package/docs/personas/developer/README.md +371 -371
  597. package/docs/personas/executive/README.md +172 -172
  598. package/docs/personas/qa/README.md +350 -350
  599. package/docs/processo-projeto.md +138 -138
  600. package/docs/publishing.md +49 -377
  601. package/docs/quick-reference.md +409 -409
  602. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  603. package/docs/structure.md +360 -360
  604. package/docs/token-optimization.md +502 -502
  605. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  606. package/memory/00-global/mission.md +15 -15
  607. package/memory/00-global/shared-knowledge.md +8 -8
  608. package/memory/00-global/standards.md +47 -47
  609. package/memory/10-product/personas.md +21 -21
  610. package/memory/10-product/vision.md +27 -27
  611. package/memory/30-projects/README.md +15 -15
  612. package/memory/40-delivery/backlog.md +15 -15
  613. package/memory/40-delivery/current-sprint.md +20 -20
  614. package/memory/50-orchestration/gsd-harness.md +55 -55
  615. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  616. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  617. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  618. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  619. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  620. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  621. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  622. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  623. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  624. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  625. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  626. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  627. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  628. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  629. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  630. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  631. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  632. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  633. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  634. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  635. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  636. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  637. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  638. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  639. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  640. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  641. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  642. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  643. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  644. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  645. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  646. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  647. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  648. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  649. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  650. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  651. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  652. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  653. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  654. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  655. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  656. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  657. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  658. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  659. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  660. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  661. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  662. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  663. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  664. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  665. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  666. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  667. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  668. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  669. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  670. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  671. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  672. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  673. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  674. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  675. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  676. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  677. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  678. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  679. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  680. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  681. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  682. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  683. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  684. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  685. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  686. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  687. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  688. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  689. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  690. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  691. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  692. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  693. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  694. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  695. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  696. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  697. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  698. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  699. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  700. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  701. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  702. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  703. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  704. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  705. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  706. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  707. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  708. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  709. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  710. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  711. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  712. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  713. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  714. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  715. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  716. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  717. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  718. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  719. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  720. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  721. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  722. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  723. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  724. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  725. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  726. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  727. package/memory/90-decisions/0080-llm-execution-evidence.md +42 -0
  728. package/memory/90-decisions/0081-llm-resume-validation.md +42 -0
  729. package/memory/90-decisions/_template.md +28 -28
  730. package/package.json +159 -157
  731. package/prompts/context-engineer-agent.md +13 -19
  732. package/prompts/governance-agent.md +13 -16
  733. package/prompts/marketing-agent.md +13 -13
  734. package/prompts/orchestrator-agent.md +13 -18
  735. package/prompts/product-agent.md +13 -13
  736. package/prompts/sdd-architect-agent.md +13 -20
  737. package/skills/MANIFEST.json +10 -0
  738. package/skills/llm-provider-routing/SKILL.md +18 -0
  739. package/specs/README.md +70 -70
  740. package/specs/_templates/plan.md +50 -43
  741. package/specs/_templates/spec.md +50 -43
  742. package/specs/_templates/tasks.md +39 -32
  743. package/specs/agent-identity-reputation/plan.md +133 -0
  744. package/specs/agent-identity-reputation/spec.md +125 -0
  745. package/specs/agent-identity-reputation/tasks.md +51 -0
  746. package/specs/agent-instructions-v4/plan.md +8 -0
  747. package/specs/agent-instructions-v4/spec.md +21 -0
  748. package/specs/agent-instructions-v4/tasks.md +12 -0
  749. package/specs/agent-runtime-monitoring/plan.md +78 -0
  750. package/specs/agent-runtime-monitoring/spec.md +92 -0
  751. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  752. package/specs/ai-code-provenance/plan.md +71 -0
  753. package/specs/ai-code-provenance/spec.md +97 -0
  754. package/specs/ai-code-provenance/tasks.md +39 -0
  755. package/specs/architecture-constitution/plan.md +110 -0
  756. package/specs/architecture-constitution/spec.md +114 -0
  757. package/specs/architecture-constitution/tasks.md +58 -0
  758. package/specs/change-risk-engine/plan.md +130 -0
  759. package/specs/change-risk-engine/spec.md +119 -0
  760. package/specs/change-risk-engine/tasks.md +72 -0
  761. package/specs/clean-arch-boilerplate/plan.md +137 -137
  762. package/specs/clean-arch-boilerplate/spec.md +121 -121
  763. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  764. package/specs/cli-first-operacao/plan.md +53 -53
  765. package/specs/cli-first-operacao/spec.md +53 -53
  766. package/specs/cli-first-operacao/tasks.md +53 -53
  767. package/specs/code-context/spec.md +56 -56
  768. package/specs/coerencia-do-sistema/plan.md +155 -155
  769. package/specs/coerencia-do-sistema/spec.md +123 -123
  770. package/specs/coerencia-do-sistema/tasks.md +115 -115
  771. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  772. package/specs/dev-token-assets-db/plan.md +71 -71
  773. package/specs/dev-token-assets-db/spec.md +58 -58
  774. package/specs/dev-token-assets-db/tasks.md +58 -58
  775. package/specs/doctor-do-nucleo/plan.md +165 -165
  776. package/specs/doctor-do-nucleo/spec.md +139 -139
  777. package/specs/doctor-do-nucleo/tasks.md +172 -172
  778. package/specs/drift-sentinel/spec.md +117 -0
  779. package/specs/engineer-facade-extension/plan.md +71 -0
  780. package/specs/engineer-facade-extension/spec.md +98 -0
  781. package/specs/engineer-facade-extension/tasks.md +36 -0
  782. package/specs/engineering-evidence-ledger/plan.md +121 -0
  783. package/specs/engineering-evidence-ledger/spec.md +90 -0
  784. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  785. package/specs/engineering-graph-extensions/plan.md +92 -0
  786. package/specs/engineering-graph-extensions/spec.md +101 -0
  787. package/specs/engineering-graph-extensions/tasks.md +60 -0
  788. package/specs/engineering-intelligence/spec.md +177 -0
  789. package/specs/forja-core/spec.md +71 -71
  790. package/specs/gates/spec.md +63 -63
  791. package/specs/governanca-visivel/plan.md +122 -122
  792. package/specs/governanca-visivel/spec.md +112 -112
  793. package/specs/governanca-visivel/tasks.md +60 -60
  794. package/specs/harness-codegraph/spec.md +71 -71
  795. package/specs/learning-loop-incidents/plan.md +59 -0
  796. package/specs/learning-loop-incidents/spec.md +93 -0
  797. package/specs/learning-loop-incidents/tasks.md +36 -0
  798. package/specs/llm-integration-v2/plan.md +55 -0
  799. package/specs/llm-integration-v2/spec.md +61 -0
  800. package/specs/llm-integration-v2/tasks.md +28 -0
  801. package/specs/llm-resume-validation/plan.md +50 -0
  802. package/specs/llm-resume-validation/spec.md +35 -0
  803. package/specs/llm-resume-validation/tasks.md +19 -0
  804. package/specs/memory-audit/spec.md +54 -54
  805. package/specs/orchestrate/spec.md +108 -108
  806. package/specs/orchestration-coherent/spec.md +95 -95
  807. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  808. package/specs/predictive-change-simulation/plan.md +109 -0
  809. package/specs/predictive-change-simulation/spec.md +107 -0
  810. package/specs/predictive-change-simulation/tasks.md +41 -0
  811. package/specs/project-smoke/spec.md +96 -96
  812. package/specs/project-upgrade/spec.md +58 -58
  813. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  814. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  815. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  816. package/specs/release-auditor-health/spec.md +23 -23
  817. package/specs/release-gate/plan.md +174 -174
  818. package/specs/release-gate/spec.md +122 -122
  819. package/specs/release-gate/tasks.md +183 -183
  820. package/specs/smart-agent-routing/plan.md +55 -0
  821. package/specs/smart-agent-routing/spec.md +85 -0
  822. package/specs/smart-agent-routing/tasks.md +26 -0
  823. package/specs/ts-migration/plan.md +200 -200
  824. package/specs/ts-migration/spec.md +119 -119
  825. package/specs/ts-migration/tasks.md +110 -110
@@ -1,174 +1,174 @@
1
- # Plan: release-gate
2
-
3
- - **Spec**: ./spec.md
4
- - **Status**: done
5
- - **Criado em**: 2026-07-14
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 runner já existe.** `runChecks({ checks, env })` em `lib/core/health.mjs` foi escrito genérico
12
- — recebe a lista de checks por parâmetro e já é exercitado com fixtures nos testes. O gate de
13
- release não precisa de máquina nova: precisa de **outro catálogo de checks** rodando na mesma
14
- máquina.
15
-
16
- Então extraímos o runner para `lib/core/checks.mjs` e deixamos dois catálogos: `health.mjs` (o
17
- núcleo, fronteira *repo*) e `release.mjs` (o tarball, fronteira *pacote publicado*). Mesma
18
- severidade, mesma cascata, mesmo contrato de `fix`. Uma máquina, duas fronteiras.
19
-
20
- A diferença essencial em relação ao doctor: o gate de release **não inspeciona; ele instala**. Grep
21
- não prova ausência — instalação prova. O `release-auditor` já diz isso, e é a razão de o gate ser
22
- lento e de tudo bem ser lento.
23
-
24
- ## 2. Módulos afetados
25
-
26
- | Caminho | Mudança | Risco |
27
- |---|---|---|
28
- | `lib/core/checks.mjs` | **criar** — runner extraído de `health.mjs` (`runChecks`, `worstStatus`) | M |
29
- | `lib/core/health.mjs` | editar — passa a importar o runner; re-exporta para não quebrar consumidores | M |
30
- | `lib/core/release.mjs` | **criar** — catálogo dos checks de tarball | M |
31
- | `scripts/release-check.mjs` | **criar** — apresentação + exit code | B |
32
- | `lib/core/registry.mjs` | editar — `release:check` (ADR-0020) | B |
33
- | `package.json` | editar — `prepublishOnly` | **A** |
34
- | `.github/workflows/ci.yml` | editar — steps `tools:doctor` e `release:check` | B |
35
- | `.claude/agents/release-auditor.md` | reescrever — consome o gate, não reimplementa | B |
36
- | `test/release.test.js` | **criar** — os três bugs históricos como fixture | B |
37
-
38
- Risco alto no `prepublishOnly`: se ele falhar indevidamente, **ninguém consegue publicar**. É o
39
- único ponto onde um falso positivo trava a operação inteira em vez de só incomodar.
40
-
41
- ## 3. Diagrama de fluxo
42
-
43
- ```
44
- npm run release:check [--publish]
45
- │
46
- ▼
47
- ┌─ preflight ───────────────────────────────────────┐
48
- │ árvore limpa? --publish → fail senão → warn │ ← v1.1.1 morreu aqui
49
- └───────────────────────────────────────────────────┘
50
- │
51
- ▼
52
- npm pack → /tmp/forja-release-<pid>/
53
- │
54
- ▼
55
- npm init + npm i <tgz> (isolado: sem NODE_PATH, sem node_modules do repo)
56
- │
57
- ▼
58
- ┌──────────── RELEASE_CHECKS[] (lib/core/release.mjs) ──────────┐
59
- │ id severity o que prova │
60
- │ tree-clean critical* tarball == commit (*warn sem --publish)
61
- │ install critical o pacote instala do zero │
62
- │ registry-scripts critical os 41 comandos existem no tarball │
63
- │ smoke-commands critical os comandos EXECUTAM (não só help) │
64
- │ reprova por stderr, não exit code │
65
- │ deps-declared critical importado ⊆ dependencies │
66
- │ deps-unused warn dependency que ninguém importa │
67
- │ imports-resolve critical import relativo resolve no tarball │
68
- └───────────────────────────────────────────────────────────────┘
69
- │
70
- ▼
71
- re-check árvore limpa ← a aprovação é perecível
72
- │
73
- ▼
74
- exit 0 / exit 1 + limpa o /tmp
75
- ```
76
-
77
- ## 4. Contratos (API/CLI/Schema)
78
-
79
- ```js
80
- // lib/core/checks.mjs — o runner, sem opinião sobre o que checa
81
- export async function runChecks(opts); // { checks, scope, env } -> Result[]
82
- export function worstStatus(results); // -> 'ok' | 'warn' | 'fail'
83
-
84
- // lib/core/health.mjs — inalterado para quem consome
85
- export { runChecks, worstStatus } from './checks.mjs'; // re-export: tools-doctor e o hook seguem iguais
86
- export const CHECKS; // os 7 do núcleo
87
-
88
- // lib/core/release.mjs
89
- export const RELEASE_CHECKS;
90
- export async function withCleanInstall(fn); // empacota, instala isolado, executa, limpa. Sempre limpa.
91
- ```
92
-
93
- **CLI**:
94
-
95
- | Comando | Árvore suja | Uso |
96
- |---|---|---|
97
- | `npm run release:check` | `warn` | Dev quer o smoke test sem commitar. Reprova o resto normalmente. |
98
- | `npm run release:check -- --publish` | **`fail`** | `prepublishOnly` e CI de release. |
99
-
100
- A distinção existe porque um gate que reprova todo desenvolvimento local vira um gate que se
101
- contorna — a lição que o CI nos deu na SPEC-009, quando `memory-db` reprovava qualquer clone novo.
102
- Mas na hora de publicar, árvore suja é **fatal**: foi assim que `otplib` e `qrcode` entraram na
103
- v1.1.1 sem existirem no git.
104
-
105
- ## 5. Decisões e alternativas
106
-
107
- **D1: Extrair o runner em vez de duplicá-lo.** `health.mjs` já tem cascata, blindagem de probe e
108
- `worstStatus` testados. Copiar tudo para `release.mjs` criaria duas máquinas que divergem com o
109
- tempo — exatamente o defeito que a SPEC-009 matou quando o doctor e o hook divergiram. Alternativa
110
- rejeitada: `release.mjs` importar de `health.mjs`, deixando o núcleo dono de um runner que não é
111
- dele.
112
-
113
- **D2: Instalar, não inspecionar.** O gate faz `npm pack` + `npm i` de verdade. Alternativa
114
- rejeitada: análise estática do tarball — foi o que eu fiz à mão hoje e produziu **falso positivo
115
- imediato** (os geradores contêm `import` dentro de template string). Grep não prova ausência.
116
-
117
- **D3: Template literals são removidos antes do parse.** Onde a análise estática for inevitável
118
- (`deps-declared`), o conteúdo entre crases é apagado do fonte antes de casar `import`. Os geradores
119
- *escrevem* código NestJS; não o executam. Sem isso, o check acusa `@nestjs/core` como dependência
120
- não declarada — e é o bug latente que já existe hoje no `runtime-deps` (AC-11).
121
-
122
- **D4: Dois modos (`--publish`).** Ver §4. Severidade do `tree-clean` muda com o contexto; o resto
123
- é idêntico.
124
-
125
- **D5: A aprovação é perecível.** O `git status` é reconferido **ao final**, porque a auditoria vale
126
- para o disco no instante em que rodou. Um `npm install` entre o check e o publish invalida tudo — e
127
- essa foi literalmente a causa da v1.1.1.
128
-
129
- **D6: O gate nunca publica.** Ele autoriza. `npm publish` continua sendo um ato humano deliberado.
130
-
131
- **D7: `deps-unused` é `warn`, não `fail`.** Peso morto no tarball incomoda, não quebra. Reprovar um
132
- release por causa disso é o tipo de rigor que ensina o time a usar `--no-verify`.
133
-
134
- **D8: `smoke-commands` reprova por padrão no stderr, nunca por exit code.** Numa instalação limpa
135
- não existe workspace nem `universal.db` — então `query:universal` sai com código ≠ 0 *legitimamente*,
136
- e `tools:doctor` avisa sobre memória não indexada. Isso é o pacote **funcionando**. O que denuncia
137
- tarball quebrado é a assinatura do carregamento: `ERR_MODULE_NOT_FOUND`, `ERR_DLOPEN_FAILED`,
138
- `Cannot find module`. Reprovar por exit code faria o gate reprovar um pacote saudável — é a mesma
139
- armadilha do `memory-db` na SPEC-009, um nível acima.
140
-
141
- **D9: `prepublishOnly`, nunca `prepack`.** O gate roda `npm pack`. Amarrá-lo ao `prepack` faria o
142
- `npm pack` do gate disparar o `prepack`, que chama o gate, que roda `npm pack`… `npm pack` **não**
143
- dispara `prepublishOnly`, então o hook correto é o único seguro. Vale um comentário no
144
- `package.json`: a alternativa "óbvia" é uma bomba-relógio.
145
-
146
- D1 e a mudança de contrato do `prepublishOnly` são estruturais → **ADR-0024**, referenciando
147
- ADR-0023 (mesma filosofia, fronteira seguinte) e ADR-0021 (a classe que ambos fecham).
148
-
149
- ## 6. Dependências
150
-
151
- - **Specs**: SPEC-009 (`lib/core/health.mjs` é a base do runner). Já em `done`.
152
- - **Pacotes npm**: **nenhum novo.** `npm pack`/`npm i` via `child_process`.
153
- - **Migrações**: nenhuma.
154
-
155
- ## 7. Rollout
156
-
157
- - [ ] **Ordem**: `checks.mjs` extraído + suíte verde (refactor puro, nada muda de comportamento) →
158
- `release.mjs` + testes → `release-check.mjs` → CI → `prepublishOnly` **por último**.
159
- - [x] Doc/persona impactada: `docs/publishing.md`, `CLAUDE.md`, persona **governança**.
160
- - [ ] **Validar reintroduzindo os três bugs históricos** (better-sqlite3 em devDeps; arquivo fora do
161
- `files[]`; árvore suja). Cada um deve reprovar. Um gate que nunca viu a falha que promete
162
- pegar não está testado — está escrito.
163
- - [ ] `prepublishOnly` entra **depois** de o gate rodar verde no CI por um ciclo. Ele é a única
164
- peça que, com falso positivo, impede publicar qualquer coisa.
165
-
166
- ## 8. Sinais de fracasso (kill criteria)
167
-
168
- - **O gate reprova um release saudável.** Um falso positivo no `prepublishOnly` trava a operação
169
- inteira. Se acontecer uma vez, o `tree-clean` estrito sai do `prepublishOnly` e fica só no CI.
170
- - **`deps-declared` volta a acusar os geradores.** Se o D3 não bastar, o check é rebaixado a `warn`
171
- e a cobertura passa a vir do `smoke-commands` (que executa e não mente).
172
- - **O gate leva minutos.** O custo real não é o `npm pack` — é o `npm i` compilando o
173
- `better-sqlite3` do zero (o CI já gasta ~1min45 nisso). Se ficar caro demais, o gate sai do fluxo
174
- de PR e fica só no release: a instalação limpa é inegociável, a frequência não.
1
+ # Plan: release-gate
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: done
5
+ - **Criado em**: 2026-07-14
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 runner já existe.** `runChecks({ checks, env })` em `lib/core/health.mjs` foi escrito genérico
12
+ — recebe a lista de checks por parâmetro e já é exercitado com fixtures nos testes. O gate de
13
+ release não precisa de máquina nova: precisa de **outro catálogo de checks** rodando na mesma
14
+ máquina.
15
+
16
+ Então extraímos o runner para `lib/core/checks.mjs` e deixamos dois catálogos: `health.mjs` (o
17
+ núcleo, fronteira *repo*) e `release.mjs` (o tarball, fronteira *pacote publicado*). Mesma
18
+ severidade, mesma cascata, mesmo contrato de `fix`. Uma máquina, duas fronteiras.
19
+
20
+ A diferença essencial em relação ao doctor: o gate de release **não inspeciona; ele instala**. Grep
21
+ não prova ausência — instalação prova. O `release-auditor` já diz isso, e é a razão de o gate ser
22
+ lento e de tudo bem ser lento.
23
+
24
+ ## 2. Módulos afetados
25
+
26
+ | Caminho | Mudança | Risco |
27
+ |---|---|---|
28
+ | `lib/core/checks.mjs` | **criar** — runner extraído de `health.mjs` (`runChecks`, `worstStatus`) | M |
29
+ | `lib/core/health.mjs` | editar — passa a importar o runner; re-exporta para não quebrar consumidores | M |
30
+ | `lib/core/release.mjs` | **criar** — catálogo dos checks de tarball | M |
31
+ | `scripts/release-check.mjs` | **criar** — apresentação + exit code | B |
32
+ | `lib/core/registry.mjs` | editar — `release:check` (ADR-0020) | B |
33
+ | `package.json` | editar — `prepublishOnly` | **A** |
34
+ | `.github/workflows/ci.yml` | editar — steps `tools:doctor` e `release:check` | B |
35
+ | `.claude/agents/release-auditor.md` | reescrever — consome o gate, não reimplementa | B |
36
+ | `test/release.test.js` | **criar** — os três bugs históricos como fixture | B |
37
+
38
+ Risco alto no `prepublishOnly`: se ele falhar indevidamente, **ninguém consegue publicar**. É o
39
+ único ponto onde um falso positivo trava a operação inteira em vez de só incomodar.
40
+
41
+ ## 3. Diagrama de fluxo
42
+
43
+ ```
44
+ npm run release:check [--publish]
45
+ │
46
+ ▼
47
+ ┌─ preflight ───────────────────────────────────────┐
48
+ │ árvore limpa? --publish → fail senão → warn │ ← v1.1.1 morreu aqui
49
+ └───────────────────────────────────────────────────┘
50
+ │
51
+ ▼
52
+ npm pack → /tmp/forja-release-<pid>/
53
+ │
54
+ ▼
55
+ npm init + npm i <tgz> (isolado: sem NODE_PATH, sem node_modules do repo)
56
+ │
57
+ ▼
58
+ ┌──────────── RELEASE_CHECKS[] (lib/core/release.mjs) ──────────┐
59
+ │ id severity o que prova │
60
+ │ tree-clean critical* tarball == commit (*warn sem --publish)
61
+ │ install critical o pacote instala do zero │
62
+ │ registry-scripts critical os 41 comandos existem no tarball │
63
+ │ smoke-commands critical os comandos EXECUTAM (não só help) │
64
+ │ reprova por stderr, não exit code │
65
+ │ deps-declared critical importado ⊆ dependencies │
66
+ │ deps-unused warn dependency que ninguém importa │
67
+ │ imports-resolve critical import relativo resolve no tarball │
68
+ └───────────────────────────────────────────────────────────────┘
69
+ │
70
+ ▼
71
+ re-check árvore limpa ← a aprovação é perecível
72
+ │
73
+ ▼
74
+ exit 0 / exit 1 + limpa o /tmp
75
+ ```
76
+
77
+ ## 4. Contratos (API/CLI/Schema)
78
+
79
+ ```js
80
+ // lib/core/checks.mjs — o runner, sem opinião sobre o que checa
81
+ export async function runChecks(opts); // { checks, scope, env } -> Result[]
82
+ export function worstStatus(results); // -> 'ok' | 'warn' | 'fail'
83
+
84
+ // lib/core/health.mjs — inalterado para quem consome
85
+ export { runChecks, worstStatus } from './checks.mjs'; // re-export: tools-doctor e o hook seguem iguais
86
+ export const CHECKS; // os 7 do núcleo
87
+
88
+ // lib/core/release.mjs
89
+ export const RELEASE_CHECKS;
90
+ export async function withCleanInstall(fn); // empacota, instala isolado, executa, limpa. Sempre limpa.
91
+ ```
92
+
93
+ **CLI**:
94
+
95
+ | Comando | Árvore suja | Uso |
96
+ |---|---|---|
97
+ | `npm run release:check` | `warn` | Dev quer o smoke test sem commitar. Reprova o resto normalmente. |
98
+ | `npm run release:check -- --publish` | **`fail`** | `prepublishOnly` e CI de release. |
99
+
100
+ A distinção existe porque um gate que reprova todo desenvolvimento local vira um gate que se
101
+ contorna — a lição que o CI nos deu na SPEC-009, quando `memory-db` reprovava qualquer clone novo.
102
+ Mas na hora de publicar, árvore suja é **fatal**: foi assim que `otplib` e `qrcode` entraram na
103
+ v1.1.1 sem existirem no git.
104
+
105
+ ## 5. Decisões e alternativas
106
+
107
+ **D1: Extrair o runner em vez de duplicá-lo.** `health.mjs` já tem cascata, blindagem de probe e
108
+ `worstStatus` testados. Copiar tudo para `release.mjs` criaria duas máquinas que divergem com o
109
+ tempo — exatamente o defeito que a SPEC-009 matou quando o doctor e o hook divergiram. Alternativa
110
+ rejeitada: `release.mjs` importar de `health.mjs`, deixando o núcleo dono de um runner que não é
111
+ dele.
112
+
113
+ **D2: Instalar, não inspecionar.** O gate faz `npm pack` + `npm i` de verdade. Alternativa
114
+ rejeitada: análise estática do tarball — foi o que eu fiz à mão hoje e produziu **falso positivo
115
+ imediato** (os geradores contêm `import` dentro de template string). Grep não prova ausência.
116
+
117
+ **D3: Template literals são removidos antes do parse.** Onde a análise estática for inevitável
118
+ (`deps-declared`), o conteúdo entre crases é apagado do fonte antes de casar `import`. Os geradores
119
+ *escrevem* código NestJS; não o executam. Sem isso, o check acusa `@nestjs/core` como dependência
120
+ não declarada — e é o bug latente que já existe hoje no `runtime-deps` (AC-11).
121
+
122
+ **D4: Dois modos (`--publish`).** Ver §4. Severidade do `tree-clean` muda com o contexto; o resto
123
+ é idêntico.
124
+
125
+ **D5: A aprovação é perecível.** O `git status` é reconferido **ao final**, porque a auditoria vale
126
+ para o disco no instante em que rodou. Um `npm install` entre o check e o publish invalida tudo — e
127
+ essa foi literalmente a causa da v1.1.1.
128
+
129
+ **D6: O gate nunca publica.** Ele autoriza. `npm publish` continua sendo um ato humano deliberado.
130
+
131
+ **D7: `deps-unused` é `warn`, não `fail`.** Peso morto no tarball incomoda, não quebra. Reprovar um
132
+ release por causa disso é o tipo de rigor que ensina o time a usar `--no-verify`.
133
+
134
+ **D8: `smoke-commands` reprova por padrão no stderr, nunca por exit code.** Numa instalação limpa
135
+ não existe workspace nem `universal.db` — então `query:universal` sai com código ≠ 0 *legitimamente*,
136
+ e `tools:doctor` avisa sobre memória não indexada. Isso é o pacote **funcionando**. O que denuncia
137
+ tarball quebrado é a assinatura do carregamento: `ERR_MODULE_NOT_FOUND`, `ERR_DLOPEN_FAILED`,
138
+ `Cannot find module`. Reprovar por exit code faria o gate reprovar um pacote saudável — é a mesma
139
+ armadilha do `memory-db` na SPEC-009, um nível acima.
140
+
141
+ **D9: `prepublishOnly`, nunca `prepack`.** O gate roda `npm pack`. Amarrá-lo ao `prepack` faria o
142
+ `npm pack` do gate disparar o `prepack`, que chama o gate, que roda `npm pack`… `npm pack` **não**
143
+ dispara `prepublishOnly`, então o hook correto é o único seguro. Vale um comentário no
144
+ `package.json`: a alternativa "óbvia" é uma bomba-relógio.
145
+
146
+ D1 e a mudança de contrato do `prepublishOnly` são estruturais → **ADR-0024**, referenciando
147
+ ADR-0023 (mesma filosofia, fronteira seguinte) e ADR-0021 (a classe que ambos fecham).
148
+
149
+ ## 6. Dependências
150
+
151
+ - **Specs**: SPEC-009 (`lib/core/health.mjs` é a base do runner). Já em `done`.
152
+ - **Pacotes npm**: **nenhum novo.** `npm pack`/`npm i` via `child_process`.
153
+ - **Migrações**: nenhuma.
154
+
155
+ ## 7. Rollout
156
+
157
+ - [ ] **Ordem**: `checks.mjs` extraído + suíte verde (refactor puro, nada muda de comportamento) →
158
+ `release.mjs` + testes → `release-check.mjs` → CI → `prepublishOnly` **por último**.
159
+ - [x] Doc/persona impactada: `docs/publishing.md`, `CLAUDE.md`, persona **governança**.
160
+ - [ ] **Validar reintroduzindo os três bugs históricos** (better-sqlite3 em devDeps; arquivo fora do
161
+ `files[]`; árvore suja). Cada um deve reprovar. Um gate que nunca viu a falha que promete
162
+ pegar não está testado — está escrito.
163
+ - [ ] `prepublishOnly` entra **depois** de o gate rodar verde no CI por um ciclo. Ele é a única
164
+ peça que, com falso positivo, impede publicar qualquer coisa.
165
+
166
+ ## 8. Sinais de fracasso (kill criteria)
167
+
168
+ - **O gate reprova um release saudável.** Um falso positivo no `prepublishOnly` trava a operação
169
+ inteira. Se acontecer uma vez, o `tree-clean` estrito sai do `prepublishOnly` e fica só no CI.
170
+ - **`deps-declared` volta a acusar os geradores.** Se o D3 não bastar, o check é rebaixado a `warn`
171
+ e a cobertura passa a vir do `smoke-commands` (que executa e não mente).
172
+ - **O gate leva minutos.** O custo real não é o `npm pack` — é o `npm i` compilando o
173
+ `better-sqlite3` do zero (o CI já gasta ~1min45 nisso). Se ficar caro demais, o gate sai do fluxo
174
+ de PR e fica só no release: a instalação limpa é inegociável, a frequência não.
@@ -1,122 +1,122 @@
1
- # Spec: release-gate
2
-
3
- - **ID**: SPEC-010
4
- - **Status**: done
5
- - **Owner**: apk
6
- - **Criado em**: 2026-07-13
7
- - **Sprint alvo**: S?
8
- - **ADRs relacionadas**: [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (doctor como gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails de harness), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry), [ADR-0018](../../memory/90-decisions/0018-ferramentas-de-processo.md) (ferramentas de processo)
9
-
10
- ## 1. Problema
11
-
12
- **O repositório mente sobre o pacote.** No repo tudo resolve: `node_modules` tem as devDeps, todo
13
- arquivo está presente, o `cwd` é a raiz. Nada disso vale para quem roda `npm i -g forjajs`. Entre o
14
- repo e o tarball existe uma fronteira que nenhum teste atravessa — e ela já cedeu **três vezes**:
15
-
16
- | Versão | O que foi publicado | Consequência |
17
- |---|---|---|
18
- | ADR-0021 §2 | `better-sqlite3` como `devDependency` | Dez comandos estouravam com `ERR_MODULE_NOT_FOUND` numa instalação limpa. O `forja` sem argumentos funcionava — o help não carrega os scripts — o que mascarava a quebra. |
19
- | v1.1.1 | `otplib` e `qrcode` no tarball, **sem jamais existirem no git** | `npm publish` empacota o *disco*, não o commit. Um `npm install` casual entre a auditoria e o publish reescreveu o `package.json`. |
20
- | v1.1.3 | `docs/dashboard.md` e o script `npm run dashboard`, sem a pasta `dashboard/` | Quem instalava recebia a documentação e o comando, sem o código. |
21
-
22
- Três ocorrências, uma classe: **o que é publicado não é o que o repositório promete.** Todas
23
- descobertas *depois* do publish, na máquina de quem instalou.
24
-
25
- O agente `.claude/agents/release-auditor.md` descreve essa classe com precisão cirúrgica — as
26
- quatro variantes, o procedimento, os comandos. Mas ele é **um agente**: prosa, opt-in, invocado por
27
- quem lembrar. Pelo critério do próprio ADR-0021 — *"uma regra que depende de memória não é uma
28
- regra; é uma sugestão"* — isto não é gate. É a última fronteira do framework que ainda funciona por
29
- disciplina em vez de por harness.
30
-
31
- Não é conhecimento que falta. É **execução**.
32
-
33
- ## 2. Proposta de valor
34
-
35
- Publicar deixa de ser um ato de fé: **nenhuma versão sai sem prova de que uma instalação limpa
36
- funciona**, e a prova é gerada pelo harness, não pela lembrança de quem publica.
37
-
38
- ## 3. User stories
39
-
40
- - **Como** quem publica, **quero** que o `npm publish` seja **bloqueado** quando o tarball está
41
- quebrado, **para que** eu não descubra pela issue de um usuário.
42
- - **Como** quem publica, **quero** que árvore suja reprove antes de qualquer outra checagem,
43
- **para que** não se repita a v1.1.1 — auditar um tarball que não é o que será publicado é
44
- auditar ficção.
45
- - **Como** usuário do `forjajs`, **quero** que todo comando anunciado exista de verdade no pacote,
46
- **para que** `npm i -g forjajs` não me entregue documentação sem código.
47
- - **Como** governança, **quero** a evidência da instalação limpa **no log do CI**, **para que**
48
- "testado" seja um artefato verificável e não uma afirmação.
49
-
50
- ## 4. Critérios de aceite (Definition of Done)
51
-
52
- - [ ] AC-1: Existe `npm run release:check` (entrada no registry, ADR-0020) que empacota, instala num
53
- diretório temporário isolado e **reprova com exit ≠ 0** em qualquer uma das falhas abaixo.
54
- - [ ] AC-2: **Árvore limpa é pré-condição.** Qualquer saída de `git status --short` reprova
55
- imediatamente, antes de empacotar. Foi a falha da v1.1.1, e nenhuma instalação a pega.
56
- - [ ] AC-3: **Instalação limpa real**: `npm pack` → `npm i <tgz>` fora do repo, sem devDeps.
57
- - [ ] AC-4: **Comandos são executados, não listados.** O `forja` sem argumentos passa mesmo com tudo
58
- quebrado (o help não carrega os scripts). O gate roda os comandos sem efeito colateral
59
- (`tools:doctor`, `code:status`, `query:universal`, help) e reprova em `ERR_MODULE_NOT_FOUND`.
60
- - [ ] AC-5: **Todo comando do registry tem seu script no tarball.** Hoje são 41/41 — o gate torna
61
- isso permanente, em vez de verdade acidental.
62
- - [ ] AC-6: **Fronteira deps/devDeps nos dois sentidos**: todo pacote importado por código sob
63
- `files[]` está em `dependencies`; e toda `dependency` declarada é importada por alguém — peso
64
- morto viaja no tarball de todo usuário.
65
- - [ ] AC-7: **Imports em template literal não contam.** Os geradores contêm código NestJS que eles
66
- *escrevem*, não que *executam*. Contá-los produz falso positivo.
67
- - [ ] AC-8: `release:check` roda como **`prepublishOnly`** e como **step do CI**. Um gate que só roda
68
- quando alguém lembra é o problema, não a solução.
69
- - [ ] AC-9: `tools:doctor` também vira step do CI — o gate do ADR-0023 existe e hoje nada o executa
70
- automaticamente.
71
- - [ ] AC-10: O agente `release-auditor` passa a **consumir o gate**, em vez de manter procedimento
72
- próprio em prosa. Deixa de ser a fonte da verdade e passa a interpretá-la.
73
- - [ ] AC-11: `runtime-deps` (ADR-0023) endurecido contra o falso positivo do AC-7. Hoje ele passa
74
- **por sorte**: `@nestjs/*` não está nas devDeps. No dia em que estiver, ele trava o gate.
75
- - [ ] AC-12: Testes cobrindo cada reprovação com tarball de fixture deliberadamente quebrado.
76
-
77
- ## 5. Escopo
78
-
79
- **Dentro**:
80
- - `lib/core/release.mjs` — as checagens como dados, no mesmo formato de `lib/core/health.mjs`
81
- (`{ id, severity, probe, fix }`). Mesma filosofia, fronteira diferente.
82
- - `scripts/release-check.mjs` — superfície de apresentação + exit code.
83
- - `package.json` (`prepublishOnly`) e `.github/workflows/` (steps de `release:check` e `tools:doctor`).
84
- - `lib/core/health.mjs` — endurecer `runtime-deps` (AC-11).
85
- - `.claude/agents/release-auditor.md` — reescrito para consumir o gate.
86
-
87
- **Fora** (explícito):
88
- - **Publicar automaticamente.** O gate autoriza; quem publica é humano. Automatizar o `npm publish`
89
- é a classe de risco oposta à que esta spec fecha.
90
- - Mudar o conteúdo de `files[]` — o gate *verifica* o que está lá; não decide o que deveria estar.
91
- - Assinatura/proveniência de pacote (npm provenance) — vale a pena, mas é outra spec.
92
- - Testar os projetos **gerados** pelos boilerplates. É uma fronteira real e descoberta, mas grande
93
- demais para entrar aqui de carona.
94
-
95
- ## 6. NFRs / restrições
96
-
97
- - **Honestidade acima de velocidade**: o gate instala de verdade. Vai levar dezenas de segundos, e
98
- tudo bem — roda antes de publicar e no CI, não a cada commit.
99
- - **Isolamento**: a instalação acontece fora do repo, em diretório temporário, sem herdar
100
- `node_modules` nem `NODE_PATH`. Um gate que enxerga o repo não prova nada.
101
- - **Zero falso positivo crítico**: melhor deixar passar um caso duvidoso do que reprovar um release
102
- saudável. Análise estática ambígua vira `warn`, nunca `fail`.
103
- - **Compatibilidade**: não altera nenhum comando existente. `release:check` é aditivo.
104
-
105
- ## 7. Riscos e mitigação
106
-
107
- | Risco | Probabilidade | Impacto | Mitigação |
108
- |---|---|---|---|
109
- | Gate lento e as pessoas o contornam | M | A | Só em `prepublishOnly` e CI; nunca no pre-commit |
110
- | Falso positivo por template literal nos geradores | **A** | A | AC-7 e AC-11; ambíguo vira `warn`. **Já observado em campo** |
111
- | Instalação "vaza" para o repo (cache, `NODE_PATH`) e o gate mente verde | M | A | Diretório temporário + `npm init` próprio; teste que injeta tarball quebrado e **exige** reprovação |
112
- | `prepublishOnly` não roda em todos os fluxos de publish | B | A | Duplicado como step de CI — duas portas, não uma |
113
- | Escopo escorrega para "testar os projetos gerados" | M | M | Explicitamente fora |
114
-
115
- ## 8. Métricas de sucesso
116
-
117
- - **Zero** bugs da classe "publicado ≠ repositório" nos 90 dias após a 1.1.4. Foram três em três
118
- releases; a régua é chegar a zero — e provar.
119
- - A evidência da instalação limpa passa a existir **no log do CI de cada release**, em vez de na
120
- memória de quem publicou.
121
- - Os três bugs históricos viram fixture: cada um, reintroduzido, **reprova** o gate. Um gate que
122
- nunca viu a falha que promete pegar não está testado — está escrito.
1
+ # Spec: release-gate
2
+
3
+ - **ID**: SPEC-010
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-13
7
+ - **Sprint alvo**: S?
8
+ - **ADRs relacionadas**: [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (doctor como gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails de harness), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry), [ADR-0018](../../memory/90-decisions/0018-ferramentas-de-processo.md) (ferramentas de processo)
9
+
10
+ ## 1. Problema
11
+
12
+ **O repositório mente sobre o pacote.** No repo tudo resolve: `node_modules` tem as devDeps, todo
13
+ arquivo está presente, o `cwd` é a raiz. Nada disso vale para quem roda `npm i -g forjajs`. Entre o
14
+ repo e o tarball existe uma fronteira que nenhum teste atravessa — e ela já cedeu **três vezes**:
15
+
16
+ | Versão | O que foi publicado | Consequência |
17
+ |---|---|---|
18
+ | ADR-0021 §2 | `better-sqlite3` como `devDependency` | Dez comandos estouravam com `ERR_MODULE_NOT_FOUND` numa instalação limpa. O `forja` sem argumentos funcionava — o help não carrega os scripts — o que mascarava a quebra. |
19
+ | v1.1.1 | `otplib` e `qrcode` no tarball, **sem jamais existirem no git** | `npm publish` empacota o *disco*, não o commit. Um `npm install` casual entre a auditoria e o publish reescreveu o `package.json`. |
20
+ | v1.1.3 | `docs/dashboard.md` e o script `npm run dashboard`, sem a pasta `dashboard/` | Quem instalava recebia a documentação e o comando, sem o código. |
21
+
22
+ Três ocorrências, uma classe: **o que é publicado não é o que o repositório promete.** Todas
23
+ descobertas *depois* do publish, na máquina de quem instalou.
24
+
25
+ O agente `.claude/agents/release-auditor.md` descreve essa classe com precisão cirúrgica — as
26
+ quatro variantes, o procedimento, os comandos. Mas ele é **um agente**: prosa, opt-in, invocado por
27
+ quem lembrar. Pelo critério do próprio ADR-0021 — *"uma regra que depende de memória não é uma
28
+ regra; é uma sugestão"* — isto não é gate. É a última fronteira do framework que ainda funciona por
29
+ disciplina em vez de por harness.
30
+
31
+ Não é conhecimento que falta. É **execução**.
32
+
33
+ ## 2. Proposta de valor
34
+
35
+ Publicar deixa de ser um ato de fé: **nenhuma versão sai sem prova de que uma instalação limpa
36
+ funciona**, e a prova é gerada pelo harness, não pela lembrança de quem publica.
37
+
38
+ ## 3. User stories
39
+
40
+ - **Como** quem publica, **quero** que o `npm publish` seja **bloqueado** quando o tarball está
41
+ quebrado, **para que** eu não descubra pela issue de um usuário.
42
+ - **Como** quem publica, **quero** que árvore suja reprove antes de qualquer outra checagem,
43
+ **para que** não se repita a v1.1.1 — auditar um tarball que não é o que será publicado é
44
+ auditar ficção.
45
+ - **Como** usuário do `forjajs`, **quero** que todo comando anunciado exista de verdade no pacote,
46
+ **para que** `npm i -g forjajs` não me entregue documentação sem código.
47
+ - **Como** governança, **quero** a evidência da instalação limpa **no log do CI**, **para que**
48
+ "testado" seja um artefato verificável e não uma afirmação.
49
+
50
+ ## 4. Critérios de aceite (Definition of Done)
51
+
52
+ - [ ] AC-1: Existe `npm run release:check` (entrada no registry, ADR-0020) que empacota, instala num
53
+ diretório temporário isolado e **reprova com exit ≠ 0** em qualquer uma das falhas abaixo.
54
+ - [ ] AC-2: **Árvore limpa é pré-condição.** Qualquer saída de `git status --short` reprova
55
+ imediatamente, antes de empacotar. Foi a falha da v1.1.1, e nenhuma instalação a pega.
56
+ - [ ] AC-3: **Instalação limpa real**: `npm pack` → `npm i <tgz>` fora do repo, sem devDeps.
57
+ - [ ] AC-4: **Comandos são executados, não listados.** O `forja` sem argumentos passa mesmo com tudo
58
+ quebrado (o help não carrega os scripts). O gate roda os comandos sem efeito colateral
59
+ (`tools:doctor`, `code:status`, `query:universal`, help) e reprova em `ERR_MODULE_NOT_FOUND`.
60
+ - [ ] AC-5: **Todo comando do registry tem seu script no tarball.** Hoje são 41/41 — o gate torna
61
+ isso permanente, em vez de verdade acidental.
62
+ - [ ] AC-6: **Fronteira deps/devDeps nos dois sentidos**: todo pacote importado por código sob
63
+ `files[]` está em `dependencies`; e toda `dependency` declarada é importada por alguém — peso
64
+ morto viaja no tarball de todo usuário.
65
+ - [ ] AC-7: **Imports em template literal não contam.** Os geradores contêm código NestJS que eles
66
+ *escrevem*, não que *executam*. Contá-los produz falso positivo.
67
+ - [ ] AC-8: `release:check` roda como **`prepublishOnly`** e como **step do CI**. Um gate que só roda
68
+ quando alguém lembra é o problema, não a solução.
69
+ - [ ] AC-9: `tools:doctor` também vira step do CI — o gate do ADR-0023 existe e hoje nada o executa
70
+ automaticamente.
71
+ - [ ] AC-10: O agente `release-auditor` passa a **consumir o gate**, em vez de manter procedimento
72
+ próprio em prosa. Deixa de ser a fonte da verdade e passa a interpretá-la.
73
+ - [ ] AC-11: `runtime-deps` (ADR-0023) endurecido contra o falso positivo do AC-7. Hoje ele passa
74
+ **por sorte**: `@nestjs/*` não está nas devDeps. No dia em que estiver, ele trava o gate.
75
+ - [ ] AC-12: Testes cobrindo cada reprovação com tarball de fixture deliberadamente quebrado.
76
+
77
+ ## 5. Escopo
78
+
79
+ **Dentro**:
80
+ - `lib/core/release.mjs` — as checagens como dados, no mesmo formato de `lib/core/health.mjs`
81
+ (`{ id, severity, probe, fix }`). Mesma filosofia, fronteira diferente.
82
+ - `scripts/release-check.mjs` — superfície de apresentação + exit code.
83
+ - `package.json` (`prepublishOnly`) e `.github/workflows/` (steps de `release:check` e `tools:doctor`).
84
+ - `lib/core/health.mjs` — endurecer `runtime-deps` (AC-11).
85
+ - `.claude/agents/release-auditor.md` — reescrito para consumir o gate.
86
+
87
+ **Fora** (explícito):
88
+ - **Publicar automaticamente.** O gate autoriza; quem publica é humano. Automatizar o `npm publish`
89
+ é a classe de risco oposta à que esta spec fecha.
90
+ - Mudar o conteúdo de `files[]` — o gate *verifica* o que está lá; não decide o que deveria estar.
91
+ - Assinatura/proveniência de pacote (npm provenance) — vale a pena, mas é outra spec.
92
+ - Testar os projetos **gerados** pelos boilerplates. É uma fronteira real e descoberta, mas grande
93
+ demais para entrar aqui de carona.
94
+
95
+ ## 6. NFRs / restrições
96
+
97
+ - **Honestidade acima de velocidade**: o gate instala de verdade. Vai levar dezenas de segundos, e
98
+ tudo bem — roda antes de publicar e no CI, não a cada commit.
99
+ - **Isolamento**: a instalação acontece fora do repo, em diretório temporário, sem herdar
100
+ `node_modules` nem `NODE_PATH`. Um gate que enxerga o repo não prova nada.
101
+ - **Zero falso positivo crítico**: melhor deixar passar um caso duvidoso do que reprovar um release
102
+ saudável. Análise estática ambígua vira `warn`, nunca `fail`.
103
+ - **Compatibilidade**: não altera nenhum comando existente. `release:check` é aditivo.
104
+
105
+ ## 7. Riscos e mitigação
106
+
107
+ | Risco | Probabilidade | Impacto | Mitigação |
108
+ |---|---|---|---|
109
+ | Gate lento e as pessoas o contornam | M | A | Só em `prepublishOnly` e CI; nunca no pre-commit |
110
+ | Falso positivo por template literal nos geradores | **A** | A | AC-7 e AC-11; ambíguo vira `warn`. **Já observado em campo** |
111
+ | Instalação "vaza" para o repo (cache, `NODE_PATH`) e o gate mente verde | M | A | Diretório temporário + `npm init` próprio; teste que injeta tarball quebrado e **exige** reprovação |
112
+ | `prepublishOnly` não roda em todos os fluxos de publish | B | A | Duplicado como step de CI — duas portas, não uma |
113
+ | Escopo escorrega para "testar os projetos gerados" | M | M | Explicitamente fora |
114
+
115
+ ## 8. Métricas de sucesso
116
+
117
+ - **Zero** bugs da classe "publicado ≠ repositório" nos 90 dias após a 1.1.4. Foram três em três
118
+ releases; a régua é chegar a zero — e provar.
119
+ - A evidência da instalação limpa passa a existir **no log do CI de cada release**, em vez de na
120
+ memória de quem publicou.
121
+ - Os três bugs históricos viram fixture: cada um, reintroduzido, **reprova** o gate. Um gate que
122
+ nunca viu a falha que promete pegar não está testado — está escrito.