forjajs 2.0.3 → 2.0.4

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 (701) hide show
  1. package/.claude/agents/context-engineer.md +25 -25
  2. package/.claude/agents/governance.md +55 -55
  3. package/.claude/agents/marketing.md +24 -24
  4. package/.claude/agents/orchestrator.md +31 -31
  5. package/.claude/agents/product.md +26 -26
  6. package/.claude/agents/release-auditor.md +68 -59
  7. package/.claude/agents/sdd-architect.md +34 -34
  8. package/.claude/settings.json +76 -76
  9. package/.claude/skills/new-adr/SKILL.md +61 -61
  10. package/.claude/skills/new-command/SKILL.md +67 -67
  11. package/.gemini-instructions.md +87 -87
  12. package/.github/copilot-instructions.md +87 -87
  13. package/.memoryrc.json +104 -104
  14. package/.openai-instructions.md +87 -87
  15. package/AGENTS.md +134 -134
  16. package/CHANGELOG.md +566 -550
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +65 -60
  19. package/LICENSE +21 -21
  20. package/README.md +358 -339
  21. package/README.pt-BR.md +345 -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/dashboard-client.jsx +10 -10
  328. package/dist/bin/create-memory-nest-kit.js +17 -17
  329. package/dist/bin/forja.js +14 -2
  330. package/dist/bin/init-project.js +38 -38
  331. package/dist/lib/audit.js +7 -7
  332. package/dist/lib/context-builder.js +32 -32
  333. package/dist/lib/core/doc-graph.js +6 -4
  334. package/dist/lib/core/registry.d.ts +54 -0
  335. package/dist/lib/core/registry.js +55 -0
  336. package/dist/lib/core/release.d.ts +53 -0
  337. package/dist/lib/core/release.js +5 -1
  338. package/dist/lib/generators/memory-generator.js +700 -698
  339. package/dist/lib/generators/nest-generator.js +398 -398
  340. package/dist/lib/generators/readme-generator.js +180 -180
  341. package/dist/lib/governance-report.js +39 -39
  342. package/dist/lib/project-upgrade.js +1 -1
  343. package/dist/lib/workspace.d.ts +7 -0
  344. package/dist/lib/workspace.js +63 -34
  345. package/dist/packages/adapter-sqlite/src/index.js +12 -12
  346. package/dist/packages/llm/src/index.d.ts +43 -0
  347. package/dist/packages/llm/src/index.js +108 -0
  348. package/dist/scripts/agent-harness.js +66 -64
  349. package/dist/scripts/agent-router.js +20 -20
  350. package/dist/scripts/build-smart-context.js +22 -22
  351. package/dist/scripts/compress-memory.js +8 -8
  352. package/dist/scripts/context-ops.js +29 -29
  353. package/dist/scripts/demo-autonomy.js +2 -2
  354. package/dist/scripts/demo-workspace.d.ts +6 -0
  355. package/dist/scripts/demo-workspace.js +101 -0
  356. package/dist/scripts/dev.js +13 -13
  357. package/dist/scripts/extract-global-knowledge.js +5 -5
  358. package/dist/scripts/generate-dashboard.js +11 -11
  359. package/dist/scripts/llm-fit.js +131 -0
  360. package/dist/scripts/memory-schema.js +48 -48
  361. package/dist/scripts/query-universal-memory.js +13 -13
  362. package/dist/scripts/sprint-manager.js +39 -39
  363. package/dist/scripts/sync-universal-memory.js +63 -50
  364. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  365. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  366. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  367. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  368. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  369. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  370. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  371. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  372. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  373. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  374. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  375. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  376. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  377. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  378. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  379. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  380. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  381. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  382. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  383. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  384. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  385. package/docs/agent-harnesses.md +149 -149
  386. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  387. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  388. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  389. package/docs/archive/FASE2-SUMMARY.md +263 -263
  390. package/docs/archive/FASE3-PROGRESS.md +355 -355
  391. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  392. package/docs/archive/INDICE-MASTER.md +282 -282
  393. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  394. package/docs/archive/README-REFINAMENTO.md +293 -293
  395. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  396. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  397. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  398. package/docs/archive/START-HERE.md +319 -319
  399. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  400. package/docs/archive/examples/v1/AGENTS.md +10 -10
  401. package/docs/archive/examples/v1/README.md +36 -36
  402. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  403. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  404. package/docs/archive/examples/v1/backend/package.json +42 -42
  405. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  406. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  407. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  408. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  409. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  410. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  411. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  412. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  413. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  414. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  415. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  416. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  417. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  418. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  419. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  420. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  421. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  422. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  423. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  424. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  425. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  426. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  427. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  428. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  429. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  430. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  431. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  432. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  433. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  434. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  435. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  436. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  437. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  438. package/docs/archive/examples/v2/AGENTS.md +16 -16
  439. package/docs/archive/examples/v2/README.md +35 -35
  440. package/docs/archive/examples/v2/agents/README.md +3 -3
  441. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  442. package/docs/archive/examples/v2/agents/dba.md +4 -4
  443. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  444. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  445. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  446. package/docs/archive/examples/v2/agents/security.md +4 -4
  447. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  448. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  449. package/docs/archive/examples/v2/backend/package.json +42 -42
  450. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  451. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  452. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  453. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  454. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  455. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  456. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  457. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  458. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  459. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  460. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  461. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  462. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  463. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  464. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  465. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  466. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  467. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  468. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  469. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  470. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  471. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  472. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  473. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  474. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  475. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  476. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  477. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  478. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  479. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  480. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  481. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  482. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  483. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  484. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  485. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  486. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  487. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  488. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  489. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  490. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  491. package/docs/archive/examples/v2/memory/README.md +8 -8
  492. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  493. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  494. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  495. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  496. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  497. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  498. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  499. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  500. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  501. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  502. package/docs/capacidades-externas.md +86 -86
  503. package/docs/cli-first-operacao.md +74 -74
  504. package/docs/dev-workflow.md +421 -421
  505. package/docs/examples.md +546 -546
  506. package/docs/fluxo.md +103 -103
  507. package/docs/glossary.md +453 -453
  508. package/docs/init-project.md +457 -457
  509. package/docs/llm-fit-loop.md +41 -0
  510. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  511. package/docs/modos-de-operacao.md +52 -0
  512. package/docs/personas/architect/README.md +333 -333
  513. package/docs/personas/developer/README.md +371 -371
  514. package/docs/personas/executive/README.md +172 -172
  515. package/docs/personas/qa/README.md +350 -350
  516. package/docs/processo-projeto.md +138 -138
  517. package/docs/produto/factsheet-marketing.md +151 -0
  518. package/docs/produto/roteiro-demo.md +47 -0
  519. package/docs/publishing.md +377 -377
  520. package/docs/quick-reference.md +409 -409
  521. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  522. package/docs/structure.md +360 -360
  523. package/docs/token-optimization.md +502 -502
  524. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  525. package/memory/00-global/mission.md +15 -15
  526. package/memory/00-global/shared-knowledge.md +8 -8
  527. package/memory/00-global/standards.md +47 -47
  528. package/memory/10-product/personas.md +21 -21
  529. package/memory/10-product/vision.md +27 -27
  530. package/memory/30-projects/README.md +15 -15
  531. package/memory/40-delivery/backlog.md +15 -15
  532. package/memory/40-delivery/current-sprint.md +23 -26
  533. package/memory/50-orchestration/gsd-harness.md +55 -55
  534. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  535. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  536. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  537. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  538. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  539. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  540. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  541. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  542. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  543. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  544. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  545. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  546. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  547. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  548. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  549. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  550. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  551. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  552. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  553. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  554. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  555. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  556. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  557. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  558. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  559. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  560. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  561. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  562. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  563. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  564. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  565. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  566. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  567. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  568. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  569. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  570. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  571. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  572. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  573. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  574. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  575. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  576. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  577. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  578. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  579. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  580. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  581. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  582. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  583. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  584. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  585. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  586. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  587. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  588. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  589. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  590. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  591. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  592. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  593. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  594. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  595. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  596. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  597. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  598. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  599. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  600. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  601. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  602. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  603. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  604. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  605. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  606. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  607. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  608. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  609. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  610. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  611. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  612. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  613. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  614. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  615. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  616. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  617. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  618. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  619. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  620. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  621. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  622. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  623. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  624. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  625. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  626. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  627. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  628. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  629. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  630. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  631. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  632. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  633. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  634. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  635. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  636. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  637. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  638. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  639. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  640. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  641. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  642. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  643. package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
  644. package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
  645. package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
  646. package/memory/90-decisions/_template.md +28 -28
  647. package/package.json +157 -150
  648. package/prompts/context-engineer-agent.md +19 -19
  649. package/prompts/governance-agent.md +16 -16
  650. package/prompts/marketing-agent.md +13 -13
  651. package/prompts/orchestrator-agent.md +18 -18
  652. package/prompts/product-agent.md +13 -13
  653. package/prompts/sdd-architect-agent.md +20 -20
  654. package/specs/README.md +70 -70
  655. package/specs/_templates/plan.md +43 -43
  656. package/specs/_templates/spec.md +43 -43
  657. package/specs/_templates/tasks.md +32 -32
  658. package/specs/clean-arch-boilerplate/plan.md +137 -137
  659. package/specs/clean-arch-boilerplate/spec.md +121 -121
  660. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  661. package/specs/cli-first-operacao/plan.md +53 -53
  662. package/specs/cli-first-operacao/spec.md +53 -53
  663. package/specs/cli-first-operacao/tasks.md +53 -53
  664. package/specs/code-context/spec.md +56 -56
  665. package/specs/coerencia-do-sistema/plan.md +155 -155
  666. package/specs/coerencia-do-sistema/spec.md +123 -123
  667. package/specs/coerencia-do-sistema/tasks.md +115 -115
  668. package/specs/dev-token-assets-db/plan.md +71 -71
  669. package/specs/dev-token-assets-db/spec.md +58 -58
  670. package/specs/dev-token-assets-db/tasks.md +58 -58
  671. package/specs/doctor-do-nucleo/plan.md +165 -165
  672. package/specs/doctor-do-nucleo/spec.md +139 -139
  673. package/specs/doctor-do-nucleo/tasks.md +172 -172
  674. package/specs/forja-core/spec.md +71 -71
  675. package/specs/gates/spec.md +63 -63
  676. package/specs/governanca-visivel/plan.md +122 -122
  677. package/specs/governanca-visivel/spec.md +112 -112
  678. package/specs/governanca-visivel/tasks.md +60 -60
  679. package/specs/harness-codegraph/spec.md +71 -71
  680. package/specs/memory-audit/spec.md +54 -54
  681. package/specs/orchestrate/spec.md +108 -108
  682. package/specs/orchestration-coherent/spec.md +95 -95
  683. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  684. package/specs/project-smoke/spec.md +96 -96
  685. package/specs/project-upgrade/spec.md +58 -58
  686. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  687. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  688. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  689. package/specs/release-auditor-health/plan.md +88 -0
  690. package/specs/release-auditor-health/spec.md +82 -0
  691. package/specs/release-auditor-health/tasks.md +72 -0
  692. package/specs/release-gate/plan.md +174 -174
  693. package/specs/release-gate/spec.md +122 -122
  694. package/specs/release-gate/tasks.md +183 -183
  695. package/specs/ts-migration/plan.md +200 -200
  696. package/specs/ts-migration/spec.md +119 -119
  697. package/specs/ts-migration/tasks.md +110 -110
  698. package/dist/scripts/server-persistence-probe.d.ts +0 -1
  699. package/dist/scripts/server-persistence-probe.js +0 -52
  700. package/dist/scripts/server-persistence-probe.mjs +0 -52
  701. /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
