forjajs 2.0.2 → 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 (712) 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 -317
  21. package/README.pt-BR.md +345 -323
  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/apps/server/src/main.d.ts +3 -2
  329. package/dist/apps/server/src/main.js +8 -6
  330. package/dist/bin/create-memory-nest-kit.js +17 -17
  331. package/dist/bin/forja.js +22 -5
  332. package/dist/bin/init-project.js +38 -38
  333. package/dist/lib/audit.js +7 -7
  334. package/dist/lib/context-builder.js +32 -32
  335. package/dist/lib/core/doc-graph.js +6 -4
  336. package/dist/lib/core/registry.d.ts +64 -0
  337. package/dist/lib/core/registry.js +65 -0
  338. package/dist/lib/core/release.d.ts +63 -0
  339. package/dist/lib/core/release.js +5 -1
  340. package/dist/lib/generators/memory-generator.js +700 -698
  341. package/dist/lib/generators/nest-generator.js +398 -398
  342. package/dist/lib/generators/readme-generator.js +180 -180
  343. package/dist/lib/governance-report.js +39 -39
  344. package/dist/lib/project-upgrade.js +1 -1
  345. package/dist/lib/workspace.d.ts +7 -0
  346. package/dist/lib/workspace.js +63 -34
  347. package/dist/packages/adapter-git/src/index.d.ts +2 -0
  348. package/dist/packages/adapter-git/src/index.js +22 -1
  349. package/dist/packages/adapter-sqlite/src/index.js +12 -12
  350. package/dist/packages/contracts/src/index.d.ts +1 -1
  351. package/dist/packages/llm/src/index.d.ts +43 -0
  352. package/dist/packages/llm/src/index.js +108 -0
  353. package/dist/packages/plugin-docker/src/index.d.ts +3 -0
  354. package/dist/packages/plugin-docker/src/index.js +13 -0
  355. package/dist/packages/plugin-github/src/index.d.ts +3 -0
  356. package/dist/packages/plugin-github/src/index.js +13 -0
  357. package/dist/packages/sandbox/src/index.d.ts +2 -0
  358. package/dist/packages/sandbox/src/index.js +10 -0
  359. package/dist/scripts/agent-harness.js +66 -64
  360. package/dist/scripts/agent-router.js +20 -20
  361. package/dist/scripts/build-smart-context.js +22 -22
  362. package/dist/scripts/compress-memory.js +8 -8
  363. package/dist/scripts/context-benchmark.d.ts +2 -0
  364. package/dist/scripts/context-benchmark.js +39 -0
  365. package/dist/scripts/context-ops.js +29 -29
  366. package/dist/scripts/demo-autonomy.d.ts +15 -0
  367. package/dist/scripts/demo-autonomy.js +200 -0
  368. package/dist/scripts/demo-workspace.d.ts +6 -0
  369. package/dist/scripts/demo-workspace.js +101 -0
  370. package/dist/scripts/dev.js +13 -13
  371. package/dist/scripts/extract-global-knowledge.js +5 -5
  372. package/dist/scripts/generate-dashboard.js +11 -11
  373. package/dist/scripts/llm-fit.d.ts +1 -0
  374. package/dist/scripts/llm-fit.js +131 -0
  375. package/dist/scripts/memory-schema.js +48 -48
  376. package/dist/scripts/query-universal-memory.js +13 -13
  377. package/dist/scripts/sprint-manager.js +39 -39
  378. package/dist/scripts/sync-universal-memory.js +63 -50
  379. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  380. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -132
  381. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  382. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  383. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  384. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -0
  385. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -0
  386. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -0
  387. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -0
  388. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -0
  389. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  390. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  391. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  392. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  393. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  394. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  395. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  396. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  397. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  398. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  399. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  400. package/docs/agent-harnesses.md +149 -149
  401. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  402. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  403. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  404. package/docs/archive/FASE2-SUMMARY.md +263 -263
  405. package/docs/archive/FASE3-PROGRESS.md +355 -355
  406. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  407. package/docs/archive/INDICE-MASTER.md +282 -282
  408. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  409. package/docs/archive/README-REFINAMENTO.md +293 -293
  410. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  411. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  412. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  413. package/docs/archive/START-HERE.md +319 -319
  414. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  415. package/docs/archive/examples/v1/AGENTS.md +10 -10
  416. package/docs/archive/examples/v1/README.md +36 -36
  417. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  418. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  419. package/docs/archive/examples/v1/backend/package.json +42 -42
  420. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  421. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  422. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  423. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  424. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  425. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  426. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  427. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  428. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  429. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  430. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  431. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  432. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  433. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  434. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  435. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  436. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  437. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  438. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  439. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  440. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  441. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  442. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  443. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  444. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  445. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  446. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  447. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  448. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  449. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  450. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  451. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  452. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  453. package/docs/archive/examples/v2/AGENTS.md +16 -16
  454. package/docs/archive/examples/v2/README.md +35 -35
  455. package/docs/archive/examples/v2/agents/README.md +3 -3
  456. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  457. package/docs/archive/examples/v2/agents/dba.md +4 -4
  458. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  459. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  460. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  461. package/docs/archive/examples/v2/agents/security.md +4 -4
  462. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  463. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  464. package/docs/archive/examples/v2/backend/package.json +42 -42
  465. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  466. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  467. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  468. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  469. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  470. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  471. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  472. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  473. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  474. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  475. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  476. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  477. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  478. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  479. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  480. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  481. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  482. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  483. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  484. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  485. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  486. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  487. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  488. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  489. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  490. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  491. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  492. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  493. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  494. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  495. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  496. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  497. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  498. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  499. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  500. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  501. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  502. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  503. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  504. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  505. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  506. package/docs/archive/examples/v2/memory/README.md +8 -8
  507. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  508. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  509. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  510. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  511. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  512. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  513. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  514. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  515. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  516. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  517. package/docs/capacidades-externas.md +86 -86
  518. package/docs/cli-first-operacao.md +74 -74
  519. package/docs/dev-workflow.md +421 -421
  520. package/docs/examples.md +546 -546
  521. package/docs/fluxo.md +103 -103
  522. package/docs/glossary.md +453 -453
  523. package/docs/init-project.md +457 -457
  524. package/docs/llm-fit-loop.md +41 -0
  525. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  526. package/docs/modos-de-operacao.md +52 -0
  527. package/docs/personas/architect/README.md +333 -333
  528. package/docs/personas/developer/README.md +371 -371
  529. package/docs/personas/executive/README.md +172 -172
  530. package/docs/personas/qa/README.md +350 -350
  531. package/docs/processo-projeto.md +138 -138
  532. package/docs/produto/factsheet-marketing.md +151 -0
  533. package/docs/produto/roteiro-demo.md +47 -0
  534. package/docs/publishing.md +377 -377
  535. package/docs/quick-reference.md +409 -409
  536. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  537. package/docs/structure.md +360 -360
  538. package/docs/token-optimization.md +502 -502
  539. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  540. package/memory/00-global/mission.md +15 -15
  541. package/memory/00-global/shared-knowledge.md +8 -8
  542. package/memory/00-global/standards.md +47 -47
  543. package/memory/10-product/personas.md +21 -21
  544. package/memory/10-product/vision.md +27 -27
  545. package/memory/30-projects/README.md +15 -15
  546. package/memory/40-delivery/backlog.md +15 -15
  547. package/memory/40-delivery/current-sprint.md +23 -26
  548. package/memory/50-orchestration/gsd-harness.md +55 -55
  549. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  550. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  551. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  552. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  553. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  554. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  555. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  556. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  557. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  558. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  559. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  560. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  561. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  562. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  563. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  564. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  565. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  566. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  567. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  568. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  569. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  570. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  571. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  572. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  573. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  574. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  575. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  576. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -0
  577. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  578. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  579. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  580. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  581. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  582. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  583. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  584. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  585. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -0
  586. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -0
  587. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -0
  588. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -0
  589. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  590. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  591. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  592. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  593. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  594. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  595. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  596. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  597. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  598. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  599. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  600. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  601. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  602. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  603. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  604. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  605. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  606. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  607. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  608. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  609. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  610. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  611. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  612. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  613. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  614. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  615. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  616. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  617. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  618. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  619. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  620. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  621. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  622. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  623. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  624. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  625. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  626. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  627. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  628. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  629. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  630. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  631. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  632. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  633. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  634. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  635. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  636. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  637. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  638. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  639. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  640. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  641. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  642. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  643. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  644. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  645. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  646. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  647. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  648. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  649. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  650. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  651. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  652. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  653. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -0
  654. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -0
  655. package/memory/90-decisions/0071-server-persistence-composition.md +12 -0
  656. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -0
  657. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -0
  658. package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
  659. package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
  660. package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
  661. package/memory/90-decisions/_template.md +28 -28
  662. package/package.json +157 -140
  663. package/prompts/context-engineer-agent.md +19 -19
  664. package/prompts/governance-agent.md +16 -16
  665. package/prompts/marketing-agent.md +13 -13
  666. package/prompts/orchestrator-agent.md +18 -18
  667. package/prompts/product-agent.md +13 -13
  668. package/prompts/sdd-architect-agent.md +20 -20
  669. package/specs/README.md +70 -70
  670. package/specs/_templates/plan.md +43 -43
  671. package/specs/_templates/spec.md +43 -43
  672. package/specs/_templates/tasks.md +32 -32
  673. package/specs/clean-arch-boilerplate/plan.md +137 -137
  674. package/specs/clean-arch-boilerplate/spec.md +121 -121
  675. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  676. package/specs/cli-first-operacao/plan.md +53 -53
  677. package/specs/cli-first-operacao/spec.md +53 -53
  678. package/specs/cli-first-operacao/tasks.md +53 -53
  679. package/specs/code-context/spec.md +56 -56
  680. package/specs/coerencia-do-sistema/plan.md +155 -155
  681. package/specs/coerencia-do-sistema/spec.md +123 -123
  682. package/specs/coerencia-do-sistema/tasks.md +115 -115
  683. package/specs/dev-token-assets-db/plan.md +71 -71
  684. package/specs/dev-token-assets-db/spec.md +58 -58
  685. package/specs/dev-token-assets-db/tasks.md +58 -58
  686. package/specs/doctor-do-nucleo/plan.md +165 -165
  687. package/specs/doctor-do-nucleo/spec.md +139 -139
  688. package/specs/doctor-do-nucleo/tasks.md +172 -172
  689. package/specs/forja-core/spec.md +71 -71
  690. package/specs/gates/spec.md +63 -63
  691. package/specs/governanca-visivel/plan.md +122 -122
  692. package/specs/governanca-visivel/spec.md +112 -112
  693. package/specs/governanca-visivel/tasks.md +60 -60
  694. package/specs/harness-codegraph/spec.md +71 -71
  695. package/specs/memory-audit/spec.md +54 -54
  696. package/specs/orchestrate/spec.md +108 -108
  697. package/specs/orchestration-coherent/spec.md +95 -95
  698. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  699. package/specs/project-smoke/spec.md +96 -96
  700. package/specs/project-upgrade/spec.md +58 -58
  701. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  702. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  703. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  704. package/specs/release-auditor-health/plan.md +88 -0
  705. package/specs/release-auditor-health/spec.md +82 -0
  706. package/specs/release-auditor-health/tasks.md +72 -0
  707. package/specs/release-gate/plan.md +174 -174
  708. package/specs/release-gate/spec.md +122 -122
  709. package/specs/release-gate/tasks.md +183 -183
  710. package/specs/ts-migration/plan.md +200 -200
  711. package/specs/ts-migration/spec.md +119 -119
  712. package/specs/ts-migration/tasks.md +110 -110
