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,61 +1,61 @@
1
- # Spec: pipeline-sdd-e-orquestracao
2
-
3
- - **ID**: SPEC-001
4
- - **Status**: done
5
- - **Owner**: framework-team
6
- - **Criado em**: 2026-05-10
7
- - **Sprint alvo**: refator-2026-05
8
- - **ADRs relacionadas**: ADR-0007 (SDD), ADR-0008 (sub-agents executáveis)
9
-
10
- ## 1. Problema
11
- O framework declara "spec-driven" e "orquestração" no AGENTS.md mas não há mecânica: nenhum comando força spec antes de código, e os 6 papéis de AGENTS.md não têm sub-agents executáveis em `.claude/agents/`. Handoffs vivem como markdown manual em `memory/50-orchestration/handoffs/`. Resultado: cada agente reinventa formato, retrabalho alto, decisões perdidas.
12
-
13
- ## 2. Proposta de valor
14
- Toda feature não-trivial passa por `spec → plan → tasks` validado por CLI, e tarefas são roteadas para sub-agents Claude com handoff rastreável em SQLite. Spec-driven e orquestração deixam de ser slogans.
15
-
16
- ## 3. User stories
17
- - **Como** Product Agent, **quero** rascunhar uma spec em 5 min com template, **para que** o backlog tenha entrada estruturada
18
- - **Como** SDD Architect, **quero** que `spec:plan` só funcione com spec aprovada, **para que** ninguém pule etapa
19
- - **Como** Worker, **quero** receber handoff com 7 campos via tabela SQLite, **para que** eu não pesque contexto em markdown
20
- - **Como** Governance Agent, **quero** rodar `project:check` que falha se há código novo sem spec ativa, **para que** dívida não se acumule
21
-
22
- ## 4. Critérios de aceite
23
- - [x] AC-1: `npm run spec:new <feature>` cria diretório com spec.md preenchido a partir do template
24
- - [x] AC-2: `npm run spec:plan` e `spec:tasks` só rodam se a fase anterior está `approved+`
25
- - [x] AC-3: `npm run spec:check` lista status de todas as features e falha com exit≠0 se inconsistente
26
- - [ ] AC-4: `.claude/agents/*.md` para 6 papéis funcionando como sub-agents
27
- - [ ] AC-5: handoffs registrados em tabela SQLite (`universal.db.handoffs`) com 7 campos da ADR-0005
28
- - [ ] AC-6: `agent:route` aceita handoff e dispara sub-agent correspondente
29
- - [ ] AC-7: hook `UserPromptSubmit` injeta smart-context automaticamente
30
-
31
- ## 5. Escopo
32
- **Dentro**:
33
- - CLI `spec-cli.mjs` (new/plan/tasks/check)
34
- - Templates em `specs/_templates/`
35
- - 6 sub-agents em `.claude/agents/`
36
- - Tabela `handoffs` no `universal.db` + script `agent-router.mjs`
37
- - Hooks em `.claude/settings.json`
38
-
39
- **Fora**:
40
- - Embeddings semânticos (mantém FTS5)
41
- - UI/dashboard interativo de specs
42
- - Migrar handoffs antigos em markdown — só novos
43
- - Sub-agents para outros provedores (Copilot, Gemini) — só Claude nesta rodada
44
-
45
- ## 6. NFRs
46
- - Performance: `spec:check` < 500ms em 100 specs
47
- - Compatibilidade: scripts npm existentes não quebram
48
- - Segurança: nenhum script gera token/secret embedido
49
- - Observabilidade: cada invocação de sub-agent loga em `60-runs/`
50
-
51
- ## 7. Riscos
52
- | Risco | P | I | Mitigação |
53
- |---|---|---|---|
54
- | Hook UserPromptSubmit causa latência | M | M | Cache por hash do prompt + cap de bytes |
55
- | Sub-agents disputam contexto | B | A | Roteamento explícito via handoff, sem broadcast |
56
- | SDD vira burocracia | M | A | Lista clara em README de "quando NÃO precisa de spec" |
57
-
58
- ## 8. Métricas de sucesso (30d)
59
- - ≥80% das features novas atravessam o pipeline completo
60
- - 0 PRs mergeados com `spec:check` falhando
61
- - Tempo médio spec→tasks < 1 dia
1
+ # Spec: pipeline-sdd-e-orquestracao
2
+
3
+ - **ID**: SPEC-001
4
+ - **Status**: done
5
+ - **Owner**: framework-team
6
+ - **Criado em**: 2026-05-10
7
+ - **Sprint alvo**: refator-2026-05
8
+ - **ADRs relacionadas**: ADR-0007 (SDD), ADR-0008 (sub-agents executáveis)
9
+
10
+ ## 1. Problema
11
+ O framework declara "spec-driven" e "orquestração" no AGENTS.md mas não há mecânica: nenhum comando força spec antes de código, e os 6 papéis de AGENTS.md não têm sub-agents executáveis em `.claude/agents/`. Handoffs vivem como markdown manual em `memory/50-orchestration/handoffs/`. Resultado: cada agente reinventa formato, retrabalho alto, decisões perdidas.
12
+
13
+ ## 2. Proposta de valor
14
+ Toda feature não-trivial passa por `spec → plan → tasks` validado por CLI, e tarefas são roteadas para sub-agents Claude com handoff rastreável em SQLite. Spec-driven e orquestração deixam de ser slogans.
15
+
16
+ ## 3. User stories
17
+ - **Como** Product Agent, **quero** rascunhar uma spec em 5 min com template, **para que** o backlog tenha entrada estruturada
18
+ - **Como** SDD Architect, **quero** que `spec:plan` só funcione com spec aprovada, **para que** ninguém pule etapa
19
+ - **Como** Worker, **quero** receber handoff com 7 campos via tabela SQLite, **para que** eu não pesque contexto em markdown
20
+ - **Como** Governance Agent, **quero** rodar `project:check` que falha se há código novo sem spec ativa, **para que** dívida não se acumule
21
+
22
+ ## 4. Critérios de aceite
23
+ - [x] AC-1: `npm run spec:new <feature>` cria diretório com spec.md preenchido a partir do template
24
+ - [x] AC-2: `npm run spec:plan` e `spec:tasks` só rodam se a fase anterior está `approved+`
25
+ - [x] AC-3: `npm run spec:check` lista status de todas as features e falha com exit≠0 se inconsistente
26
+ - [ ] AC-4: `.claude/agents/*.md` para 6 papéis funcionando como sub-agents
27
+ - [ ] AC-5: handoffs registrados em tabela SQLite (`universal.db.handoffs`) com 7 campos da ADR-0005
28
+ - [ ] AC-6: `agent:route` aceita handoff e dispara sub-agent correspondente
29
+ - [ ] AC-7: hook `UserPromptSubmit` injeta smart-context automaticamente
30
+
31
+ ## 5. Escopo
32
+ **Dentro**:
33
+ - CLI `spec-cli.mjs` (new/plan/tasks/check)
34
+ - Templates em `specs/_templates/`
35
+ - 6 sub-agents em `.claude/agents/`
36
+ - Tabela `handoffs` no `universal.db` + script `agent-router.mjs`
37
+ - Hooks em `.claude/settings.json`
38
+
39
+ **Fora**:
40
+ - Embeddings semânticos (mantém FTS5)
41
+ - UI/dashboard interativo de specs
42
+ - Migrar handoffs antigos em markdown — só novos
43
+ - Sub-agents para outros provedores (Copilot, Gemini) — só Claude nesta rodada
44
+
45
+ ## 6. NFRs
46
+ - Performance: `spec:check` < 500ms em 100 specs
47
+ - Compatibilidade: scripts npm existentes não quebram
48
+ - Segurança: nenhum script gera token/secret embedido
49
+ - Observabilidade: cada invocação de sub-agent loga em `60-runs/`
50
+
51
+ ## 7. Riscos
52
+ | Risco | P | I | Mitigação |
53
+ |---|---|---|---|
54
+ | Hook UserPromptSubmit causa latência | M | M | Cache por hash do prompt + cap de bytes |
55
+ | Sub-agents disputam contexto | B | A | Roteamento explícito via handoff, sem broadcast |
56
+ | SDD vira burocracia | M | A | Lista clara em README de "quando NÃO precisa de spec" |
57
+
58
+ ## 8. Métricas de sucesso (30d)
59
+ - ≥80% das features novas atravessam o pipeline completo
60
+ - 0 PRs mergeados com `spec:check` falhando
61
+ - Tempo médio spec→tasks < 1 dia
@@ -0,0 +1,109 @@
1
+ # Plan: Predictive Change Simulation
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-01
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ `scripts/simulate.ts`, adapter puro de composição (mesmo padrão de `scripts/engineer.ts`) — nenhum
10
+ pacote novo em `packages/engineering`, porque não há lógica de domínio nova aqui, só orquestração
11
+ de engines já existentes (`SandboxEngine`, `checkConstitution`, `assessRisk`).
12
+
13
+ Ciclo do sandbox usado (D1): `create({sourceRef: ref})` → `prepare` → `execute(testCommand)` →
14
+ `reject` → `destroy`. **Não** usa `validate`/`diff`/`promote` do `SandboxEngine` — esses passos
15
+ existem pra "modifiquei o worktree, quero decidir se aplico as mudanças na árvore real"; aqui o
16
+ worktree já nasce checked out no `ref` (nada é modificado depois), e a árvore real nunca deveria
17
+ receber nada desta simulação. `reject()` aceita o estado `'validating'` (onde a sessão fica logo
18
+ após `execute()`) — não precisa passar por `validate()` pra chegar lá. Isso torna
19
+ "nunca promove" uma propriedade estrutural do código (a função `promote()` simplesmente nunca é
20
+ chamada em lugar nenhum deste arquivo), não uma disciplina que dependeria de lembrar de não chamar.
21
+
22
+ ## 2. Módulos afetados
23
+
24
+ | Caminho | Mudança | Risco |
25
+ |---|---|---|
26
+ | `scripts/simulate.ts` | novo — `forja simulate <ref>` | Médio — orquestra sandbox real + grafo temporário, mas cada peça já existe e testada |
27
+ | `lib/core/registry.ts` | 1 comando novo | Baixo |
28
+ | `test/simulate-cli.test.js` (novo) | fixture git isolada, verifica não-promoção e destruição do worktree | — |
29
+
30
+ ## 3. Diagrama de fluxo
31
+
32
+ ```text
33
+ forja simulate <ref> [--command "npm test"]
34
+ │
35
+ ├─► SandboxEngine.create({sourceRef: ref}) — GitWorktreeBackend, worktree isolado real
36
+ ├─► SandboxEngine.prepare
37
+ ├─► SandboxEngine.execute({command}) — roda o teste DENTRO do worktree
38
+ │ │
39
+ │ ▼ (sessão em 'validating')
40
+ ├─► SqliteMigrationRunner sobre um SQLite TEMPORÁRIO (mkdtemp, não getWorkspaceDbPath)
41
+ ├─► GraphIndexer.sync(GitGraphDocumentSource(session.root)) — indexa o worktree isolado
42
+ ├─► checkConstitution(constitution.json do worktree, arestas do grafo temporário)
43
+ ├─► buildRiskInput(changedFiles, database-temporário) + assessRisk
44
+ │
45
+ ├─► SandboxEngine.reject(session.id) — nunca promote()
46
+ └─► SandboxEngine.destroy(session.id) — sempre, mesmo em erro (try/finally)
47
+ │
48
+ ▼
49
+ SimulationReport { testResult, architectureCheck, risk, recommendation }
50
+ ```
51
+
52
+ ## 4. Contratos (CLI/Schema)
53
+
54
+ ```ts
55
+ // scripts/simulate.ts
56
+ interface SimulationReport {
57
+ readonly ref: string;
58
+ readonly changedFiles: readonly string[];
59
+ readonly testCommand: string;
60
+ readonly testResult: { readonly exitCode: number; readonly durationMs: number; readonly passed: boolean };
61
+ readonly architectureCheck: ArchitectureCheckReport | { readonly note: string };
62
+ readonly risk: ChangeRiskAssessment;
63
+ readonly recommendation: 'promote' | 'review' | 'discard';
64
+ }
65
+ ```
66
+
67
+ ```bash
68
+ simulate <ref> [--command "npm test"] [--json]
69
+ ```
70
+
71
+ ## 5. Decisões e alternativas
72
+
73
+ **D1**: ciclo `create→prepare→execute→reject→destroy`, sem `validate`/`diff`/`promote` — ver §1.
74
+ Alternativa considerada: usar o ciclo completo de `runSandboxedCapability` — rejeitada porque esse
75
+ helper foi desenhado pra capabilities que **modificam** o worktree via `work()` e depois decidem
76
+ promover; aqui o "trabalho" é só checkout+teste, sem modificação, e a promoção nunca deveria
77
+ acontecer — usar o ciclo completo introduziria um caminho de código (`promote`) que não deveria
78
+ nunca ser exercitado, risco desnecessário pro que AC-3 exige.
79
+
80
+ **D2**: `changedFiles` vem de `git diff --name-only HEAD <ref>` (reaproveita
81
+ `lib/core/risk-collect.ts.changedFiles`, mesma função de `risk:assess`/`forja engineer`) — rodado
82
+ **antes** de criar o sandbox, contra a árvore real (só leitura, `git diff` não modifica nada).
83
+
84
+ **D3**: grafo + banco da simulação são **completamente isolados** do workspace real — SQLite em
85
+ `fs.mkdtempSync`, apontando `FORJA_GRAPH_ROOT` pro `session.root` só durante a chamada de
86
+ `buildRiskInput`/`checkConstitution` (restaurado no `finally`, mesmo em exceção). Alternativa
87
+ rejeitada: reaproveitar `getWorkspaceDbPath()` — violaria AC-2/NFR explicitamente (contaminaria o
88
+ grafo persistente com o estado de um ref que pode nunca ser integrado).
89
+
90
+ **D4**: `recommendation` — `discard` se o teste falhar (hard gate); senão `review` se houver
91
+ violação de arquitetura `active` OU `risk.autonomyBand` for `supervised`/`human_in_the_loop`;
92
+ senão `promote`. Mesma filosofia de "informa, não decide" de `RiskEngine` (SPEC-034 D3) —
93
+ `forja simulate` nunca aplica a mudança sozinho independente da recomendação.
94
+
95
+ ## 6. Dependências
96
+
97
+ - SPEC-033 (`checkConstitution`), SPEC-034 (`assessRisk`/`buildRiskInput`, `lib/core/risk-collect.ts`)
98
+ — reaproveitados sem mudança.
99
+ - `packages/sandbox.SandboxEngine`/`packages/adapter-git.GitWorktreeBackend` — já existentes.
100
+
101
+ ## 7. Rollout
102
+
103
+ Sem migração, sem feature flag — comando novo, opt-in.
104
+
105
+ ## 8. Kill criteria
106
+
107
+ Se a recomendação não corresponder a julgamento humano sobre um ref real (§8 do spec), os pesos de
108
+ D4 são revisados antes de qualquer consumo automático futuro (fora de escopo desta spec de
109
+ qualquer forma, §5 "Fora").
@@ -0,0 +1,107 @@
1
+ # Spec: Predictive Change Simulation
2
+
3
+ - **ID**: SPEC-038
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-01
7
+ - **Sprint alvo**: Sprint 6 (Fase 4 da visão original)
8
+ - **ADRs relacionadas**: ADR-0078; depende de SPEC-033 (`checkConstitution`), SPEC-034
9
+ (`assessRisk`/`buildRiskInput`) — reaproveitados, não recalculados
10
+
11
+ > Gap analysis original (`docs/architecture/...` §3): `SandboxEngine` + `GitWorktreeBackend` +
12
+ > `runSandboxedCapability` "já são exatamente 'aplicar em worktree isolado, testar, decidir
13
+ > promover ou descartar'" — **compor** sandbox + risk engine + architecture:check, não construir
14
+ > nada novo. Esta spec é essa composição.
15
+
16
+ ## 1. Problema
17
+
18
+ Hoje, avaliar se um ref/branch proposto é seguro pra integrar exige checkout manual, rodar teste
19
+ manualmente, rodar `architecture:check`/`risk:assess` manualmente, e cruzar os três resultados na
20
+ cabeça. Nenhum comando único simula "e se essa mudança fosse aplicada" com isolamento real e
21
+ resposta estruturada.
22
+
23
+ ## 2. Proposta de valor
24
+
25
+ `forja simulate <ref> [--command "npm test"]` aplica o `ref` num worktree git isolado (nunca a
26
+ árvore real), roda o comando de teste, computa `architecture:check`+`risk:assess` contra o estado
27
+ resultante, e devolve uma recomendação (`promote`/`review`/`discard`) — sempre destruindo o
28
+ worktree ao final, nunca promovendo automaticamente.
29
+
30
+ ## 3. User stories
31
+
32
+ - **Como** governance, **quero** simular uma mudança antes de integrá-la, **para que** eu veja
33
+ teste+arquitetura+risco combinados sem tocar a árvore real nem rodar três comandos manualmente.
34
+
35
+ ## 4. Critérios de aceite (Definition of Done)
36
+
37
+ - [x] AC-1: `forja simulate <ref>` cria um worktree git isolado no `ref` (via `SandboxEngine` +
38
+ `GitWorktreeBackend`, já existentes — nenhum motor de isolamento novo), roda o comando de
39
+ teste (`--command`, default `npm test`) dentro dele via `sandbox.execute()`.
40
+ - [x] AC-2: `architecture:check`/`risk:assess` rodam contra o **estado do worktree isolado**
41
+ (reaproveitando `checkConstitution`/`buildRiskInput` já existentes — nenhuma lógica de
42
+ violação/risco reimplementada), usando um SQLite temporário próprio da simulação — **nunca**
43
+ o workspace real (evita contaminar o Engineering Graph persistente com estado de um ref que
44
+ pode nunca ser integrado).
45
+ - [x] AC-3: o worktree é **sempre destruído** ao final (sucesso, falha de teste, ou exceção) —
46
+ `forja simulate` nunca chama `sandbox.promote()`; a única escrita na árvore real é a remoção
47
+ do próprio worktree. Verificável: `git worktree list` antes/depois idêntico.
48
+ - [x] AC-4: recomendação (`promote`/`review`/`discard`) é determinística a partir de teste+
49
+ arquitetura+risco (regra documentada em código e no plan) — nunca decide sozinha (não chama
50
+ `PolicyEngine`, não integra nada), é leitura, mesmo princípio de `RiskEngine`/SPEC-034 D3.
51
+ - [x] AC-5: `--json` produz saída estruturada; texto legível por padrão.
52
+
53
+ ## 5. Escopo
54
+
55
+ **Dentro**: `forja simulate <ref> [--command <cmd>] [--json]`, composição de `SandboxEngine` +
56
+ `checkConstitution` + `assessRisk`.
57
+
58
+ **Fora**: aplicação automática (`sandbox.promote()` nunca é chamado — essa decisão continua manual,
59
+ via os fluxos normais de merge/PR); simular a partir de um patch/diff textual solto (só refs git,
60
+ mesmo princípio de `risk:assess`/SPEC-034 D1 — verificável, não texto livre); múltiplos comandos de
61
+ teste em paralelo (um `--command` por vez, nesta versão).
62
+
63
+ ## 6. NFRs / restrições
64
+
65
+ - Isolamento real: nenhuma escrita na árvore/branch atual além do worktree (que é sempre removido).
66
+ - SQLite temporário e descartável — zero persistência cross-run do Engineering Graph do ref
67
+ simulado.
68
+ - Determinístico: nenhum LLM em nenhum ponto.
69
+
70
+ ## 7. Riscos e mitigação
71
+
72
+ | Risco | Probabilidade | Impacto | Mitigação |
73
+ |---|---|---|---|
74
+ | Simulação vazar pro Engineering Graph real | Média se não isolado explicitamente | Alta (grafo persistente contaminado com ref nunca integrado) | AC-2: SQLite temporário próprio, nunca `getWorkspaceDbPath()` |
75
+ | `forja simulate` promover por engano | Baixa (mesmo padrão de `runSandboxedCapability`) | Muito alta (mudaria a árvore real sem revisão) | AC-3: nenhuma chamada a `sandbox.promote()` em todo o código; teste de CLI verifica `git worktree list` antes/depois |
76
+ | Comando de teste do projeto não ser `npm test` | Média (todo projeto é diferente) | Baixa | `--command` configurável, `npm test` é só o default |
77
+
78
+ ## 8. Métricas de sucesso
79
+
80
+ Simular um ref real deste repositório (ex.: um commit já mergeado, comparado contra seu pai) produz
81
+ teste+arquitetura+risco coerentes com o que se sabe sobre aquela mudança — revisão humana, mesma
82
+ metodologia de SPEC-034/036/037 §8.
83
+
84
+ **Validado**: `forja simulate <commit real deste repositório> --command "node --test
85
+ test/risk-engine.test.js"` — teste passou, `architecture:check` achou a regra active real (0
86
+ violações, coerente com o estado real do repositório), risco 18/100 (`autonomous`), recomendação
87
+ `promote`. `git worktree list`/`git status` idênticos antes/depois (AC-3 confirmado sobre dado
88
+ real, não só fixture).
89
+
90
+ **Achados reais corrigidos durante a implementação (não adiados)**:
91
+
92
+ 1. **`sandboxEnvironment()` não passava `HOME`/`USERPROFILE`** (`packages/adapter-git/src/index.ts`
93
+ — código pré-existente, não escrito nesta spec, mas exposto por ela: nenhum consumidor anterior
94
+ do sandbox rodava um comando dependente de resolver `HOME`). `npm test` como comando de teste
95
+ travava indefinidamente com o ambiente restrito por padrão — sem `HOME`, `npm` não consegue
96
+ resolver seu diretório de config/cache e trava em vez de falhar rápido (reproduzido
97
+ isoladamente com `env -i` fora do sandbox pra confirmar a causa antes de mexer no código).
98
+ Corrigido adicionando os dois ao allowlist fixo — nenhum dos dois é segredo, e o teste "runner
99
+ não herda secrets do ambiente por padrão" continua passando (cobre uma env var arbitrária do
100
+ processo host, não este allowlist).
101
+ 2. **Rodar `--command "npm test"` (a suíte inteira, 400+ testes) contra este próprio repositório é
102
+ lento e inconsistente neste ambiente sandboxado** — mesma categoria de achado já documentada em
103
+ SPEC-032 (SQLite não em lote) e SPEC-034 (reindexação do grafo real): I/O pesado sob este
104
+ sandbox específico não é confiável dentro de um timeout razoável. Não é um bug em `forja
105
+ simulate` (a mesma suíte roda em ~10s fora de um worktree recém-criado, sem cache de
106
+ dependências); a validação real do §8 usou um comando de teste mais leve por esse motivo — não
107
+ um limite estrutural de `forja simulate`.
@@ -0,0 +1,41 @@
1
+ # Tasks: Predictive Change Simulation
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-01
7
+
8
+ ---
9
+
10
+ ## T1 — `scripts/simulate.ts`: sandbox real + grafo temporário + recomendação
11
+ - **Owner**: worker
12
+ - **Estimativa**: G
13
+ - **Depende de**: —
14
+ - **Paths**: `scripts/simulate.ts`, `lib/core/registry.ts`
15
+ - **Done quando**:
16
+ - [ ] `SandboxEngine.create({sourceRef: ref})` → `prepare` → `execute` → `reject` → `destroy`
17
+ (D1) — `promote()` nunca chamado em nenhum caminho, incluindo erro
18
+ - [ ] SQLite/grafo da simulação são temporários (`mkdtemp`), nunca `getWorkspaceDbPath()` (D3)
19
+ - [ ] `checkConstitution`/`assessRisk` rodam contra o worktree isolado, reaproveitando
20
+ `lib/core/risk-collect.ts`
21
+ - [ ] `recommendation` segue a regra de D4
22
+ - [ ] worktree sempre destruído mesmo se o teste falhar ou o processo lançar exceção
23
+ (try/finally)
24
+ - [ ] `forja tools:doctor` continua verde
25
+
26
+ ## T2 — prova de isolamento + prova sobre ref real
27
+ - **Owner**: worker
28
+ - **Estimativa**: M
29
+ - **Depende de**: T1
30
+ - **Paths**: `test/simulate-cli.test.js` (novo)
31
+ - **Done quando**:
32
+ - [ ] fixture git isolada: `git worktree list` antes/depois de `forja simulate` idêntico (AC-3)
33
+ - [ ] teste com comando de teste que falha → `recommendation: 'discard'`
34
+ - [ ] teste com violação de arquitetura injetada → `recommendation: 'review'`
35
+ - [ ] simulação de um ref real deste repositório (§8 do spec) documentada no spec.md
36
+
37
+ ---
38
+
39
+ ## Handoffs entre agentes
40
+
41
+ T1 → T2 sequencial. Sem handoff de papel.
@@ -1,96 +1,96 @@
1
- # Spec: project-smoke
2
-
3
- - **ID**: SPEC-015
4
- - **Status**: done
5
- - **Owner**: apk
6
- - **Criado em**: 2026-07-19
7
- - **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-release-gate.md) (gate do tarball — o padrão), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (doctor), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry)
8
-
9
- ## 1. Problema
10
-
11
- O `release:check` guarda uma fronteira: **o repositório mente sobre o pacote**. Existe a *mesma
12
- classe de bug um nível acima*, e ela está **descoberta**: nada prova que `forja project:new` gera um
13
- projeto que de fato **é coerente e roda**.
14
-
15
- O gerador escreve arquivos a partir de templates (`{{FEATURE}}`, `{{ID}}`, blocos de `scripts`, configs
16
- multi-IA). Cada um desses é uma oportunidade de mentira silenciosa:
17
-
18
- - um placeholder `{{...}}` que vaza para o output porque o gerador esqueceu de substituir;
19
- - um `package.json` gerado que não é JSON válido, ou sem os scripts que os docs prometem;
20
- - a estrutura de memória incompleta (falta um diretório crítico que o resto assume);
21
- - no limite: o projeto gerado simplesmente **não buildar**.
22
-
23
- Hoje só descobrimos isso quando um usuário gera um projeto e ele quebra — exatamente o modo de falha
24
- que o `release:check` existe para eliminar, só que na saída do gerador em vez do tarball. **Não é
25
- conhecimento que falta** (o `structure-validator` já sabe validar estrutura). **É execução**: nada
26
- roda o gerador de ponta a ponta e reprova.
27
-
28
- ## 2. Proposta de valor
29
-
30
- Gerar um projeto deixa de ser um ato de fé: **nenhuma mudança no gerador passa sem prova de que o
31
- projeto gerado é coerente**, e a prova é gerada pelo harness — não pela lembrança de quem tocou no
32
- template.
33
-
34
- ## 3. User stories
35
-
36
- - **Como** quem mantém o gerador, **quero** que uma mudança que quebra o output **reprove no CI**,
37
- **para que** eu não descubra pela issue de um usuário.
38
- - **Como** usuário do `forjajs`, **quero** que `forja project:new` me entregue um projeto sem
39
- placeholders vazados nem `package.json` quebrado, **para que** eu não perca a primeira hora
40
- depurando o scaffold em vez do meu produto.
41
- - **Como** governança, **quero** a evidência de que o projeto gerado buildar **no log do CI**,
42
- **para que** "o gerador funciona" seja um artefato verificável e não uma afirmação.
43
-
44
- ## 4. Critérios de aceite (Definition of Done)
45
-
46
- - [ ] AC-1: Existe `forja project:smoke` (entrada no registry, ADR-0020) que **gera um projeto num
47
- diretório temporário isolado** e reprova com exit ≠ 0 em qualquer falha abaixo. Limpa o tmp
48
- sempre, inclusive quando um check lança.
49
- - [ ] AC-2: **Zero placeholder vazado.** Nenhum arquivo gerado contém `{{...}}` não substituído.
50
- É o bug mais barato de introduzir e o mais visível para o usuário.
51
- - [ ] AC-3: **Todo `package.json` gerado é JSON válido** e contém os scripts que o gerador anuncia.
52
- - [ ] AC-4: **Estrutura íntegra.** `validateProjectStructure` do projeto gerado passa (reusa o
53
- `structure-validator` existente — uma máquina, não duas).
54
- - [ ] AC-5: **Modo `--full` (opt-in): o projeto buildar de verdade.** `npm install` + `npm run build`
55
- no backend gerado, num ambiente isolado. É o análogo do clean-install do `release:check`:
56
- caro, roda antes de release, não a cada commit.
57
- - [ ] AC-6: **Reusa o runner de `checks.mjs`.** O `project:smoke` é um catálogo novo consumido pelo
58
- mesmo runner do doctor/release — mesma máquina de probes, `severity`, cascata por `dependsOn`.
59
- - [ ] AC-7: O gate roda no CI (tier barato) e o `tools:doctor` **não** o executa (custo alto; é um
60
- gate próprio, como o `release:check`).
61
-
62
- ## 5. Escopo
63
-
64
- **Dentro**:
65
- - Comando `project:smoke` + catálogo `lib/core/project-smoke.mjs`.
66
- - Isolamento em tmp + limpeza garantida (padrão do `withCleanInstall`).
67
- - Tier barato (placeholders, JSON, estrutura) no CI; tier `--full` (install+build) opt-in.
68
-
69
- **Fora** (explícito):
70
- - Rodar a suíte de testes do projeto gerado (`npm test`) — fica para uma iteração futura; build já
71
- prova que os imports resolvem.
72
- - Validar os boilerplates de stack individualmente (`api-rest`, `saas`, …) — este gate cobre o
73
- caminho default do gerador; a matriz de stacks é escopo à parte.
74
- - Publicar o projeto gerado em qualquer lugar.
75
-
76
- ## 6. NFRs / restrições
77
-
78
- - **Compatibilidade**: não muda o comportamento de `init-project`/`create-memory-nest-kit` — só os
79
- observa. O gerador não sabe que está sendo auditado.
80
- - **Isolamento**: o tier `--full` roda `npm install` fora do repo, com o ambiente limpo (sem
81
- `NODE_PATH`/`npm_config_*` herdados — a lição do `release:check`).
82
- - **Custo**: o tier barato roda em segundos (sem rede); o `--full` é minutos (baixa NestJS).
83
-
84
- ## 7. Riscos e mitigação
85
-
86
- | Risco | Probabilidade | Impacto | Mitigação |
87
- |---|---|---|---|
88
- | `--full` flaky por rede (npm registry) | M | M | tier barato é o gate de CI; `--full` é opt-in/pré-release, como o clean-install |
89
- | Gerador tem efeitos colaterais fora do tmp | B | A | gerar sempre com destino explícito no tmp; o teste falha alto se escrever fora |
90
- | Duplicar lógica de validação | B | M | reusar `structure-validator` e o runner de `checks.mjs` — AC-4/AC-6 |
91
-
92
- ## 8. Métricas de sucesso
93
-
94
- 30 dias após o release: **pelo menos uma regressão do gerador pega pelo gate antes do merge** (a
95
- prova de que a fronteira estava mesmo descoberta), e **zero issue de usuário sobre scaffold quebrado**
96
- (placeholder vazado, `package.json` inválido).
1
+ # Spec: project-smoke
2
+
3
+ - **ID**: SPEC-015
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-19
7
+ - **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-release-gate.md) (gate do tarball — o padrão), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (doctor), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry)
8
+
9
+ ## 1. Problema
10
+
11
+ O `release:check` guarda uma fronteira: **o repositório mente sobre o pacote**. Existe a *mesma
12
+ classe de bug um nível acima*, e ela está **descoberta**: nada prova que `forja project:new` gera um
13
+ projeto que de fato **é coerente e roda**.
14
+
15
+ O gerador escreve arquivos a partir de templates (`{{FEATURE}}`, `{{ID}}`, blocos de `scripts`, configs
16
+ multi-IA). Cada um desses é uma oportunidade de mentira silenciosa:
17
+
18
+ - um placeholder `{{...}}` que vaza para o output porque o gerador esqueceu de substituir;
19
+ - um `package.json` gerado que não é JSON válido, ou sem os scripts que os docs prometem;
20
+ - a estrutura de memória incompleta (falta um diretório crítico que o resto assume);
21
+ - no limite: o projeto gerado simplesmente **não buildar**.
22
+
23
+ Hoje só descobrimos isso quando um usuário gera um projeto e ele quebra — exatamente o modo de falha
24
+ que o `release:check` existe para eliminar, só que na saída do gerador em vez do tarball. **Não é
25
+ conhecimento que falta** (o `structure-validator` já sabe validar estrutura). **É execução**: nada
26
+ roda o gerador de ponta a ponta e reprova.
27
+
28
+ ## 2. Proposta de valor
29
+
30
+ Gerar um projeto deixa de ser um ato de fé: **nenhuma mudança no gerador passa sem prova de que o
31
+ projeto gerado é coerente**, e a prova é gerada pelo harness — não pela lembrança de quem tocou no
32
+ template.
33
+
34
+ ## 3. User stories
35
+
36
+ - **Como** quem mantém o gerador, **quero** que uma mudança que quebra o output **reprove no CI**,
37
+ **para que** eu não descubra pela issue de um usuário.
38
+ - **Como** usuário do `forjajs`, **quero** que `forja project:new` me entregue um projeto sem
39
+ placeholders vazados nem `package.json` quebrado, **para que** eu não perca a primeira hora
40
+ depurando o scaffold em vez do meu produto.
41
+ - **Como** governança, **quero** a evidência de que o projeto gerado buildar **no log do CI**,
42
+ **para que** "o gerador funciona" seja um artefato verificável e não uma afirmação.
43
+
44
+ ## 4. Critérios de aceite (Definition of Done)
45
+
46
+ - [ ] AC-1: Existe `forja project:smoke` (entrada no registry, ADR-0020) que **gera um projeto num
47
+ diretório temporário isolado** e reprova com exit ≠ 0 em qualquer falha abaixo. Limpa o tmp
48
+ sempre, inclusive quando um check lança.
49
+ - [ ] AC-2: **Zero placeholder vazado.** Nenhum arquivo gerado contém `{{...}}` não substituído.
50
+ É o bug mais barato de introduzir e o mais visível para o usuário.
51
+ - [ ] AC-3: **Todo `package.json` gerado é JSON válido** e contém os scripts que o gerador anuncia.
52
+ - [ ] AC-4: **Estrutura íntegra.** `validateProjectStructure` do projeto gerado passa (reusa o
53
+ `structure-validator` existente — uma máquina, não duas).
54
+ - [ ] AC-5: **Modo `--full` (opt-in): o projeto buildar de verdade.** `npm install` + `npm run build`
55
+ no backend gerado, num ambiente isolado. É o análogo do clean-install do `release:check`:
56
+ caro, roda antes de release, não a cada commit.
57
+ - [ ] AC-6: **Reusa o runner de `checks.mjs`.** O `project:smoke` é um catálogo novo consumido pelo
58
+ mesmo runner do doctor/release — mesma máquina de probes, `severity`, cascata por `dependsOn`.
59
+ - [ ] AC-7: O gate roda no CI (tier barato) e o `tools:doctor` **não** o executa (custo alto; é um
60
+ gate próprio, como o `release:check`).
61
+
62
+ ## 5. Escopo
63
+
64
+ **Dentro**:
65
+ - Comando `project:smoke` + catálogo `lib/core/project-smoke.mjs`.
66
+ - Isolamento em tmp + limpeza garantida (padrão do `withCleanInstall`).
67
+ - Tier barato (placeholders, JSON, estrutura) no CI; tier `--full` (install+build) opt-in.
68
+
69
+ **Fora** (explícito):
70
+ - Rodar a suíte de testes do projeto gerado (`npm test`) — fica para uma iteração futura; build já
71
+ prova que os imports resolvem.
72
+ - Validar os boilerplates de stack individualmente (`api-rest`, `saas`, …) — este gate cobre o
73
+ caminho default do gerador; a matriz de stacks é escopo à parte.
74
+ - Publicar o projeto gerado em qualquer lugar.
75
+
76
+ ## 6. NFRs / restrições
77
+
78
+ - **Compatibilidade**: não muda o comportamento de `init-project`/`create-memory-nest-kit` — só os
79
+ observa. O gerador não sabe que está sendo auditado.
80
+ - **Isolamento**: o tier `--full` roda `npm install` fora do repo, com o ambiente limpo (sem
81
+ `NODE_PATH`/`npm_config_*` herdados — a lição do `release:check`).
82
+ - **Custo**: o tier barato roda em segundos (sem rede); o `--full` é minutos (baixa NestJS).
83
+
84
+ ## 7. Riscos e mitigação
85
+
86
+ | Risco | Probabilidade | Impacto | Mitigação |
87
+ |---|---|---|---|
88
+ | `--full` flaky por rede (npm registry) | M | M | tier barato é o gate de CI; `--full` é opt-in/pré-release, como o clean-install |
89
+ | Gerador tem efeitos colaterais fora do tmp | B | A | gerar sempre com destino explícito no tmp; o teste falha alto se escrever fora |
90
+ | Duplicar lógica de validação | B | M | reusar `structure-validator` e o runner de `checks.mjs` — AC-4/AC-6 |
91
+
92
+ ## 8. Métricas de sucesso
93
+
94
+ 30 dias após o release: **pelo menos uma regressão do gerador pega pelo gate antes do merge** (a
95
+ prova de que a fronteira estava mesmo descoberta), e **zero issue de usuário sobre scaffold quebrado**
96
+ (placeholder vazado, `package.json` inválido).