@@ -1,105 +1,105 @@
1
- # ADR-0025: Coerência da documentação como gate
2
-
3
- - **Status**: accepted
4
- - **Data**: 2026-07-18
5
- - **Autor(es)**: Allan Pablo
6
- - **Tags**: governance, docs, harness, diagnostics, registry
7
-
8
- ## Contexto
9
-
10
- Os ADRs 0023 e 0024 fecharam a classe "erra sem avisar" (ADR-0021) no **núcleo** e no **tarball**.
11
- Faltava a fronteira mais barata de corromper e a mais cara de perceber: a **palavra escrita**.
12
-
13
- O Forja é operado por agentes que leem a documentação e executam o que ela manda. Quando a doc e o
14
- código divergem, o agente não erra por burrice — erra por **obediência**. Uma auditoria manual em
15
- 2026-07-14 encontrou, entre outras coisas:
16
-
17
- - `docs/token-optimization.md` — o documento que ensina a economia de tokens (ADR-0009) — mandava
18
- rodar **quatro comandos que não existem** (`context:build`, `memory:db:reindex`, …) e linkava um
19
- `docs/DEPLOYMENT.md` que nunca existiu.
20
- - O Governance descrevia `tools:doctor` pela definição anterior ao ADR-0023.
21
- - Comandos do registry sem menção em lugar nenhum — capacidade obscura é capacidade morta.
22
-
23
- Nada disso quebrava um teste nem aparecia no `git status`. A correção manual apagou os sintomas do
24
- dia; nada impedia a reincidência. Toda vez que um comando é renomeado ou um gate muda de contrato, a
25
- doc pode silenciosamente passar a mentir.
26
-
27
- ## Decisão
28
-
29
- Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanner puro
30
- `lib/core/doc-graph.mjs` que lê os `.md` de instrução como dado:
31
-
32
- - **`docs-commands`** (critical): todo `forja <cmd>` / `npm run <cmd>` citado numa superfície de
33
- instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
34
- - **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
35
- - **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
36
- - **`adr-refs`** (warn, adicionado depois): toda citação `ADR-NNNN` em doc/spec/ADR aponta para um
37
- ADR que existe. Fecha o último invariante que vivia por disciplina ("toda decisão vira ADR") pelo
38
- lado verificável: referência a decisão inexistente é trilha que apodrece. Pegou o `ADR-0026`
39
- pendurado (citado pela SPEC-012, nunca escrito) na primeira execução.
40
- - **`agent-topology`** (warn, SPEC-019): a topologia de orquestração é descrita em três fontes
41
- (`VALID_AGENTS` do router, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio — o
42
- namesake do framework (orquestração multiagente) vivendo por disciplina. O check cruza as três:
43
- sub-agent sem rota, papel roteável sem executor, agente não documentado. `user`/`worker` são
44
- endpoints isentos. Pegou o `release-auditor` (executável, sem rota) na primeira execução. Mesma
45
- classe dos checks acima, aplicada a quem-orquestra-quem.
46
-
47
- Princípios:
48
-
49
- - **Scanner puro, checks finos.** `doc-graph.mjs` lê e devolve dados (`scanCommands`, `scanLinks`,
50
- `projectCommands`); os checks julgam. Testar o parsing — a parte difícil — não exige montar o
51
- ambiente do doctor.
52
- - **Allowlist derivada, jamais literal.** Os comandos do projeto *gerado* (`start:dev`, `test:e2e`,
53
- `memory:db:*`) não são do Forja e não podem reprovar. A allowlist deriva de **duas** fontes: os
54
- blocos `"scripts"` inline dos geradores **e** os `package.json` dos boilerplates. Foi `test:e2e`
55
- — que vive no boilerplate, não no gerador — que provou que uma fonte só produz falso positivo. Uma
56
- lista manual mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
57
- - **Escopo = instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
58
- `.claude/agents/` e os `.md` de raiz. **Fora**: `boilerplates/` (conteúdo do projeto gerado),
59
- `specs/` e `memory/90-*` (registro histórico — uma spec ou ADR pode legitimamente citar um comando
60
- proposto ou já removido). O gate protege o que instrui o agente *agora*.
61
- - **`:` como discriminador de comando.** Cobre 42/42 do registry e nenhuma prosa (`"forja does X"`)
62
- casa por acidente. Inventar parser de gramática para um comando-sem-`:` inexistente seria criar o
63
- problema que não temos.
64
- - **Severidade honesta.** Só `docs-commands` é crítico. Comando não-documentado e link quebrado
65
- atrapalham, não impedem — `warn`. Um gate que reprova o que não trava é um gate que se aprende a
66
- ignorar.
67
-
68
- ## Alternativas consideradas
69
-
70
- - **Manter a auditoria manual** — rejeitada: ela apaga sintomas, não fecha a classe. Reincide na
71
- próxima renomeação.
72
- - **Lista literal de comandos do projeto gerado** — rejeitada: é a armadilha do `.gitignore` da
73
- SPEC-009. Uma lista que não acompanha o gerador vira mentira.
74
- - **Parsear markdown com um lexer de CommonMark** — rejeitada: peso morto. Precisamos de citações e
75
- links, não de um AST. Regex + o discriminador `:` bastam.
76
- - **Gerar a doc a partir do registry** — rejeitada: doc gerada por máquina descreve o *quê*, nunca o
77
- *porquê*, e o porquê é o que importa. O gate cobra que a explicação exista; não escreve por você.
78
- - **Escanear `specs/` e `memory/` também** — rejeitada: são registro histórico. Reprovar um ADR por
79
- citar um comando já removido puniria a memória por lembrar.
80
-
81
- ## Consequências
82
-
83
- **Positivas**:
84
- - Renomear um comando vira **ato detectável**: a doc que ficou para trás reprova o CI (o
85
- `tools:doctor` já é step, ADR-0024) — não espera a próxima auditoria manual.
86
- - Os quatro comandos-fantasma e os 22 links quebrados da auditoria manual viram zero, verificado a
87
- cada CI. `memory:extract` (o único órfão) passou a ser documentado.
88
- - O gate pegou o **próprio autor**: ao corrigir os links, um erro de profundidade relativa
89
- (`../../` vs `../../../`) foi detectado na hora, antes do commit. É a prova de que ele mede o que
90
- deve.
91
-
92
- **Negativas / Trade-offs**:
93
- - Análise estática conservadora: o `:` como discriminador deixaria escapar um futuro comando sem
94
- `:`. Aceito — nenhum existe, e falso negativo raro é melhor que falso positivo crítico.
95
- - Os checks leem todos os `.md` de instrução a cada `tools:doctor`. Barato hoje (< 1s); se crescer,
96
- vira lazy por mtime. São `scope: repo`, fora do `SessionStart`.
97
-
98
- ## Rastreamento
99
-
100
- - Implementação: `lib/core/doc-graph.mjs`, `lib/core/health.mjs` (checks `docs-commands`,
101
- `commands-documented`, `docs-links`), `test/doc-graph.test.js`, `test/health.test.js`
102
- - Spec: `specs/coerencia-do-sistema/` (SPEC-011)
103
- - ADRs relacionadas: ADR-0023 (gate do núcleo) e ADR-0024 (gate do tarball) — a mesma família, agora
104
- na terceira fronteira: a instrução. ADR-0021 (a classe "erra sem avisar"). ADR-0020 (registry como
105
- fonte da verdade dos comandos).
1
+ # ADR-0025: Coerência da documentação como gate
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-18
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: governance, docs, harness, diagnostics, registry
7
+
8
+ ## Contexto
9
+
10
+ Os ADRs 0023 e 0024 fecharam a classe "erra sem avisar" (ADR-0021) no **núcleo** e no **tarball**.
11
+ Faltava a fronteira mais barata de corromper e a mais cara de perceber: a **palavra escrita**.
12
+
13
+ O Forja é operado por agentes que leem a documentação e executam o que ela manda. Quando a doc e o
14
+ código divergem, o agente não erra por burrice — erra por **obediência**. Uma auditoria manual em
15
+ 2026-07-14 encontrou, entre outras coisas:
16
+
17
+ - `docs/token-optimization.md` — o documento que ensina a economia de tokens (ADR-0009) — mandava
18
+ rodar **quatro comandos que não existem** (`context:build`, `memory:db:reindex`, …) e linkava um
19
+ `docs/DEPLOYMENT.md` que nunca existiu.
20
+ - O Governance descrevia `tools:doctor` pela definição anterior ao ADR-0023.
21
+ - Comandos do registry sem menção em lugar nenhum — capacidade obscura é capacidade morta.
22
+
23
+ Nada disso quebrava um teste nem aparecia no `git status`. A correção manual apagou os sintomas do
24
+ dia; nada impedia a reincidência. Toda vez que um comando é renomeado ou um gate muda de contrato, a
25
+ doc pode silenciosamente passar a mentir.
26
+
27
+ ## Decisão
28
+
29
+ Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanner puro
30
+ `lib/core/doc-graph.mjs` que lê os `.md` de instrução como dado:
31
+
32
+ - **`docs-commands`** (critical): todo `forja <cmd>` / `npm run <cmd>` citado numa superfície de
33
+ instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
34
+ - **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
35
+ - **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
36
+ - **`adr-refs`** (warn, adicionado depois): toda citação `ADR-NNNN` em doc/spec/ADR aponta para um
37
+ ADR que existe. Fecha o último invariante que vivia por disciplina ("toda decisão vira ADR") pelo
38
+ lado verificável: referência a decisão inexistente é trilha que apodrece. Pegou o `ADR-0026`
39
+ pendurado (citado pela SPEC-012, nunca escrito) na primeira execução.
40
+ - **`agent-topology`** (warn, SPEC-019): a topologia de orquestração é descrita em três fontes
41
+ (`VALID_AGENTS` do router, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio — o
42
+ namesake do framework (orquestração multiagente) vivendo por disciplina. O check cruza as três:
43
+ sub-agent sem rota, papel roteável sem executor, agente não documentado. `user`/`worker` são
44
+ endpoints isentos. Pegou o `release-auditor` (executável, sem rota) na primeira execução. Mesma
45
+ classe dos checks acima, aplicada a quem-orquestra-quem.
46
+
47
+ Princípios:
48
+
49
+ - **Scanner puro, checks finos.** `doc-graph.mjs` lê e devolve dados (`scanCommands`, `scanLinks`,
50
+ `projectCommands`); os checks julgam. Testar o parsing — a parte difícil — não exige montar o
51
+ ambiente do doctor.
52
+ - **Allowlist derivada, jamais literal.** Os comandos do projeto *gerado* (`start:dev`, `test:e2e`,
53
+ `memory:db:*`) não são do Forja e não podem reprovar. A allowlist deriva de **duas** fontes: os
54
+ blocos `"scripts"` inline dos geradores **e** os `package.json` dos boilerplates. Foi `test:e2e`
55
+ — que vive no boilerplate, não no gerador — que provou que uma fonte só produz falso positivo. Uma
56
+ lista manual mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
57
+ - **Escopo = instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
58
+ `.claude/agents/` e os `.md` de raiz. **Fora**: `boilerplates/` (conteúdo do projeto gerado),
59
+ `specs/` e `memory/90-*` (registro histórico — uma spec ou ADR pode legitimamente citar um comando
60
+ proposto ou já removido). O gate protege o que instrui o agente *agora*.
61
+ - **`:` como discriminador de comando.** Cobre 42/42 do registry e nenhuma prosa (`"forja does X"`)
62
+ casa por acidente. Inventar parser de gramática para um comando-sem-`:` inexistente seria criar o
63
+ problema que não temos.
64
+ - **Severidade honesta.** Só `docs-commands` é crítico. Comando não-documentado e link quebrado
65
+ atrapalham, não impedem — `warn`. Um gate que reprova o que não trava é um gate que se aprende a
66
+ ignorar.
67
+
68
+ ## Alternativas consideradas
69
+
70
+ - **Manter a auditoria manual** — rejeitada: ela apaga sintomas, não fecha a classe. Reincide na
71
+ próxima renomeação.
72
+ - **Lista literal de comandos do projeto gerado** — rejeitada: é a armadilha do `.gitignore` da
73
+ SPEC-009. Uma lista que não acompanha o gerador vira mentira.
74
+ - **Parsear markdown com um lexer de CommonMark** — rejeitada: peso morto. Precisamos de citações e
75
+ links, não de um AST. Regex + o discriminador `:` bastam.
76
+ - **Gerar a doc a partir do registry** — rejeitada: doc gerada por máquina descreve o *quê*, nunca o
77
+ *porquê*, e o porquê é o que importa. O gate cobra que a explicação exista; não escreve por você.
78
+ - **Escanear `specs/` e `memory/` também** — rejeitada: são registro histórico. Reprovar um ADR por
79
+ citar um comando já removido puniria a memória por lembrar.
80
+
81
+ ## Consequências
82
+
83
+ **Positivas**:
84
+ - Renomear um comando vira **ato detectável**: a doc que ficou para trás reprova o CI (o
85
+ `tools:doctor` já é step, ADR-0024) — não espera a próxima auditoria manual.
86
+ - Os quatro comandos-fantasma e os 22 links quebrados da auditoria manual viram zero, verificado a
87
+ cada CI. `memory:extract` (o único órfão) passou a ser documentado.
88
+ - O gate pegou o **próprio autor**: ao corrigir os links, um erro de profundidade relativa
89
+ (`../../` vs `../../../`) foi detectado na hora, antes do commit. É a prova de que ele mede o que
90
+ deve.
91
+
92
+ **Negativas / Trade-offs**:
93
+ - Análise estática conservadora: o `:` como discriminador deixaria escapar um futuro comando sem
94
+ `:`. Aceito — nenhum existe, e falso negativo raro é melhor que falso positivo crítico.
95
+ - Os checks leem todos os `.md` de instrução a cada `tools:doctor`. Barato hoje (< 1s); se crescer,
96
+ vira lazy por mtime. São `scope: repo`, fora do `SessionStart`.
97
+
98
+ ## Rastreamento
99
+
100
+ - Implementação: `lib/core/doc-graph.mjs`, `lib/core/health.mjs` (checks `docs-commands`,
101
+ `commands-documented`, `docs-links`), `test/doc-graph.test.js`, `test/health.test.js`
102
+ - Spec: `specs/coerencia-do-sistema/` (SPEC-011)
103
+ - ADRs relacionadas: ADR-0023 (gate do núcleo) e ADR-0024 (gate do tarball) — a mesma família, agora
104
+ na terceira fronteira: a instrução. ADR-0021 (a classe "erra sem avisar"). ADR-0020 (registry como
105
+ fonte da verdade dos comandos).
@@ -1,66 +1,66 @@
1
- # ADR-0026: Migração TypeScript com runtime duplo (fonte `.ts`, publicado `dist/`)
2
-
3
- - **Status**: accepted
4
- - **Data**: 2026-07-19
5
- - **Autor(es)**: apk
6
- - **Tags**: typescript, build, runtime, sdd
7
-
8
- ## Contexto
9
-
10
- A SPEC-012 migrou o framework de `.mjs`/checkJs para TypeScript de verdade. Dois requisitos em
11
- tensão organizaram todas as decisões:
12
-
13
- - **NFR inegociável**: o dev roda `sem build`. `node bin/forja.ts <cmd>` tem que funcionar direto,
14
- ou o loop de desenvolvimento morre.
15
- - **`engines.node >= 20`**: o pacote publicado precisa rodar em Node 20/21, que **não** executam
16
- `.ts` (strip-types nativo só existe a partir do Node 22.6).
17
-
18
- Essas duas verdades não cabem no mesmo artefato: no instante em que a fonte vira `.ts`, um pacote
19
- publicado sem compilar quebra para quem está em Node 20.
20
-
21
- ## Decisão
22
-
23
- **Runtime duplo, resolvido por um único ponto.**
24
-
25
- 1. **D1 — Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
26
- `dist/lib`, `dist/scripts`. Não movemos a fonte para `src/`: trocaria todo import, path de
27
- registry e hook — blast radius enorme, contra o "verde contínuo".
28
- 2. **D2 — Registry + `resolveScript` (o coração).** O registry nomeia os scripts; o `resolveScript`
29
- tenta as extensões na ordem `['.ts', '.js', '.mjs']`, fazendo strip da extensão declarada. Em dev
30
- acha o `.ts`; no publicado acha o `dist/*.js`. Um resolver, dois mundos — sem dois registries
31
- (a divergência que a SPEC-009 matou).
32
- 3. **D3 — Dual runtime.** Dev roda `.ts` nativo (Node ≥22.6, exigência de contribuir); o publicado
33
- embarca `dist/*.js` (Node ≥20). O acoplamento de Node-floor vive só na fronteira do publicado.
34
- 4. **D4 (revisado) — o gate constrói o `dist/`.** O `release:check` roda `npm run build` **antes de
35
- empacotar** (quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
36
- empacota o mesmo disco recém-buildado, o tarball provado é o publicado — sem `dist/` no git, sem
37
- step de build no `ci.yml`, sem janela de staleness. O gate é self-contained.
38
- 5. **D9 — publicar `dist/` desde sempre desacopla o risco.** Enquanto a fonte ainda era `.mjs`, o
39
- build era uma cópia; quando virou `.ts`, virou compilação. Em ambos os casos o publicado é JS
40
- runnable, então o `.ts`-não-roda-em-Node-20 nunca morde o usuário final.
41
-
42
- ## Alternativas consideradas
43
-
44
- - **Guardar `.js` compilado no git e exigir build em dev** — rejeitada: mata o NFR "roda sem build".
45
- - **Publicar a fonte `.ts` crua** — rejeitada: quebra em Node 20/21; o `release:check` reprovaria.
46
- - **Dois registries (dev/publicado)** — rejeitada: duas verdades que divergem (defeito da SPEC-009).
47
- - **Mover a fonte para `src/`** — rejeitada: blast radius desproporcional para ganho estético.
48
-
49
- ## Consequências
50
-
51
- **Positivas**:
52
- - Dev roda `.ts` nativo, zero build; usuário final roda `dist/*.js`, Node ≥20. Cada um paga só o seu.
53
- - Uma máquina (`resolveScript`) resolve os dois mundos; o gate prova o tarball real.
54
- - `noImplicitAny` ligado ao fim: o ratchet força todo código futuro a ser tipado.
55
-
56
- **Negativas / Trade-offs**:
57
- - Contribuir passa a exigir Node ≥22.6; o job `test` do CI cai fora do Node 20 (o suporte a 20 do
58
- publicado é provado pelo `release-gate`, que instala o tarball `.js`).
59
- - O `resolveScript` carrega três extensões por dívida histórica (`.mjs` legado) — barato, mas é
60
- estado que um dia se limpa.
61
-
62
- ## Rastreamento
63
- - Spec: `specs/ts-migration/` (SPEC-012)
64
- - Implementação: `lib/core/registry.ts` (resolveScript), `lib/core/release.ts` (gate builda),
65
- `tsconfig.json` / `tsconfig.build.json`, `.github/workflows/ci.yml`
66
- - ADRs relacionadas: ADR-0021 (NFR "roda sem build"; classe "dist mente"), ADR-0024 (gate do tarball)
1
+ # ADR-0026: Migração TypeScript com runtime duplo (fonte `.ts`, publicado `dist/`)
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-19
5
+ - **Autor(es)**: apk
6
+ - **Tags**: typescript, build, runtime, sdd
7
+
8
+ ## Contexto
9
+
10
+ A SPEC-012 migrou o framework de `.mjs`/checkJs para TypeScript de verdade. Dois requisitos em
11
+ tensão organizaram todas as decisões:
12
+
13
+ - **NFR inegociável**: o dev roda `sem build`. `node bin/forja.ts <cmd>` tem que funcionar direto,
14
+ ou o loop de desenvolvimento morre.
15
+ - **`engines.node >= 20`**: o pacote publicado precisa rodar em Node 20/21, que **não** executam
16
+ `.ts` (strip-types nativo só existe a partir do Node 22.6).
17
+
18
+ Essas duas verdades não cabem no mesmo artefato: no instante em que a fonte vira `.ts`, um pacote
19
+ publicado sem compilar quebra para quem está em Node 20.
20
+
21
+ ## Decisão
22
+
23
+ **Runtime duplo, resolvido por um único ponto.**
24
+
25
+ 1. **D1 — Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
26
+ `dist/lib`, `dist/scripts`. Não movemos a fonte para `src/`: trocaria todo import, path de
27
+ registry e hook — blast radius enorme, contra o "verde contínuo".
28
+ 2. **D2 — Registry + `resolveScript` (o coração).** O registry nomeia os scripts; o `resolveScript`
29
+ tenta as extensões na ordem `['.ts', '.js', '.mjs']`, fazendo strip da extensão declarada. Em dev
30
+ acha o `.ts`; no publicado acha o `dist/*.js`. Um resolver, dois mundos — sem dois registries
31
+ (a divergência que a SPEC-009 matou).
32
+ 3. **D3 — Dual runtime.** Dev roda `.ts` nativo (Node ≥22.6, exigência de contribuir); o publicado
33
+ embarca `dist/*.js` (Node ≥20). O acoplamento de Node-floor vive só na fronteira do publicado.
34
+ 4. **D4 (revisado) — o gate constrói o `dist/`.** O `release:check` roda `npm run build` **antes de
35
+ empacotar** (quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
36
+ empacota o mesmo disco recém-buildado, o tarball provado é o publicado — sem `dist/` no git, sem
37
+ step de build no `ci.yml`, sem janela de staleness. O gate é self-contained.
38
+ 5. **D9 — publicar `dist/` desde sempre desacopla o risco.** Enquanto a fonte ainda era `.mjs`, o
39
+ build era uma cópia; quando virou `.ts`, virou compilação. Em ambos os casos o publicado é JS
40
+ runnable, então o `.ts`-não-roda-em-Node-20 nunca morde o usuário final.
41
+
42
+ ## Alternativas consideradas
43
+
44
+ - **Guardar `.js` compilado no git e exigir build em dev** — rejeitada: mata o NFR "roda sem build".
45
+ - **Publicar a fonte `.ts` crua** — rejeitada: quebra em Node 20/21; o `release:check` reprovaria.
46
+ - **Dois registries (dev/publicado)** — rejeitada: duas verdades que divergem (defeito da SPEC-009).
47
+ - **Mover a fonte para `src/`** — rejeitada: blast radius desproporcional para ganho estético.
48
+
49
+ ## Consequências
50
+
51
+ **Positivas**:
52
+ - Dev roda `.ts` nativo, zero build; usuário final roda `dist/*.js`, Node ≥20. Cada um paga só o seu.
53
+ - Uma máquina (`resolveScript`) resolve os dois mundos; o gate prova o tarball real.
54
+ - `noImplicitAny` ligado ao fim: o ratchet força todo código futuro a ser tipado.
55
+
56
+ **Negativas / Trade-offs**:
57
+ - Contribuir passa a exigir Node ≥22.6; o job `test` do CI cai fora do Node 20 (o suporte a 20 do
58
+ publicado é provado pelo `release-gate`, que instala o tarball `.js`).
59
+ - O `resolveScript` carrega três extensões por dívida histórica (`.mjs` legado) — barato, mas é
60
+ estado que um dia se limpa.
61
+
62
+ ## Rastreamento
63
+ - Spec: `specs/ts-migration/` (SPEC-012)
64
+ - Implementação: `lib/core/registry.ts` (resolveScript), `lib/core/release.ts` (gate builda),
65
+ `tsconfig.json` / `tsconfig.build.json`, `.github/workflows/ci.yml`
66
+ - ADRs relacionadas: ADR-0021 (NFR "roda sem build"; classe "dist mente"), ADR-0024 (gate do tarball)
@@ -1,127 +1,127 @@
1
- # ADR-0027: Boilerplate Clean Architecture calibrada
2
-
3
- - **Status**: accepted
4
- - **Data**: 2026-07-18
5
- - **Autor(es)**: Allan Pablo
6
- - **Tags**: boilerplate, ddd, clean-architecture, token-economy
7
-
8
- ## Contexto
9
-
10
- Os boilerplates do Forja eram NestJS-flat: o `service` fala direto com a entity do ORM, a regra de
11
- negócio fica diluída no service acoplada ao framework. Dois preços — manutenção (testar regra exige
12
- subir o Nest; trocar ORM é cirurgia) e **tokens** (ADR-0009): um agente precisa ler a implementação
13
- inteira para entender uma feature, porque não há contrato legível separado da execução.
14
-
15
- A resposta ingênua — "aplicar Clean Architecture" — tem o preço oposto: quatro camadas para um CRUD
16
- são mais arquivos para ler, não menos. Cargo-cult de arquitetura é o anti-padrão de token com nome
17
- bonito.
18
-
19
- ## Decisão
20
-
21
- Um boilerplate (`boilerplates/06-clean-arch`) que demonstra **os dois padrões lado a lado**:
22
-
23
- - **Fatia rica (Orders)**: 4 camadas (domain / application / infrastructure / presentation) com
24
- inversão de dependência. Invariantes de negócio (não envia sem pagamento; total derivado; máquina
25
- de estados) vivem no domínio, em TypeScript puro — **zero `@nestjs`, zero ORM**. Testáveis sem
26
- subir o Nest.
27
- - **Caminho enxuto (Products)**: CRUD numa camada, controller→repo direto, sem use-case nem porta.
28
- - **`WHEN-CLEAN-WHEN-LEAN.md`**: o critério de qual padrão usar. É o coração — a calibração é a
29
- decisão, não as camadas.
30
- - **Memória por bounded context** (`memory/30-domains/<ctx>/context.md`): a linguagem ubíqua que o
31
- agente lê antes do código.
32
-
33
- Inversão via DI do Nest: a porta é `interface` no domínio + token; o adapter a implementa; o módulo
34
- faz o bind numa linha. O domínio e a aplicação não sabem que TypeORM existe.
35
-
36
- ## A medição de token — honesta (o que a spec exigiu)
37
-
38
- A SPEC-013 fez da economia de token a métrica-norte e mandou **reconhecer se não cair, não maquiar**.
39
- Então:
40
-
41
- Medida crua (bytes/4) do custo de "ler o domínio para editar uma regra":
42
-
43
- | | tokens aprox. |
44
- |---|---|
45
- | Clean-arch: `context.md` (476) + `order.entity.ts` (690) | **~1167** |
46
- | Flat 02-saas: `billing.service.ts` (486) + `invoice.entity.ts` (244) | **~730** |
47
-
48
- **Na contagem crua, Clean-arch não ganha — é maior.** E a comparação é injusta: o domínio de Orders
49
- tem máquina de estados e invariantes reais; o service de billing é fino. Estamos comparando lógica
50
- rica com lógica pobre, não arquitetura com arquitetura.
51
-
52
- **Onde o benefício de token realmente está** (e o que a medida crua não captura):
53
-
54
- 1. **Localização.** Para editar uma regra em Clean-arch, o agente lê o `context.md` (que aponta
55
- "a regra está em `order.entity.ts`") e o agregado — e **não carrega** infraestrutura, controller
56
- nem use-cases. No flat, a regra está no service misturada a acesso a dados; para ter certeza de
57
- achar toda a lógica, o agente varre mais.
58
- 2. **O `context.md` como mapa.** 476 tokens lidos primeiro que substituem exploração. No flat não há
59
- mapa: o agente greps/lê para descobrir onde a regra vive.
60
- 3. **Ler assinatura, não implementação.** Para *entender* (não editar), o `context.md` + a assinatura
61
- do use-case bastam; no flat, lê-se o service.
62
-
63
- **Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
64
- não de tamanho de arquivo. A medida crua feita aqui é um proxy fraco e **não prova** a economia. A
65
- prova rigorosa precisa do benchmark sobre uma **mesma tarefa**, com a mesma feature nas duas
66
- arquiteturas — o boilerplate flat não tinha um equivalente rico ao Order, então ficou como follow-up.
67
-
68
- ### Follow-up resolvido — o benchmark same-feature (`forja token:economy`)
69
-
70
- A dívida acima foi fechada: existe um `benchmarks/clean-vs-flat/orders-flat/` (a MESMA feature —
71
- place + ship + "não envia sem pagamento" — no estilo flat) e o comando `token:economy` mede **dois
72
- eixos**, porque a economia de token do Forja tem dois eixos e eles são diferentes:
73
-
74
- **Eixo 1 — arquitetura (clean vs flat).** Desmente a versão ingênua da claim:
75
-
76
- | Cenário | Clean | Flat | Clean vs flat |
77
- |---|---|---|---|
78
- | Entender a feature inteira | ~3684 tok (12 arq.) | ~1298 tok (3 arq.) | **+184%** |
79
- | Mudar a regra de envio (contexto mínimo) | ~1419 tok (3 arq.) | ~910 tok (1 arq.) | **+56%** |
80
-
81
- Para uma feature pequena, **o clean-arch custa MAIS tokens** — inclusive na mudança localizada. A
82
- camada cobra adiantado e, com dois casos de uso, não se paga. **A justificativa de `orders` em
83
- camadas passa a ser isolamento e testabilidade, não token.**
84
-
85
- **Eixo 2 — memória (frio vs quente).** É aqui que a economia real do framework mora (ADR-0009):
86
-
87
- | Cenário | Quente (com `context.md`) | Frio (sem mapa) | Economia |
88
- |---|---|---|---|
89
- | Localizar e mexer numa regra da fatia | ~1419 tok (3 arq.) | ~3684 tok (12 arq.) | **−61%** |
90
-
91
- O `context.md` é o mapa: com ele, o agente vai direto ao agregado + à máquina de estados; sem ele,
92
- varre a fatia inteira para descobrir onde a regra vive. **E essa economia COMPÕE**: gerar do zero é
93
- custo único (o scaffold), mas o mapa poupa a cada tarefa futura, pela vida do projeto. O
94
- `token:economy` não mede o custo de gerar — mede o regime permanente, depois do projeto levantado.
95
-
96
- Conclusão corrigida: a economia de token do Forja **não é das camadas — é da memória persistente**,
97
- amortizada no tempo. As camadas se pagam só a partir de certa escala (tamanho da feature × nº de
98
- casos de uso); a memória se paga desde a segunda tarefa. Tudo reproduzível: `forja token:economy`.
99
-
100
- ## Alternativas consideradas
101
-
102
- - **Clean Architecture em tudo** — rejeitada: é o cargo-cult que a calibração existe para evitar. O
103
- `WHEN-CLEAN-WHEN-LEAN.md` + o Products enxuto são o guardrail.
104
- - **Clean Architecture no framework Forja** — rejeitada (fora do escopo da SPEC-013): over-engineering
105
- para um CLI. O framework ganha só modelos de domínio tipados, ride na migração TS (SPEC-012).
106
- - **Refatorar os boilerplates 01-05** — rejeitada: aditivo, não migração. Os flat servem o CRUD.
107
-
108
- ## Consequências
109
-
110
- **Positivas**:
111
- - Um esqueleto onde a regra de negócio é isolada, testável sem framework, e sobrevive a troca de ORM.
112
- - A calibração é **visível em código** (Orders rico vs. Products enxuto), não só documentada.
113
- - O guardrail contra token-bloat é explícito e reprovável (o Products *tem* que ser 1 camada).
114
-
115
- **Negativas / Trade-offs**:
116
- - A economia de token **não está provada** — está argumentada (navegacional) e medida cruamente com
117
- resultado inconclusivo. O benchmark real é follow-up. Registrar isto é a honestidade que a spec
118
- cobrou; claim de vitória não-medida seria maquiar.
119
- - Mais conceitos para o dev absorver na fatia rica. Mitigado: uma fatia rica só; o resto enxuto.
120
-
121
- ## Rastreamento
122
-
123
- - Implementação: `boilerplates/06-clean-arch/`
124
- - Spec: `specs/clean-arch-boilerplate/` (SPEC-013)
125
- - ADRs relacionadas: ADR-0009 (economia de tokens — a métrica-norte), ADR-0001 (memória por contexto),
126
- ADR-0016 (harness), SPEC-012 (TS — o domínio tipado)
127
- - **Follow-up**: benchmark `context:smart` de uma tarefa-tipo, mesma feature nas duas arquiteturas.
1
+ # ADR-0027: Boilerplate Clean Architecture calibrada
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-18
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: boilerplate, ddd, clean-architecture, token-economy
7
+
8
+ ## Contexto
9
+
10
+ Os boilerplates do Forja eram NestJS-flat: o `service` fala direto com a entity do ORM, a regra de
11
+ negócio fica diluída no service acoplada ao framework. Dois preços — manutenção (testar regra exige
12
+ subir o Nest; trocar ORM é cirurgia) e **tokens** (ADR-0009): um agente precisa ler a implementação
13
+ inteira para entender uma feature, porque não há contrato legível separado da execução.
14
+
15
+ A resposta ingênua — "aplicar Clean Architecture" — tem o preço oposto: quatro camadas para um CRUD
16
+ são mais arquivos para ler, não menos. Cargo-cult de arquitetura é o anti-padrão de token com nome
17
+ bonito.
18
+
19
+ ## Decisão
20
+
21
+ Um boilerplate (`boilerplates/06-clean-arch`) que demonstra **os dois padrões lado a lado**:
22
+
23
+ - **Fatia rica (Orders)**: 4 camadas (domain / application / infrastructure / presentation) com
24
+ inversão de dependência. Invariantes de negócio (não envia sem pagamento; total derivado; máquina
25
+ de estados) vivem no domínio, em TypeScript puro — **zero `@nestjs`, zero ORM**. Testáveis sem
26
+ subir o Nest.
27
+ - **Caminho enxuto (Products)**: CRUD numa camada, controller→repo direto, sem use-case nem porta.
28
+ - **`WHEN-CLEAN-WHEN-LEAN.md`**: o critério de qual padrão usar. É o coração — a calibração é a
29
+ decisão, não as camadas.
30
+ - **Memória por bounded context** (`memory/30-domains/<ctx>/context.md`): a linguagem ubíqua que o
31
+ agente lê antes do código.
32
+
33
+ Inversão via DI do Nest: a porta é `interface` no domínio + token; o adapter a implementa; o módulo
34
+ faz o bind numa linha. O domínio e a aplicação não sabem que TypeORM existe.
35
+
36
+ ## A medição de token — honesta (o que a spec exigiu)
37
+
38
+ A SPEC-013 fez da economia de token a métrica-norte e mandou **reconhecer se não cair, não maquiar**.
39
+ Então:
40
+
41
+ Medida crua (bytes/4) do custo de "ler o domínio para editar uma regra":
42
+
43
+ | | tokens aprox. |
44
+ |---|---|
45
+ | Clean-arch: `context.md` (476) + `order.entity.ts` (690) | **~1167** |
46
+ | Flat 02-saas: `billing.service.ts` (486) + `invoice.entity.ts` (244) | **~730** |
47
+
48
+ **Na contagem crua, Clean-arch não ganha — é maior.** E a comparação é injusta: o domínio de Orders
49
+ tem máquina de estados e invariantes reais; o service de billing é fino. Estamos comparando lógica
50
+ rica com lógica pobre, não arquitetura com arquitetura.
51
+
52
+ **Onde o benefício de token realmente está** (e o que a medida crua não captura):
53
+
54
+ 1. **Localização.** Para editar uma regra em Clean-arch, o agente lê o `context.md` (que aponta
55
+ "a regra está em `order.entity.ts`") e o agregado — e **não carrega** infraestrutura, controller
56
+ nem use-cases. No flat, a regra está no service misturada a acesso a dados; para ter certeza de
57
+ achar toda a lógica, o agente varre mais.
58
+ 2. **O `context.md` como mapa.** 476 tokens lidos primeiro que substituem exploração. No flat não há
59
+ mapa: o agente greps/lê para descobrir onde a regra vive.
60
+ 3. **Ler assinatura, não implementação.** Para *entender* (não editar), o `context.md` + a assinatura
61
+ do use-case bastam; no flat, lê-se o service.
62
+
63
+ **Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
64
+ não de tamanho de arquivo. A medida crua feita aqui é um proxy fraco e **não prova** a economia. A
65
+ prova rigorosa precisa do benchmark sobre uma **mesma tarefa**, com a mesma feature nas duas
66
+ arquiteturas — o boilerplate flat não tinha um equivalente rico ao Order, então ficou como follow-up.
67
+
68
+ ### Follow-up resolvido — o benchmark same-feature (`forja token:economy`)
69
+
70
+ A dívida acima foi fechada: existe um `benchmarks/clean-vs-flat/orders-flat/` (a MESMA feature —
71
+ place + ship + "não envia sem pagamento" — no estilo flat) e o comando `token:economy` mede **dois
72
+ eixos**, porque a economia de token do Forja tem dois eixos e eles são diferentes:
73
+
74
+ **Eixo 1 — arquitetura (clean vs flat).** Desmente a versão ingênua da claim:
75
+
76
+ | Cenário | Clean | Flat | Clean vs flat |
77
+ |---|---|---|---|
78
+ | Entender a feature inteira | ~3684 tok (12 arq.) | ~1298 tok (3 arq.) | **+184%** |
79
+ | Mudar a regra de envio (contexto mínimo) | ~1419 tok (3 arq.) | ~910 tok (1 arq.) | **+56%** |
80
+
81
+ Para uma feature pequena, **o clean-arch custa MAIS tokens** — inclusive na mudança localizada. A
82
+ camada cobra adiantado e, com dois casos de uso, não se paga. **A justificativa de `orders` em
83
+ camadas passa a ser isolamento e testabilidade, não token.**
84
+
85
+ **Eixo 2 — memória (frio vs quente).** É aqui que a economia real do framework mora (ADR-0009):
86
+
87
+ | Cenário | Quente (com `context.md`) | Frio (sem mapa) | Economia |
88
+ |---|---|---|---|
89
+ | Localizar e mexer numa regra da fatia | ~1419 tok (3 arq.) | ~3684 tok (12 arq.) | **−61%** |
90
+
91
+ O `context.md` é o mapa: com ele, o agente vai direto ao agregado + à máquina de estados; sem ele,
92
+ varre a fatia inteira para descobrir onde a regra vive. **E essa economia COMPÕE**: gerar do zero é
93
+ custo único (o scaffold), mas o mapa poupa a cada tarefa futura, pela vida do projeto. O
94
+ `token:economy` não mede o custo de gerar — mede o regime permanente, depois do projeto levantado.
95
+
96
+ Conclusão corrigida: a economia de token do Forja **não é das camadas — é da memória persistente**,
97
+ amortizada no tempo. As camadas se pagam só a partir de certa escala (tamanho da feature × nº de
98
+ casos de uso); a memória se paga desde a segunda tarefa. Tudo reproduzível: `forja token:economy`.
99
+
100
+ ## Alternativas consideradas
101
+
102
+ - **Clean Architecture em tudo** — rejeitada: é o cargo-cult que a calibração existe para evitar. O
103
+ `WHEN-CLEAN-WHEN-LEAN.md` + o Products enxuto são o guardrail.
104
+ - **Clean Architecture no framework Forja** — rejeitada (fora do escopo da SPEC-013): over-engineering
105
+ para um CLI. O framework ganha só modelos de domínio tipados, ride na migração TS (SPEC-012).
106
+ - **Refatorar os boilerplates 01-05** — rejeitada: aditivo, não migração. Os flat servem o CRUD.
107
+
108
+ ## Consequências
109
+
110
+ **Positivas**:
111
+ - Um esqueleto onde a regra de negócio é isolada, testável sem framework, e sobrevive a troca de ORM.
112
+ - A calibração é **visível em código** (Orders rico vs. Products enxuto), não só documentada.
113
+ - O guardrail contra token-bloat é explícito e reprovável (o Products *tem* que ser 1 camada).
114
+
115
+ **Negativas / Trade-offs**:
116
+ - A economia de token **não está provada** — está argumentada (navegacional) e medida cruamente com
117
+ resultado inconclusivo. O benchmark real é follow-up. Registrar isto é a honestidade que a spec
118
+ cobrou; claim de vitória não-medida seria maquiar.
119
+ - Mais conceitos para o dev absorver na fatia rica. Mitigado: uma fatia rica só; o resto enxuto.
120
+
121
+ ## Rastreamento
122
+
123
+ - Implementação: `boilerplates/06-clean-arch/`
124
+ - Spec: `specs/clean-arch-boilerplate/` (SPEC-013)
125
+ - ADRs relacionadas: ADR-0009 (economia de tokens — a métrica-norte), ADR-0001 (memória por contexto),
126
+ ADR-0016 (harness), SPEC-012 (TS — o domínio tipado)
127
+ - **Follow-up**: benchmark `context:smart` de uma tarefa-tipo, mesma feature nas duas arquiteturas.