@@ -1,502 +1,502 @@
1
- # 🎯 Token Optimization Guide
2
-
3
- **Target**: 40-60% reduction in tokens per agent session through smart context, caching, and compression.
4
-
5
- ## Hooks ativos (ADR-0009)
6
-
7
- | Hook | Quando dispara | O que faz |
8
- |---|---|---|
9
- | `SessionStart` → `scripts/hook-session-start.mjs` | Início da sessão Claude Code | Injeta status de specs e handoffs abertos (`additionalContext`) |
10
- | `UserPromptSubmit` → `scripts/hook-user-prompt.mjs` | A cada prompt do usuário | **Opt-in**: só roda com `FRAMEWORK_HOOK_INJECT=1` e prompt casando triggers (`implement`, `refactor`, `spec:`, …). Cache TTL 30min |
11
- | `pre-commit` (passos 6-7) | Antes de cada commit | `spec:check` + `check-standards`; bloqueia se inconsistente |
12
-
13
- Para ativar a injeção automática de smart-context:
14
-
15
- ```bash
16
- export FRAMEWORK_HOOK_INJECT=1
17
- ```
18
-
19
- Caps em `.memoryrc.json::hooks.userPromptCap` (default 4KB). Cache em `/tmp/framework-hook-cache/`.
20
-
21
- ---
22
-
23
- ## 📊 Current State Analysis
24
-
25
- ### Baseline Metrics (Before Optimization)
26
-
27
- | Metric | Value | Impact |
28
- |--------|-------|--------|
29
- | Average context size | 150-200 KB | High token cost |
30
- | Files loaded per session | 30-50 | Redundant data |
31
- | Cache hit rate | 0% | No reuse |
32
- | Database size | 2.1 MB | Includes old logs |
33
- | Compression | None | No optimization |
34
-
35
- ### Target After Optimization
36
-
37
- | Metric | Current | Target | Savings |
38
- |--------|---------|--------|---------|
39
- | Context size | 150 KB | 60 KB | 60% ✅ |
40
- | Files loaded | 40 | 15-20 | 50% |
41
- | Cache hit rate | 0% | 70% | - |
42
- | Database size | 2.1 MB | < 1 MB | 50% |
43
- | Token cost | $0.015 | $0.006 | 60% ✅ |
44
-
45
- ---
46
-
47
- ## 🔧 3-Mode Context Strategy
48
-
49
- ### Mode 1: Global (Fastest - 2KB, ~500 tokens)
50
-
51
- **Use case**: Startup, configuration decisions, standards
52
-
53
- **Loads**:
54
- - `mission.md` — Project mission
55
- - `standards.md` — Code/doc standards
56
- - `ADR-*` — Last 3 architecture decisions
57
- - `.memoryrc.json` — Config
58
-
59
- **Cost**: $0.0001 per request
60
-
61
- ```bash
62
- node lib/context-builder.js global my-project
63
- ```
64
-
65
- ---
66
-
67
- ### Mode 2: Domain (Standard - 20KB, ~5000 tokens)
68
-
69
- **Use case**: Feature development, architectural work
70
-
71
- **Loads**:
72
- - All from **Global**
73
- - `vision.md` — Product vision
74
- - `design-md/INDEX.md` — Design decisions
75
- - `rules.md` — Business rules
76
- - `[domain]/api.md` — Domain-specific API
77
- - Recent `summary.md` files
78
-
79
- **Cost**: $0.005 per request
80
-
81
- ```bash
82
- node lib/context-builder.js domain my-project
83
- ```
84
-
85
- ---
86
-
87
- ### Mode 3: Task (Optimized - 30-40KB, ~8000 tokens)
88
-
89
- **Use case**: Specific features, debugging, handoffs
90
-
91
- **Loads**:
92
- - All from **Domain**
93
- - FTS5 search results for keyword
94
- - Deduplicates overlaps
95
- - Prunes unused sections
96
-
97
- **Cost**: $0.008 per request
98
-
99
- ```bash
100
- node lib/context-builder.js task my-project "auth backend"
101
- ```
102
-
103
- ---
104
-
105
- ## 🧠 Smart Context - How It Works
106
-
107
- ```
108
- ┌─────────────────────────────────────┐
109
- │ User Query: "Implement JWT auth" │
110
- └────────────┬────────────────────────┘
111
- │
112
- ▼
113
- ┌─────────────────────────────────────┐
114
- │ 1. Parse keyword: "JWT", "auth" │
115
- └────────────┬────────────────────────┘
116
- │
117
- ▼
118
- ┌─────────────────────────────────────┐
119
- │ 2. Check cache: Hit? → Return │
120
- │ Miss? → Continue │
121
- └────────────┬────────────────────────┘
122
- │
123
- ▼
124
- ┌─────────────────────────────────────┐
125
- │ 3. FTS5 search in memory_nodes │
126
- │ Find: auth-service, jwt-spec, │
127
- │ security-adr, etc (10 files) │
128
- └────────────┬────────────────────────┘
129
- │
130
- ▼
131
- ┌─────────────────────────────────────┐
132
- │ 4. Add domain + global context │
133
- │ Total: ~20 files (deduped) │
134
- └────────────┬────────────────────────┘
135
- │
136
- ▼
137
- ┌─────────────────────────────────────┐
138
- │ 5. Rank by relevance + recency │
139
- │ Keep top 15 (by token budget) │
140
- └────────────┬────────────────────────┘
141
- │
142
- ▼
143
- ┌─────────────────────────────────────┐
144
- │ 6. Generate markdown + cache │
145
- │ ~30KB context (8000 tokens) │
146
- └────────────┬────────────────────────┘
147
- │
148
- ▼
149
- ┌─────────────────────────────────────┐
150
- │ 7. Send to agent (from cache ✅) │
151
- └─────────────────────────────────────┘
152
- ```
153
-
154
- ---
155
-
156
- ## 📦 Compression Strategy
157
-
158
- ### Step 1: Archive Old Logs (30 days)
159
-
160
- ```bash
161
- npm run memory:vacuum
162
- ```
163
-
164
- **What happens**:
165
- - Logs > 30 days moved to `.memory/archive/`
166
- - Deleted from active DB
167
- - Database VACUUM'd
168
-
169
- **Expected savings**: 30-40% of DB size
170
-
171
- ### Step 2: Clean Cache (7-day TTL)
172
-
173
- ```bash
174
- node scripts/compress-memory.mjs
175
- ```
176
-
177
- **What happens**:
178
- - Expired cache files deleted
179
- - Empty nodes removed
180
- - Index rebuilt
181
-
182
- **Expected savings**: 20-30% more
183
-
184
- ### Step 3: Optimize Memory Runs
185
-
186
- **Manual audit**:
187
- ```bash
188
- # Find biggest runs
189
- du -sh .memory/runs/* | sort -h | tail -10
190
-
191
- # Archive manually if needed
192
- mv .memory/runs/old-run-* .memory/archive/
193
- ```
194
-
195
- ---
196
-
197
- ## 💾 Configuration (.memoryrc.json)
198
-
199
- ### Set Token Limits
200
-
201
- ```json
202
- {
203
- "tokenLimits": {
204
- "global": 2000,
205
- "domain": 5000,
206
- "task": 8000,
207
- "buffer": 500
208
- }
209
- }
210
- ```
211
-
212
- ### Compression Settings
213
-
214
- ```json
215
- {
216
- "compression": {
217
- "archiveAge": 30,
218
- "maxDbSize": 50,
219
- "cacheTtl": 7,
220
- "vacuumInterval": 86400000
221
- }
222
- }
223
- ```
224
-
225
- ### Cache Strategy
226
-
227
- ```json
228
- {
229
- "context": {
230
- "cache": {
231
- "enabled": true,
232
- "ttl": 604800000,
233
- "location": ".context/cache",
234
- "strategy": "lru"
235
- }
236
- }
237
- }
238
- ```
239
-
240
- ---
241
-
242
- ## 📈 Benchmarking
243
-
244
- ### Run Benchmark
245
-
246
- ```bash
247
- npm run token:benchmark
248
- ```
249
-
250
- **What it does**:
251
- 1. Generate all 3 context modes
252
- 2. Measure size, token count, generation time
253
- 3. Compare with baseline
254
- 4. Report savings %
255
-
256
- **Output example**:
257
- ```
258
- 📊 Token Economy Benchmark
259
-
260
- Mode: global
261
- Size: 2.1 KB
262
- Tokens: 525
263
- Time: 45ms
264
-
265
- Mode: domain
266
- Size: 18.5 KB
267
- Tokens: 4625
268
- Time: 120ms
269
-
270
- Mode: task (keyword: "auth")
271
- Size: 31.2 KB
272
- Tokens: 7800
273
- Time: 180ms
274
-
275
- Summary:
276
- ✅ 52% reduction vs original (full context)
277
- ✅ 70% cache hit rate
278
- ✅ Average generation: 115ms
279
- 💰 Cost savings: $0.009/request
280
- ```
281
-
282
- ---
283
-
284
- ## 🎯 Optimization Techniques
285
-
286
- ### 1. Deduplication
287
-
288
- **Problem**: Same files loaded in multiple modes.
289
-
290
- **Solution**:
291
- ```javascript
292
- const seenPaths = new Set();
293
- for (const node of nodes) {
294
- if (seenPaths.has(node.path)) continue; // Skip
295
- seenPaths.add(node.path);
296
- // Add to context
297
- }
298
- ```
299
-
300
- **Savings**: 20-30%
301
-
302
- ---
303
-
304
- ### 2. Priority Weighting
305
-
306
- **Problem**: Not all files equally important.
307
-
308
- **Solution**:
309
- ```javascript
310
- const priorities = {
311
- 'mission.md': 10,
312
- 'vision.md': 8,
313
- 'rules.md': 6,
314
- 'design-md/': 5,
315
- 'implementation/': 2
316
- };
317
- ```
318
-
319
- **Savings**: 15-25%
320
-
321
- ---
322
-
323
- ### 3. Time Decay
324
-
325
- **Problem**: Old files still included equally.
326
-
327
- **Solution**:
328
- ```javascript
329
- const age = (now - node.updatedAt) / (1000 * 60 * 60 * 24); // days
330
- const weight = Math.exp(-age / 30); // Decay over 30 days
331
- if (weight < 0.1) skip(); // Drop very old files
332
- ```
333
-
334
- **Savings**: 10-20%
335
-
336
- ---
337
-
338
- ### 4. Relevance Ranking
339
-
340
- **Problem**: FTS5 results not always ranked best.
341
-
342
- **Solution**:
343
- ```javascript
344
- const relevanceScore =
345
- (titleMatch * 3) +
346
- (contentMatch * 1) +
347
- (recencyBoost * 0.5) +
348
- (domainMatch * 2);
349
-
350
- nodes.sort((a, b) => b.score - a.score);
351
- nodes = nodes.slice(0, maxFiles); // Keep top N
352
- ```
353
-
354
- **Savings**: 25-40%
355
-
356
- ---
357
-
358
- ## 🚀 Integration with Agent Workflow
359
-
360
- ### For Backend Worker
361
-
362
- ```javascript
363
- import ContextBuilder from '../lib/context-builder.js';
364
-
365
- // On task start
366
- const builder = new ContextBuilder(process.cwd(), dbPath);
367
- const context = builder.build('task', 'my-project', 'backend auth');
368
- const stats = builder.stats('task', 'my-project', 'backend auth');
369
-
370
- console.log(`📊 Using ${stats.tokens} tokens (cost: $${stats.estimatedCost})`);
371
-
372
- // Send context to agent
373
- await agent.exec(task, context);
374
-
375
- builder.close();
376
- ```
377
-
378
- ### For Frontend Worker
379
-
380
- ```javascript
381
- // More domain-focused
382
- const context = builder.build('domain', 'my-project');
383
- ```
384
-
385
- ### For Orchestrator
386
-
387
- ```javascript
388
- // Global context only (faster handoff)
389
- const context = builder.build('global', 'my-project');
390
- ```
391
-
392
- ---
393
-
394
- ## 📋 Pre-Flight Checklist
395
-
396
- - [ ] `.memoryrc.json` created with token limits
397
- - [ ] `lib/context-builder.js` integrated
398
- - [ ] `scripts/compress-memory.mjs` tested
399
- - [ ] Cache directory created: `.context/cache/`
400
- - [ ] Archive directory created: `.memory/archive/`
401
- - [ ] FTS5 index enabled in universal.db
402
- - [ ] Benchmark run: `npm run token:benchmark`
403
- - [ ] Savings > 40%? Deploy!
404
-
405
- ---
406
-
407
- ## 🎓 Common Patterns
408
-
409
- ### Scenario 1: Feature Development
410
-
411
- ```bash
412
- # Developer needs feature context
413
- npm run context:smart -- task my-project "payment feature"
414
- # Uses cached domain + task-specific files
415
- # Result: ~30KB, ~7500 tokens, $0.0075
416
- ```
417
-
418
- ### Scenario 2: Security Review
419
-
420
- ```bash
421
- # Security agent needs all related context
422
- npm run context:smart -- domain my-project
423
- # Adds security rules, ADRs, design docs
424
- # Result: ~20KB, ~5000 tokens, $0.005
425
- ```
426
-
427
- ### Scenario 3: Onboarding New Developer
428
-
429
- ```bash
430
- # New dev needs big picture
431
- npm run context:smart -- global my-project
432
- # Just mission, standards, recent ADRs
433
- # Result: ~2KB, ~500 tokens, $0.0005
434
- ```
435
-
436
- ---
437
-
438
- ## 📞 Troubleshooting
439
-
440
- ### Context Too Large?
441
-
442
- ```bash
443
- # Try smaller mode
444
- npm run context:smart -- global # Instead of domain
445
-
446
- # Or prune manually
447
- npm run memory:compress
448
- npm run memory:vacuum
449
- ```
450
-
451
- ### FTS5 Queries Slow or Stale?
452
-
453
- ```bash
454
- # Rebuild the index (it is also what fixes a stale index)
455
- npm run sync:universal
456
-
457
- # The doctor tells you when the index is behind memory/ — it is the
458
- # failure that costs the most and shows the least (ADR-0023).
459
- npm run tools:doctor
460
- ```
461
-
462
- ### Cache Not Working?
463
-
464
- ```bash
465
- # Clear cache
466
- rm -rf .context/cache
467
-
468
- # Verify cache enabled in .memoryrc.json
469
- cat .memoryrc.json | grep cache -A 5
470
- ```
471
-
472
- ---
473
-
474
- ## 📚 Related Commands
475
-
476
- Todos passam pelo core (`bin/forja.mjs`, ADR-0020). Se um comando não está aqui, ele está no
477
- registry — `node bin/forja.mjs` lista todos.
478
-
479
- ```bash
480
- # Buscar antes de ler: é o primeiro passo da economia de tokens (ADR-0009)
481
- npm run query:universal "auth"
482
-
483
- # Montar o pacote de contexto mínimo-suficiente (global | domain | task)
484
- npm run context:smart -- task my-project "payment feature"
485
-
486
- # Reindexar a memória — também é o que corrige um índice defasado
487
- npm run sync:universal
488
-
489
- # Comprimir memória antiga e recuperar espaço
490
- npm run memory:compress
491
- npm run memory:vacuum
492
-
493
- # Medir a economia
494
- npm run token:benchmark
495
-
496
- # Índice defasado responde sobre memória velha, calado. O doctor avisa (ADR-0023)
497
- npm run tools:doctor
498
- ```
499
-
500
- ---
501
-
502
- **Próximo**: [`docs/agent-harnesses.md`](agent-harnesses.md) — os gates e as ferramentas de processo.
1
+ # 🎯 Token Optimization Guide
2
+
3
+ **Target**: 40-60% reduction in tokens per agent session through smart context, caching, and compression.
4
+
5
+ ## Hooks ativos (ADR-0009)
6
+
7
+ | Hook | Quando dispara | O que faz |
8
+ |---|---|---|
9
+ | `SessionStart` → `scripts/hook-session-start.mjs` | Início da sessão Claude Code | Injeta status de specs e handoffs abertos (`additionalContext`) |
10
+ | `UserPromptSubmit` → `scripts/hook-user-prompt.mjs` | A cada prompt do usuário | **Opt-in**: só roda com `FRAMEWORK_HOOK_INJECT=1` e prompt casando triggers (`implement`, `refactor`, `spec:`, …). Cache TTL 30min |
11
+ | `pre-commit` (passos 6-7) | Antes de cada commit | `spec:check` + `check-standards`; bloqueia se inconsistente |
12
+
13
+ Para ativar a injeção automática de smart-context:
14
+
15
+ ```bash
16
+ export FRAMEWORK_HOOK_INJECT=1
17
+ ```
18
+
19
+ Caps em `.memoryrc.json::hooks.userPromptCap` (default 4KB). Cache em `/tmp/framework-hook-cache/`.
20
+
21
+ ---
22
+
23
+ ## 📊 Current State Analysis
24
+
25
+ ### Baseline Metrics (Before Optimization)
26
+
27
+ | Metric | Value | Impact |
28
+ |--------|-------|--------|
29
+ | Average context size | 150-200 KB | High token cost |
30
+ | Files loaded per session | 30-50 | Redundant data |
31
+ | Cache hit rate | 0% | No reuse |
32
+ | Database size | 2.1 MB | Includes old logs |
33
+ | Compression | None | No optimization |
34
+
35
+ ### Target After Optimization
36
+
37
+ | Metric | Current | Target | Savings |
38
+ |--------|---------|--------|---------|
39
+ | Context size | 150 KB | 60 KB | 60% ✅ |
40
+ | Files loaded | 40 | 15-20 | 50% |
41
+ | Cache hit rate | 0% | 70% | - |
42
+ | Database size | 2.1 MB | < 1 MB | 50% |
43
+ | Token cost | $0.015 | $0.006 | 60% ✅ |
44
+
45
+ ---
46
+
47
+ ## 🔧 3-Mode Context Strategy
48
+
49
+ ### Mode 1: Global (Fastest - 2KB, ~500 tokens)
50
+
51
+ **Use case**: Startup, configuration decisions, standards
52
+
53
+ **Loads**:
54
+ - `mission.md` — Project mission
55
+ - `standards.md` — Code/doc standards
56
+ - `ADR-*` — Last 3 architecture decisions
57
+ - `.memoryrc.json` — Config
58
+
59
+ **Cost**: $0.0001 per request
60
+
61
+ ```bash
62
+ node lib/context-builder.js global my-project
63
+ ```
64
+
65
+ ---
66
+
67
+ ### Mode 2: Domain (Standard - 20KB, ~5000 tokens)
68
+
69
+ **Use case**: Feature development, architectural work
70
+
71
+ **Loads**:
72
+ - All from **Global**
73
+ - `vision.md` — Product vision
74
+ - `design-md/INDEX.md` — Design decisions
75
+ - `rules.md` — Business rules
76
+ - `[domain]/api.md` — Domain-specific API
77
+ - Recent `summary.md` files
78
+
79
+ **Cost**: $0.005 per request
80
+
81
+ ```bash
82
+ node lib/context-builder.js domain my-project
83
+ ```
84
+
85
+ ---
86
+
87
+ ### Mode 3: Task (Optimized - 30-40KB, ~8000 tokens)
88
+
89
+ **Use case**: Specific features, debugging, handoffs
90
+
91
+ **Loads**:
92
+ - All from **Domain**
93
+ - FTS5 search results for keyword
94
+ - Deduplicates overlaps
95
+ - Prunes unused sections
96
+
97
+ **Cost**: $0.008 per request
98
+
99
+ ```bash
100
+ node lib/context-builder.js task my-project "auth backend"
101
+ ```
102
+
103
+ ---
104
+
105
+ ## 🧠 Smart Context - How It Works
106
+
107
+ ```
108
+ ┌─────────────────────────────────────┐
109
+ │ User Query: "Implement JWT auth" │
110
+ └────────────┬────────────────────────┘
111
+ │
112
+ ▼
113
+ ┌─────────────────────────────────────┐
114
+ │ 1. Parse keyword: "JWT", "auth" │
115
+ └────────────┬────────────────────────┘
116
+ │
117
+ ▼
118
+ ┌─────────────────────────────────────┐
119
+ │ 2. Check cache: Hit? → Return │
120
+ │ Miss? → Continue │
121
+ └────────────┬────────────────────────┘
122
+ │
123
+ ▼
124
+ ┌─────────────────────────────────────┐
125
+ │ 3. FTS5 search in memory_nodes │
126
+ │ Find: auth-service, jwt-spec, │
127
+ │ security-adr, etc (10 files) │
128
+ └────────────┬────────────────────────┘
129
+ │
130
+ ▼
131
+ ┌─────────────────────────────────────┐
132
+ │ 4. Add domain + global context │
133
+ │ Total: ~20 files (deduped) │
134
+ └────────────┬────────────────────────┘
135
+ │
136
+ ▼
137
+ ┌─────────────────────────────────────┐
138
+ │ 5. Rank by relevance + recency │
139
+ │ Keep top 15 (by token budget) │
140
+ └────────────┬────────────────────────┘
141
+ │
142
+ ▼
143
+ ┌─────────────────────────────────────┐
144
+ │ 6. Generate markdown + cache │
145
+ │ ~30KB context (8000 tokens) │
146
+ └────────────┬────────────────────────┘
147
+ │
148
+ ▼
149
+ ┌─────────────────────────────────────┐
150
+ │ 7. Send to agent (from cache ✅) │
151
+ └─────────────────────────────────────┘
152
+ ```
153
+
154
+ ---
155
+
156
+ ## 📦 Compression Strategy
157
+
158
+ ### Step 1: Archive Old Logs (30 days)
159
+
160
+ ```bash
161
+ npm run memory:vacuum
162
+ ```
163
+
164
+ **What happens**:
165
+ - Logs > 30 days moved to `.memory/archive/`
166
+ - Deleted from active DB
167
+ - Database VACUUM'd
168
+
169
+ **Expected savings**: 30-40% of DB size
170
+
171
+ ### Step 2: Clean Cache (7-day TTL)
172
+
173
+ ```bash
174
+ node scripts/compress-memory.mjs
175
+ ```
176
+
177
+ **What happens**:
178
+ - Expired cache files deleted
179
+ - Empty nodes removed
180
+ - Index rebuilt
181
+
182
+ **Expected savings**: 20-30% more
183
+
184
+ ### Step 3: Optimize Memory Runs
185
+
186
+ **Manual audit**:
187
+ ```bash
188
+ # Find biggest runs
189
+ du -sh .memory/runs/* | sort -h | tail -10
190
+
191
+ # Archive manually if needed
192
+ mv .memory/runs/old-run-* .memory/archive/
193
+ ```
194
+
195
+ ---
196
+
197
+ ## 💾 Configuration (.memoryrc.json)
198
+
199
+ ### Set Token Limits
200
+
201
+ ```json
202
+ {
203
+ "tokenLimits": {
204
+ "global": 2000,
205
+ "domain": 5000,
206
+ "task": 8000,
207
+ "buffer": 500
208
+ }
209
+ }
210
+ ```
211
+
212
+ ### Compression Settings
213
+
214
+ ```json
215
+ {
216
+ "compression": {
217
+ "archiveAge": 30,
218
+ "maxDbSize": 50,
219
+ "cacheTtl": 7,
220
+ "vacuumInterval": 86400000
221
+ }
222
+ }
223
+ ```
224
+
225
+ ### Cache Strategy
226
+
227
+ ```json
228
+ {
229
+ "context": {
230
+ "cache": {
231
+ "enabled": true,
232
+ "ttl": 604800000,
233
+ "location": ".context/cache",
234
+ "strategy": "lru"
235
+ }
236
+ }
237
+ }
238
+ ```
239
+
240
+ ---
241
+
242
+ ## 📈 Benchmarking
243
+
244
+ ### Run Benchmark
245
+
246
+ ```bash
247
+ npm run token:benchmark
248
+ ```
249
+
250
+ **What it does**:
251
+ 1. Generate all 3 context modes
252
+ 2. Measure size, token count, generation time
253
+ 3. Compare with baseline
254
+ 4. Report savings %
255
+
256
+ **Output example**:
257
+ ```
258
+ 📊 Token Economy Benchmark
259
+
260
+ Mode: global
261
+ Size: 2.1 KB
262
+ Tokens: 525
263
+ Time: 45ms
264
+
265
+ Mode: domain
266
+ Size: 18.5 KB
267
+ Tokens: 4625
268
+ Time: 120ms
269
+
270
+ Mode: task (keyword: "auth")
271
+ Size: 31.2 KB
272
+ Tokens: 7800
273
+ Time: 180ms
274
+
275
+ Summary:
276
+ ✅ 52% reduction vs original (full context)
277
+ ✅ 70% cache hit rate
278
+ ✅ Average generation: 115ms
279
+ 💰 Cost savings: $0.009/request
280
+ ```
281
+
282
+ ---
283
+
284
+ ## 🎯 Optimization Techniques
285
+
286
+ ### 1. Deduplication
287
+
288
+ **Problem**: Same files loaded in multiple modes.
289
+
290
+ **Solution**:
291
+ ```javascript
292
+ const seenPaths = new Set();
293
+ for (const node of nodes) {
294
+ if (seenPaths.has(node.path)) continue; // Skip
295
+ seenPaths.add(node.path);
296
+ // Add to context
297
+ }
298
+ ```
299
+
300
+ **Savings**: 20-30%
301
+
302
+ ---
303
+
304
+ ### 2. Priority Weighting
305
+
306
+ **Problem**: Not all files equally important.
307
+
308
+ **Solution**:
309
+ ```javascript
310
+ const priorities = {
311
+ 'mission.md': 10,
312
+ 'vision.md': 8,
313
+ 'rules.md': 6,
314
+ 'design-md/': 5,
315
+ 'implementation/': 2
316
+ };
317
+ ```
318
+
319
+ **Savings**: 15-25%
320
+
321
+ ---
322
+
323
+ ### 3. Time Decay
324
+
325
+ **Problem**: Old files still included equally.
326
+
327
+ **Solution**:
328
+ ```javascript
329
+ const age = (now - node.updatedAt) / (1000 * 60 * 60 * 24); // days
330
+ const weight = Math.exp(-age / 30); // Decay over 30 days
331
+ if (weight < 0.1) skip(); // Drop very old files
332
+ ```
333
+
334
+ **Savings**: 10-20%
335
+
336
+ ---
337
+
338
+ ### 4. Relevance Ranking
339
+
340
+ **Problem**: FTS5 results not always ranked best.
341
+
342
+ **Solution**:
343
+ ```javascript
344
+ const relevanceScore =
345
+ (titleMatch * 3) +
346
+ (contentMatch * 1) +
347
+ (recencyBoost * 0.5) +
348
+ (domainMatch * 2);
349
+
350
+ nodes.sort((a, b) => b.score - a.score);
351
+ nodes = nodes.slice(0, maxFiles); // Keep top N
352
+ ```
353
+
354
+ **Savings**: 25-40%
355
+
356
+ ---
357
+
358
+ ## 🚀 Integration with Agent Workflow
359
+
360
+ ### For Backend Worker
361
+
362
+ ```javascript
363
+ import ContextBuilder from '../lib/context-builder.js';
364
+
365
+ // On task start
366
+ const builder = new ContextBuilder(process.cwd(), dbPath);
367
+ const context = builder.build('task', 'my-project', 'backend auth');
368
+ const stats = builder.stats('task', 'my-project', 'backend auth');
369
+
370
+ console.log(`📊 Using ${stats.tokens} tokens (cost: $${stats.estimatedCost})`);
371
+
372
+ // Send context to agent
373
+ await agent.exec(task, context);
374
+
375
+ builder.close();
376
+ ```
377
+
378
+ ### For Frontend Worker
379
+
380
+ ```javascript
381
+ // More domain-focused
382
+ const context = builder.build('domain', 'my-project');
383
+ ```
384
+
385
+ ### For Orchestrator
386
+
387
+ ```javascript
388
+ // Global context only (faster handoff)
389
+ const context = builder.build('global', 'my-project');
390
+ ```
391
+
392
+ ---
393
+
394
+ ## 📋 Pre-Flight Checklist
395
+
396
+ - [ ] `.memoryrc.json` created with token limits
397
+ - [ ] `lib/context-builder.js` integrated
398
+ - [ ] `scripts/compress-memory.mjs` tested
399
+ - [ ] Cache directory created: `.context/cache/`
400
+ - [ ] Archive directory created: `.memory/archive/`
401
+ - [ ] FTS5 index enabled in universal.db
402
+ - [ ] Benchmark run: `npm run token:benchmark`
403
+ - [ ] Savings > 40%? Deploy!
404
+
405
+ ---
406
+
407
+ ## 🎓 Common Patterns
408
+
409
+ ### Scenario 1: Feature Development
410
+
411
+ ```bash
412
+ # Developer needs feature context
413
+ npm run context:smart -- task my-project "payment feature"
414
+ # Uses cached domain + task-specific files
415
+ # Result: ~30KB, ~7500 tokens, $0.0075
416
+ ```
417
+
418
+ ### Scenario 2: Security Review
419
+
420
+ ```bash
421
+ # Security agent needs all related context
422
+ npm run context:smart -- domain my-project
423
+ # Adds security rules, ADRs, design docs
424
+ # Result: ~20KB, ~5000 tokens, $0.005
425
+ ```
426
+
427
+ ### Scenario 3: Onboarding New Developer
428
+
429
+ ```bash
430
+ # New dev needs big picture
431
+ npm run context:smart -- global my-project
432
+ # Just mission, standards, recent ADRs
433
+ # Result: ~2KB, ~500 tokens, $0.0005
434
+ ```
435
+
436
+ ---
437
+
438
+ ## 📞 Troubleshooting
439
+
440
+ ### Context Too Large?
441
+
442
+ ```bash
443
+ # Try smaller mode
444
+ npm run context:smart -- global # Instead of domain
445
+
446
+ # Or prune manually
447
+ npm run memory:compress
448
+ npm run memory:vacuum
449
+ ```
450
+
451
+ ### FTS5 Queries Slow or Stale?
452
+
453
+ ```bash
454
+ # Rebuild the index (it is also what fixes a stale index)
455
+ npm run sync:universal
456
+
457
+ # The doctor tells you when the index is behind memory/ — it is the
458
+ # failure that costs the most and shows the least (ADR-0023).
459
+ npm run tools:doctor
460
+ ```
461
+
462
+ ### Cache Not Working?
463
+
464
+ ```bash
465
+ # Clear cache
466
+ rm -rf .context/cache
467
+
468
+ # Verify cache enabled in .memoryrc.json
469
+ cat .memoryrc.json | grep cache -A 5
470
+ ```
471
+
472
+ ---
473
+
474
+ ## 📚 Related Commands
475
+
476
+ Todos passam pelo core (`bin/forja.mjs`, ADR-0020). Se um comando não está aqui, ele está no
477
+ registry — `node bin/forja.mjs` lista todos.
478
+
479
+ ```bash
480
+ # Buscar antes de ler: é o primeiro passo da economia de tokens (ADR-0009)
481
+ npm run query:universal "auth"
482
+
483
+ # Montar o pacote de contexto mínimo-suficiente (global | domain | task)
484
+ npm run context:smart -- task my-project "payment feature"
485
+
486
+ # Reindexar a memória — também é o que corrige um índice defasado
487
+ npm run sync:universal
488
+
489
+ # Comprimir memória antiga e recuperar espaço
490
+ npm run memory:compress
491
+ npm run memory:vacuum
492
+
493
+ # Medir a economia
494
+ npm run token:benchmark
495
+
496
+ # Índice defasado responde sobre memória velha, calado. O doctor avisa (ADR-0023)
497
+ npm run tools:doctor
498
+ ```
499
+
500
+ ---
501
+
502
+ **Próximo**: [`docs/agent-harnesses.md`](agent-harnesses.md) — os gates e as ferramentas de processo.