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,565 +1,565 @@
1
- # Refinamento de Agentes Orquestrados - Especificação de Melhoras v1.0
2
-
3
- Documento vivo com decisões, padrões e implementações para elevar o kit a padrão profissional.
4
-
5
- ---
6
-
7
- ## 🎯 1. Qualidade & Segurança
8
-
9
- ### Status Atual
10
- - Testes: básicos (apenas app.controller.spec.ts na geração NestJS)
11
- - Validação: DTO com `class-validator` disponível, não obrigatório
12
- - Segurança: documentação (security.md) mas sem implementação forçada
13
- - Sanitização: ausente
14
-
15
- ### Melhoras Tier 1
16
- **[SEC-001] Adicionar validação obrigatória em rotas**
17
- - Toda rota deve usar DTOs com `@IsString()`, `@IsEmail()`, etc
18
- - Tratamento de erro estruturado (HttpException com código específico)
19
- - Template de DTO gerado automaticamente
20
-
21
- **[SEC-002] Implementar rate-limiting no gerador**
22
- - Gerar middleware de rate-limiting no backend
23
- - Config: 100 req/min por IP por padrão
24
- - Template pronto em `backend/src/middleware/rate-limit.ts`
25
-
26
- **[SEC-003] Sanitização de entrada**
27
- - Remover caracteres perigosos em strings de entrada
28
- - Validar tamanho máximo de payloads (10MB por padrão)
29
- - Usar `helmet` no NestJS
30
-
31
- **[SEC-004] Testes obrigatórios**
32
- - Gerar `*.spec.ts` para todo controller novo
33
- - Coverage mínimo: 80% em rotas críticas
34
- - Incluir testes de segurança (SQL injection, XSS simulation)
35
-
36
- ### Decisões
37
- - ✅ **Usar class-validator + class-transformer**: padrão NestJS, suporta nestação
38
- - ✅ **Helmet para headers de segurança**: reduz vetores de ataque
39
- - ✅ **Coverage mínimo 80%**: viável em projetos novos
40
-
41
- ---
42
-
43
- ## 🧠 2. Design de Agentes
44
-
45
- ### Status Atual
46
- - Agentes: 7 tipos (orchestrator, backend-nest, frontend, dba, security, reviewer, sem specialistas adicionais)
47
- - Prompts: 3 templates genéricos, muito curtos
48
- - Comunicação: contrato explícito no AGENTS.md mas pouco estruturado
49
- - Especialização: baixa (agentes genéricos)
50
-
51
- ### Melhoras Tier 1
52
- **[AGENT-001] Criar especificação estruturada de agentes**
53
- ```
54
- Cada agente terá:
55
- - ID único (ex: agent-backend-nest-v1)
56
- - Missão clara (1-2 frases)
57
- - Entrada esperada (formato, tamanho, estrutura)
58
- - Saída esperada (formato, qualidade, critério de aceite)
59
- - Contexto prioritário (quais docs ler)
60
- - Proibições explícitas (o que NÃO fazer)
61
- - Escala: 1-10 (complexidade, especificidade)
62
- ```
63
-
64
- **[AGENT-002] Melhorar prompts com estrutura de contexto**
65
- - Adicionar seção: "Você é especialista em [domínio]"
66
- - Incluir exemplos de input/output (few-shot)
67
- - Definir tom (formal, técnico, direto)
68
- - Incluir checklist de validação final
69
-
70
- **[AGENT-003] Protocolo de handoff estruturado**
71
- - Formato obrigatório com 7 campos (contexto, mudanças, riscos, pendências, próximo passo, checklist, metadados)
72
- - Validação de handoff antes de aceitar (revisor detecta gaps)
73
- - Template em `memory/50-orchestration/handoff-template.md`
74
-
75
- **[AGENT-004] Roteamento inteligente de tarefas**
76
- - Matriz de compatibilidade: tarefa -> agentes capazes
77
- - Score de "fit" (expertise match, carga atual, contexto carregado)
78
- - Orquestrador escolhe melhor agente automaticamente
79
-
80
- **[AGENT-005] Contrato de agentes em JSON Schema**
81
- - Definir input/output como JSON Schema
82
- - Validar payloads antes de enviar para agente
83
- - Permitir "strict" mode (erro se saída não match)
84
-
85
- ### Decisões
86
- - ✅ **JSON Schema para contratos**: interoperável, validável
87
- - ✅ **7 campos obrigatórios no handoff**: reduz gaps e retrabalho
88
- - ✅ **Few-shot em prompts**: aumenta qualidade de resposta 30-50%
89
-
90
- ---
91
-
92
- ## 🤖 3. Otimização para IAs (Copilot/Gemini/Codex/Claude)
93
-
94
- ### Status Atual
95
- - Contexto: compactação básica (build-context-pack.mjs)
96
- - Prompts: genéricos, sem otimização para modelos específicos
97
- - Rastreamento: não há detecção de qual modelo está usando
98
- - Estrutura: Markdown, sem hints de estrutura semântica
99
-
100
- ### Melhoras Tier 1
101
- **[AI-OPT-001] Context packing com model-aware**
102
- - Detectar modelo via header HTTP ou variável env
103
- - Ajustar tamanho do context-pack conforme modelo (Claude: 100k, GPT-4: 8k, Gemini: 32k)
104
- - Priorizar docs conforme modelo (IA legal: segurança; IA dev: código)
105
-
106
- **[AI-OPT-002] Estrutura de prompt "Instruction Bundle"**
107
- ```markdown
108
- # [ID] Tarefa
109
- ## 👤 Contexto
110
- - Você é: [especialista]
111
- - Objetivo: [claro]
112
-
113
- ## 📥 Entrada
114
- - Formato: [structure]
115
- - Restrições: [limits]
116
-
117
- ## 📤 Saída esperada
118
- - Formato: [structure]
119
- - Validação: [checklist]
120
-
121
- ## 🚫 Proibições
122
- - NUNCA fazer: [list]
123
-
124
- ## ✅ Checklist Final
125
- - [ ] Step 1
126
- - [ ] Step 2
127
- ```
128
-
129
- **[AI-OPT-003] Integração com .context/model-config.yml**
130
- ```yaml
131
- models:
132
- claude:
133
- max_tokens: 100000
134
- priority_sections: [global, architecture]
135
- prompt_style: structured
136
- gpt-4:
137
- max_tokens: 8000
138
- priority_sections: [current-task]
139
- prompt_style: concise
140
- gemini:
141
- max_tokens: 32000
142
- priority_sections: [global, domain]
143
- prompt_style: narrative
144
- ```
145
-
146
- **[AI-OPT-004] Memory compression com inline links**
147
- - Em vez de copiar conteúdo inteiro, usar referências: `[[ref:memory/10-product/vision.md:l1-20]]`
148
- - IAs entendem contexto com links
149
- - Reduz tamanho do prompt 60-70%
150
-
151
- **[AI-OPT-005] Strict mode para output**
152
- - Definir JSON Schema obrigatório
153
- - IA deve validar contra schema antes de responder
154
- - Se não match: recusar e explicar por quê
155
-
156
- ### Decisões
157
- - ✅ **JSON Schema para contratos**: validável por qualquer IA
158
- - ✅ **Model-aware context packing**: otimiza para cada modelo
159
- - ✅ **Instruction Bundle format**: estrutura clara, reduz alucinação
160
- - ⚠️ **Inline links**: depende de suporte do modelo (Claude sim, GPT-4 parcial)
161
-
162
- ---
163
-
164
- ## 📋 4. ADR & Sistema de Decisões Inteligentes
165
-
166
- ### Status Atual
167
- - Template: basic (ADR-0001-template.md)
168
- - Rastreamento: banco tem tabela `adrs` mas vazia
169
- - Sem validação de qualidade
170
- - Sem rastreamento de impacto
171
-
172
- ### Melhoras Tier 1
173
- **[ADR-001] Estrutura robusta de ADR**
174
- ```
175
- # ADR-NNNN: [Título conciso]
176
-
177
- ## Data
178
- 2026-04-21
179
-
180
- ## Contexto
181
- [Por que estamos decidindo isso agora?]
182
- [Constraints técnicas e de negócio]
183
- [Quem precisa saber]
184
-
185
- ## Questão
186
- [Qual exatamente é a decisão?]
187
-
188
- ## Opções Consideradas
189
- ### Opção A: [Nome]
190
- - ✅ Pros
191
- - ❌ Cons
192
- - 💰 Custo
193
- - ⏱️ Tempo
194
-
195
- ### Opção B: [Nome]
196
- ...
197
-
198
- ## Decisão
199
- [Qual escolhemos e por quê]
200
-
201
- ## Impacto Esperado
202
- - Arquitetura: [mudanças]
203
- - Equipe: [skill necessária]
204
- - Cronograma: [efeito]
205
- - Risco: [novo risco]
206
-
207
- ## Status
208
- - `accepted` / `deprecated` / `superseded` / `proposed`
209
-
210
- ## Rastreamento
211
- - Issue: #123
212
- - Commit: abc1234
213
- - PR: #456
214
- ```
215
-
216
- **[ADR-002] Sistema de versionamento e impacto**
217
- - Cada ADR recebe ID único (ADR-0001, ADR-0002, etc)
218
- - Versão no nome (ADR-0001-v1.md, ADR-0001-v2-superseded.md)
219
- - Tabela de impacto: qual código/documentação mudou
220
-
221
- **[ADR-003] Decisões registradas no banco**
222
- - Sync automático: script lê ADR-*.md e popula tabela `decisions`
223
- - Query: listar decisões por data, status, impacto
224
- - Relatório: "Decisões críticas dos últimos 30 dias"
225
-
226
- **[ADR-004] Integração com handoff**
227
- - Handoff deve referenciar ADRs impactadas: "Veja ADR-0003 para context"
228
- - ADRs devem listar handoffs relacionados
229
- - Bidirecional
230
-
231
- ### Decisões
232
- - ✅ **ADR com status lifecycle**: rastreabilidade
233
- - ✅ **Impacto explícito**: facilita revisão de risco
234
- - ✅ **Versioning**: permite evolução sem perder histórico
235
-
236
- ---
237
-
238
- ## 📚 5. Gestão de Memória (Compactação & Handoff)
239
-
240
- ### Status Atual
241
- - Compactação: build-context-pack.mjs concatena 6 arquivos prioritários
242
- - Handoff: template básico, sem estrutura de validação
243
- - Recovery: `memory-db-query.mjs` faz busca genérica
244
- - Sem análise de "size creep"
245
-
246
- ### Melhoras Tier 1
247
- **[MEM-001] Compactação inteligente em 3 níveis**
248
- ```
249
- Level 1 (Minimal): 500 tokens
250
- - mission.md + standards.md + current-sprint.md
251
-
252
- Level 2 (Standard): 2000 tokens
253
- - L1 + 20-architecture + 70-summaries/global
254
-
255
- Level 3 (Full): 8000+ tokens
256
- - L2 + domain/* + handoffs/
257
-
258
- Seleção automática: usuário escolhe nível ou sistema elige conforme modelo.
259
- ```
260
-
261
- **[MEM-002] Compactação com preservação de estrutura**
262
- - Adicionar metadata JSON: `{ "sections": [...], "tokens": 1234, "checksum": "abc123" }`
263
- - Permitir "diff" entre versões de context-pack
264
- - Detectar mudanças significativas (novo capítulo, alteração crítica)
265
-
266
- **[MEM-003] Handoff com contexto mínimo garantido**
267
- - Template obrigatório: 7 campos
268
- - Validação: deve incluir "próximo passo" explícito
269
- - Sistema recusa handoff incompleto
270
-
271
- **[MEM-004] Recovery inteligente**
272
- - Se agente volta do contexto incompleto, script sugere contexto adicional
273
- - Cache local: docs carregadas recentemente reutilizadas
274
- - Rastreamento: "Último contexto carregado: 2h atrás, 4 mudanças pendentes"
275
-
276
- **[MEM-005] Análise de "tamanho creep"**
277
- - Script mensal: "memory size analysis"
278
- - Alerta se memory > 20MB (sinal de documentação não compactada)
279
- - Recomendação: arquivar e.g. handoffs antigos (> 3 meses)
280
-
281
- ### Decisões
282
- - ✅ **3 níveis de compactação**: flexível para diferentes contextos
283
- - ✅ **7 campos obrigatórios no handoff**: qualidade mínima
284
- - ✅ **Metadata com checksum**: detecta mudanças
285
-
286
- ---
287
-
288
- ## 📖 6. Documentação de Produto (Padrão Profissional)
289
-
290
- ### Status Atual
291
- - Documentação: 478 linhas em docs/, aleatória
292
- - Sem padrão de qualidade
293
- - Sem "getting started" estruturado
294
- - Sem diagrama/visual
295
-
296
- ### Melhoras Tier 1
297
- **[DOC-001] Estrutura de documentação tipo Stripe/Vercel**
298
- ```
299
- 📚 Documentação Root
300
- ├─ 📄 Getting Started (5 min)
301
- │ ├─ O que é
302
- │ ├─ Instalação 3 linhas
303
- │ ├─ "Hello World"
304
- │ └─ Próximos passos
305
- ├─ 🏗️ Conceitos Fundamentais
306
- │ ├─ Memória Hierárquica
307
- │ ├─ Agentes e Roles
308
- │ ├─ Orquestração
309
- │ └─ Handoff & Continuidade
310
- ├─ 🔧 Guia de Uso
311
- │ ├─ Criar Novo Projeto
312
- │ ├─ Adicionar Domínio
313
- │ ├─ Configurar Agentes
314
- │ └─ Usar Scripts
315
- ├─ 🎓 Tutoriais
316
- │ ├─ [Caso 1] Projeto com 1 backend + 1 worker
317
- │ ├─ [Caso 2] Projeto com múltiplos domínios
318
- │ └─ [Caso 3] Integração com seu CLI favorito
319
- ├─ 🔍 Referência API
320
- │ ├─ CLI flags
321
- │ ├─ Memory structure
322
- │ └─ Database schema
323
- ├─ ⚙️ Configuração Avançada
324
- │ ├─ Custom agents
325
- │ ├─ Model-specific tuning
326
- │ └─ Security hardening
327
- └─ ❓ FAQ & Troubleshooting
328
- ```
329
-
330
- **[DOC-002] Padrão de escrita**
331
- - Cada arquivo: < 500 linhas
332
- - Títulos H1-H3 apenas
333
- - Code samples: 5-10 linhas máximo, contexto claro
334
- - Links internos: `[topic](../path/to/doc.md)`
335
- - "Próximo passo" em todo artigo
336
-
337
- **[DOC-003] Diagramas em ASCII + Mermaid**
338
- - Arquitetura: diagram ASCII em README
339
- - Fluxo de agentes: Mermaid graph
340
- - Memory hierarchy: tree ASCII
341
-
342
- **[DOC-004] Changelog estruturado**
343
- - Arquivo: `docs/CHANGELOG.md`
344
- - Versão: major.minor.patch
345
- - Seções: Added, Changed, Deprecated, Removed, Fixed, Security
346
- - Link para ADRs relacionadas
347
-
348
- **[DOC-005] Contributing Guide**
349
- - Padrão de branches: `feat/`, `fix/`, `docs/`
350
- - Commit message: `[type] Description`
351
- - PR template: checklist + referência a ADR
352
- - Teste: instruções passo a passo
353
-
354
- ### Decisões
355
- - ✅ **Estrutura em camadas**: escalável
356
- - ✅ **Padrão Stripe/Vercel**: familiar, profissional
357
- - ✅ **Diagrama + texto**: clareza
358
-
359
- ---
360
-
361
- ## ⚙️ 7. Metodologia Ágil (Sprint & Entregáveis)
362
-
363
- ### Status Atual
364
- - Template de sprint: `current-sprint.md` básico
365
- - Sem estrutura de planning, retrospectiva
366
- - Sem definição de "pronto"
367
- - Sem métricas de velocidade
368
-
369
- ### Melhoras Tier 1
370
- **[AGILE-001] Estrutura de sprint**
371
- ```
372
- # Sprint NN (Data início - Data fim)
373
-
374
- ## Objetivo (1-2 frases)
375
- [O que queremos conseguir]
376
-
377
- ## Capacidade
378
- - Devs: 2 pessoas × 5 dias × 6h = 60 horas
379
- - QA: 1 pessoa × 5 dias × 4h = 20 horas
380
- - Total: 80 horas
381
-
382
- ## User Stories
383
- ### [ID] Título
384
- - Como [ator]
385
- - Quero [ação]
386
- - Para [benefício]
387
- - AC1: [critério]
388
- - AC2: [critério]
389
- - Estimativa: [horas]
390
- - Dono: [person]
391
- - Status: `todo` / `in-progress` / `review` / `done`
392
-
393
- ## Riscos Sprint
394
- | Risco | Impacto | Mitigation |
395
- |-------|---------|-----------|
396
- | ... | ... | ... |
397
-
398
- ## Métricas
399
- - Velocity: NN story points
400
- - Burn down: conforme esperado
401
- - Bugs encontrados: NN
402
- ```
403
-
404
- **[AGILE-002] Definição de "Pronto" (Definition of Done)**
405
- ```
406
- - Código implementado
407
- - Testes escritos (cobertura > 80%)
408
- - Code review + approval
409
- - Documentação atualizada
410
- - ADR criado (se mudança estrutural)
411
- - Handoff registrado (se cross-agent)
412
- - Passou em CI/CD
413
- - Deploy para staging
414
- ```
415
-
416
- **[AGILE-003] Estrutura de ceremônias**
417
- - Planning (2h): decomposição de stories
418
- - Standup diário (15min): sync
419
- - Review (1h): demo + feedback
420
- - Retro (1h): o que foi bem, o que melhorar, ações
421
-
422
- **[AGILE-004] Matriz de rastreamento**
423
- - Integrar com `improvement_items` no BD
424
- - Query: status de todas as melhoras
425
- - Dashboard: % completo por categoria
426
-
427
- **[AGILE-005] Release notes profissional**
428
- - Template: v0.2.0 (YYYY-MM-DD)
429
- - Seções: Features, Improvements, Fixes, Breaking Changes
430
- - Incluir: migration guide (se necessário)
431
-
432
- ### Decisões
433
- - ✅ **User stories com AC**: clareza de aceite
434
- - ✅ **Definition of Done explícito**: qualidade
435
- - ✅ **Rastreamento em BD**: visibilidade
436
-
437
- ---
438
-
439
- ## 📊 8. Observabilidade (Logs, Métricas, Tracing)
440
-
441
- ### Status Atual
442
- - Logs: genéricos, sem estrutura
443
- - Métricas: ausentes
444
- - Tracing: não existe
445
- - Observabilidade de agentes: 0
446
-
447
- ### Melhoras Tier 1
448
- **[OBS-001] Logs estruturados com contexto**
449
- ```json
450
- {
451
- "timestamp": "2026-04-21T09:51:33.423Z",
452
- "level": "info",
453
- "agent": "orchestrator",
454
- "task_id": "task-123",
455
- "action": "task_decomposed",
456
- "owner_count": 3,
457
- "duration_ms": 245,
458
- "context": {
459
- "file_count": 12,
460
- "size_bytes": 45000
461
- }
462
- }
463
- ```
464
-
465
- **[OBS-002] Decorator para log estruturado em NestJS**
466
- ```typescript
467
- @LogStructured('backend-nest', 'implement_endpoint')
468
- async createUser(dto: CreateUserDto) {
469
- // Log automático com agent, ação, duração, resultado
470
- }
471
- ```
472
-
473
- **[OBS-003] Métricas de agentes**
474
- - `agent_task_count`: quantas tarefas por agente
475
- - `agent_success_rate`: % de sucesso (com base em handoff quality)
476
- - `agent_context_size`: tamanho médio de contexto carregado
477
- - `handoff_quality_score`: 1-10 baseado em preenchimento
478
-
479
- **[OBS-004] Tracing de handoff**
480
- - Cada handoff recebe ID único: `handoff-uuid-timestamp`
481
- - Trace: orchestrator -> worker-a -> reviewer -> worker-b
482
- - Latência entre handoffs: rastreada
483
- - Alertas: handoff aberto > 1h
484
-
485
- **[OBS-005] Dashboard de observabilidade**
486
- - Script: `backend/scripts/memory-db-observability.mjs`
487
- - Queries pré-prontas:
488
- - "Handoffs abertos"
489
- - "Agente com menor taxa de sucesso"
490
- - "Documentação > 20MB"
491
- - "ADRs sem impacto vinculado"
492
-
493
- ### Decisões
494
- - ✅ **Logs estruturados em JSON**: parseável
495
- - ✅ **Decorator para automação**: menos boilerplate
496
- - ✅ **Métricas por agente**: visibilidade
497
-
498
- ---
499
-
500
- ## 📈 Roadmap de Implementação
501
-
502
- ### Fase 1 (Semanas 1-2): Tier 1 Foundation
503
- - [ ] SEC-001, SEC-002: Validação + Rate-limiting
504
- - [ ] AGENT-001, AGENT-002: Prompts estruturados
505
- - [ ] AI-OPT-001: Context packing model-aware
506
- - [ ] ADR-001: Estrutura robusta
507
- - [ ] MEM-001: 3 níveis de compactação
508
- - [ ] DOC-001: Estrutura de documentação
509
- - [ ] AGILE-001, AGILE-002: Sprint template + DoD
510
- - [ ] OBS-001: Logs estruturados
511
-
512
- ### Fase 2 (Semanas 3-4): Tier 1 Completion
513
- - [ ] SEC-003, SEC-004: Sanitização + Testes
514
- - [ ] AGENT-003, AGENT-004, AGENT-005: Handoff, roteamento, schema
515
- - [ ] AI-OPT-002 até AI-OPT-005: Advanced AI optimization
516
- - [ ] ADR-002, ADR-003, ADR-004: Versionamento + BD + integração
517
- - [ ] MEM-002 até MEM-005: Compactação inteligente + recovery
518
- - [ ] DOC-002 até DOC-005: Padrão + diagramas + changelog
519
- - [ ] AGILE-003, AGILE-004, AGILE-005: Ceremônias + matriz + release notes
520
- - [ ] OBS-002 até OBS-005: Decorator + métricas + tracing + dashboard
521
-
522
- ### Fase 3 (Semanas 5-6): Tier 2 + Integração
523
- - Documentação de Produto (completa)
524
- - Metodologia Ágil (full ceremonies)
525
- - Observabilidade (full stack)
526
-
527
- ---
528
-
529
- ## 💾 Rastreamento em Banco de Dados
530
-
531
- Todos os items estão registrados na tabela `improvement_items`:
532
-
533
- ```sql
534
- SELECT * FROM improvement_items
535
- WHERE status != 'done'
536
- ORDER BY area_id, complexity;
537
-
538
- -- Atualizar status conforme progresso
539
- UPDATE improvement_items SET status = 'in_progress'
540
- WHERE id = 'SEC-001';
541
- ```
542
-
543
- Decisões vinculadas em `decisions`:
544
-
545
- ```sql
546
- SELECT d.* FROM decisions d
547
- JOIN improvement_items i ON d.item_id = i.id
548
- WHERE i.area_id = 'ai-optimization'
549
- ORDER BY d.created_at DESC;
550
- ```
551
-
552
- ---
553
-
554
- ## ✨ Próximos Passos
555
-
556
- 1. **Review este documento** com stakeholders
557
- 2. **Ajustar prioridades** se necessário
558
- 3. **Começar Fase 1** na próxima sprint
559
- 4. **Atualizar BD** conforme progresso
560
- 5. **Documentar decisões** em ADRs quando relevante
561
-
562
- ---
563
-
564
- **Versão**: 1.0 | **Data**: 2026-04-21 | **Autor**: Copilot Analysis | **Status**: Aceito para Implementação
565
-
1
+ # Refinamento de Agentes Orquestrados - Especificação de Melhoras v1.0
2
+
3
+ Documento vivo com decisões, padrões e implementações para elevar o kit a padrão profissional.
4
+
5
+ ---
6
+
7
+ ## 🎯 1. Qualidade & Segurança
8
+
9
+ ### Status Atual
10
+ - Testes: básicos (apenas app.controller.spec.ts na geração NestJS)
11
+ - Validação: DTO com `class-validator` disponível, não obrigatório
12
+ - Segurança: documentação (security.md) mas sem implementação forçada
13
+ - Sanitização: ausente
14
+
15
+ ### Melhoras Tier 1
16
+ **[SEC-001] Adicionar validação obrigatória em rotas**
17
+ - Toda rota deve usar DTOs com `@IsString()`, `@IsEmail()`, etc
18
+ - Tratamento de erro estruturado (HttpException com código específico)
19
+ - Template de DTO gerado automaticamente
20
+
21
+ **[SEC-002] Implementar rate-limiting no gerador**
22
+ - Gerar middleware de rate-limiting no backend
23
+ - Config: 100 req/min por IP por padrão
24
+ - Template pronto em `backend/src/middleware/rate-limit.ts`
25
+
26
+ **[SEC-003] Sanitização de entrada**
27
+ - Remover caracteres perigosos em strings de entrada
28
+ - Validar tamanho máximo de payloads (10MB por padrão)
29
+ - Usar `helmet` no NestJS
30
+
31
+ **[SEC-004] Testes obrigatórios**
32
+ - Gerar `*.spec.ts` para todo controller novo
33
+ - Coverage mínimo: 80% em rotas críticas
34
+ - Incluir testes de segurança (SQL injection, XSS simulation)
35
+
36
+ ### Decisões
37
+ - ✅ **Usar class-validator + class-transformer**: padrão NestJS, suporta nestação
38
+ - ✅ **Helmet para headers de segurança**: reduz vetores de ataque
39
+ - ✅ **Coverage mínimo 80%**: viável em projetos novos
40
+
41
+ ---
42
+
43
+ ## 🧠 2. Design de Agentes
44
+
45
+ ### Status Atual
46
+ - Agentes: 7 tipos (orchestrator, backend-nest, frontend, dba, security, reviewer, sem specialistas adicionais)
47
+ - Prompts: 3 templates genéricos, muito curtos
48
+ - Comunicação: contrato explícito no AGENTS.md mas pouco estruturado
49
+ - Especialização: baixa (agentes genéricos)
50
+
51
+ ### Melhoras Tier 1
52
+ **[AGENT-001] Criar especificação estruturada de agentes**
53
+ ```
54
+ Cada agente terá:
55
+ - ID único (ex: agent-backend-nest-v1)
56
+ - Missão clara (1-2 frases)
57
+ - Entrada esperada (formato, tamanho, estrutura)
58
+ - Saída esperada (formato, qualidade, critério de aceite)
59
+ - Contexto prioritário (quais docs ler)
60
+ - Proibições explícitas (o que NÃO fazer)
61
+ - Escala: 1-10 (complexidade, especificidade)
62
+ ```
63
+
64
+ **[AGENT-002] Melhorar prompts com estrutura de contexto**
65
+ - Adicionar seção: "Você é especialista em [domínio]"
66
+ - Incluir exemplos de input/output (few-shot)
67
+ - Definir tom (formal, técnico, direto)
68
+ - Incluir checklist de validação final
69
+
70
+ **[AGENT-003] Protocolo de handoff estruturado**
71
+ - Formato obrigatório com 7 campos (contexto, mudanças, riscos, pendências, próximo passo, checklist, metadados)
72
+ - Validação de handoff antes de aceitar (revisor detecta gaps)
73
+ - Template em `memory/50-orchestration/handoff-template.md`
74
+
75
+ **[AGENT-004] Roteamento inteligente de tarefas**
76
+ - Matriz de compatibilidade: tarefa -> agentes capazes
77
+ - Score de "fit" (expertise match, carga atual, contexto carregado)
78
+ - Orquestrador escolhe melhor agente automaticamente
79
+
80
+ **[AGENT-005] Contrato de agentes em JSON Schema**
81
+ - Definir input/output como JSON Schema
82
+ - Validar payloads antes de enviar para agente
83
+ - Permitir "strict" mode (erro se saída não match)
84
+
85
+ ### Decisões
86
+ - ✅ **JSON Schema para contratos**: interoperável, validável
87
+ - ✅ **7 campos obrigatórios no handoff**: reduz gaps e retrabalho
88
+ - ✅ **Few-shot em prompts**: aumenta qualidade de resposta 30-50%
89
+
90
+ ---
91
+
92
+ ## 🤖 3. Otimização para IAs (Copilot/Gemini/Codex/Claude)
93
+
94
+ ### Status Atual
95
+ - Contexto: compactação básica (build-context-pack.mjs)
96
+ - Prompts: genéricos, sem otimização para modelos específicos
97
+ - Rastreamento: não há detecção de qual modelo está usando
98
+ - Estrutura: Markdown, sem hints de estrutura semântica
99
+
100
+ ### Melhoras Tier 1
101
+ **[AI-OPT-001] Context packing com model-aware**
102
+ - Detectar modelo via header HTTP ou variável env
103
+ - Ajustar tamanho do context-pack conforme modelo (Claude: 100k, GPT-4: 8k, Gemini: 32k)
104
+ - Priorizar docs conforme modelo (IA legal: segurança; IA dev: código)
105
+
106
+ **[AI-OPT-002] Estrutura de prompt "Instruction Bundle"**
107
+ ```markdown
108
+ # [ID] Tarefa
109
+ ## 👤 Contexto
110
+ - Você é: [especialista]
111
+ - Objetivo: [claro]
112
+
113
+ ## 📥 Entrada
114
+ - Formato: [structure]
115
+ - Restrições: [limits]
116
+
117
+ ## 📤 Saída esperada
118
+ - Formato: [structure]
119
+ - Validação: [checklist]
120
+
121
+ ## 🚫 Proibições
122
+ - NUNCA fazer: [list]
123
+
124
+ ## ✅ Checklist Final
125
+ - [ ] Step 1
126
+ - [ ] Step 2
127
+ ```
128
+
129
+ **[AI-OPT-003] Integração com .context/model-config.yml**
130
+ ```yaml
131
+ models:
132
+ claude:
133
+ max_tokens: 100000
134
+ priority_sections: [global, architecture]
135
+ prompt_style: structured
136
+ gpt-4:
137
+ max_tokens: 8000
138
+ priority_sections: [current-task]
139
+ prompt_style: concise
140
+ gemini:
141
+ max_tokens: 32000
142
+ priority_sections: [global, domain]
143
+ prompt_style: narrative
144
+ ```
145
+
146
+ **[AI-OPT-004] Memory compression com inline links**
147
+ - Em vez de copiar conteúdo inteiro, usar referências: `[[ref:memory/10-product/vision.md:l1-20]]`
148
+ - IAs entendem contexto com links
149
+ - Reduz tamanho do prompt 60-70%
150
+
151
+ **[AI-OPT-005] Strict mode para output**
152
+ - Definir JSON Schema obrigatório
153
+ - IA deve validar contra schema antes de responder
154
+ - Se não match: recusar e explicar por quê
155
+
156
+ ### Decisões
157
+ - ✅ **JSON Schema para contratos**: validável por qualquer IA
158
+ - ✅ **Model-aware context packing**: otimiza para cada modelo
159
+ - ✅ **Instruction Bundle format**: estrutura clara, reduz alucinação
160
+ - ⚠️ **Inline links**: depende de suporte do modelo (Claude sim, GPT-4 parcial)
161
+
162
+ ---
163
+
164
+ ## 📋 4. ADR & Sistema de Decisões Inteligentes
165
+
166
+ ### Status Atual
167
+ - Template: basic (ADR-0001-template.md)
168
+ - Rastreamento: banco tem tabela `adrs` mas vazia
169
+ - Sem validação de qualidade
170
+ - Sem rastreamento de impacto
171
+
172
+ ### Melhoras Tier 1
173
+ **[ADR-001] Estrutura robusta de ADR**
174
+ ```
175
+ # ADR-NNNN: [Título conciso]
176
+
177
+ ## Data
178
+ 2026-04-21
179
+
180
+ ## Contexto
181
+ [Por que estamos decidindo isso agora?]
182
+ [Constraints técnicas e de negócio]
183
+ [Quem precisa saber]
184
+
185
+ ## Questão
186
+ [Qual exatamente é a decisão?]
187
+
188
+ ## Opções Consideradas
189
+ ### Opção A: [Nome]
190
+ - ✅ Pros
191
+ - ❌ Cons
192
+ - 💰 Custo
193
+ - ⏱️ Tempo
194
+
195
+ ### Opção B: [Nome]
196
+ ...
197
+
198
+ ## Decisão
199
+ [Qual escolhemos e por quê]
200
+
201
+ ## Impacto Esperado
202
+ - Arquitetura: [mudanças]
203
+ - Equipe: [skill necessária]
204
+ - Cronograma: [efeito]
205
+ - Risco: [novo risco]
206
+
207
+ ## Status
208
+ - `accepted` / `deprecated` / `superseded` / `proposed`
209
+
210
+ ## Rastreamento
211
+ - Issue: #123
212
+ - Commit: abc1234
213
+ - PR: #456
214
+ ```
215
+
216
+ **[ADR-002] Sistema de versionamento e impacto**
217
+ - Cada ADR recebe ID único (ADR-0001, ADR-0002, etc)
218
+ - Versão no nome (ADR-0001-v1.md, ADR-0001-v2-superseded.md)
219
+ - Tabela de impacto: qual código/documentação mudou
220
+
221
+ **[ADR-003] Decisões registradas no banco**
222
+ - Sync automático: script lê ADR-*.md e popula tabela `decisions`
223
+ - Query: listar decisões por data, status, impacto
224
+ - Relatório: "Decisões críticas dos últimos 30 dias"
225
+
226
+ **[ADR-004] Integração com handoff**
227
+ - Handoff deve referenciar ADRs impactadas: "Veja ADR-0003 para context"
228
+ - ADRs devem listar handoffs relacionados
229
+ - Bidirecional
230
+
231
+ ### Decisões
232
+ - ✅ **ADR com status lifecycle**: rastreabilidade
233
+ - ✅ **Impacto explícito**: facilita revisão de risco
234
+ - ✅ **Versioning**: permite evolução sem perder histórico
235
+
236
+ ---
237
+
238
+ ## 📚 5. Gestão de Memória (Compactação & Handoff)
239
+
240
+ ### Status Atual
241
+ - Compactação: build-context-pack.mjs concatena 6 arquivos prioritários
242
+ - Handoff: template básico, sem estrutura de validação
243
+ - Recovery: `memory-db-query.mjs` faz busca genérica
244
+ - Sem análise de "size creep"
245
+
246
+ ### Melhoras Tier 1
247
+ **[MEM-001] Compactação inteligente em 3 níveis**
248
+ ```
249
+ Level 1 (Minimal): 500 tokens
250
+ - mission.md + standards.md + current-sprint.md
251
+
252
+ Level 2 (Standard): 2000 tokens
253
+ - L1 + 20-architecture + 70-summaries/global
254
+
255
+ Level 3 (Full): 8000+ tokens
256
+ - L2 + domain/* + handoffs/
257
+
258
+ Seleção automática: usuário escolhe nível ou sistema elige conforme modelo.
259
+ ```
260
+
261
+ **[MEM-002] Compactação com preservação de estrutura**
262
+ - Adicionar metadata JSON: `{ "sections": [...], "tokens": 1234, "checksum": "abc123" }`
263
+ - Permitir "diff" entre versões de context-pack
264
+ - Detectar mudanças significativas (novo capítulo, alteração crítica)
265
+
266
+ **[MEM-003] Handoff com contexto mínimo garantido**
267
+ - Template obrigatório: 7 campos
268
+ - Validação: deve incluir "próximo passo" explícito
269
+ - Sistema recusa handoff incompleto
270
+
271
+ **[MEM-004] Recovery inteligente**
272
+ - Se agente volta do contexto incompleto, script sugere contexto adicional
273
+ - Cache local: docs carregadas recentemente reutilizadas
274
+ - Rastreamento: "Último contexto carregado: 2h atrás, 4 mudanças pendentes"
275
+
276
+ **[MEM-005] Análise de "tamanho creep"**
277
+ - Script mensal: "memory size analysis"
278
+ - Alerta se memory > 20MB (sinal de documentação não compactada)
279
+ - Recomendação: arquivar e.g. handoffs antigos (> 3 meses)
280
+
281
+ ### Decisões
282
+ - ✅ **3 níveis de compactação**: flexível para diferentes contextos
283
+ - ✅ **7 campos obrigatórios no handoff**: qualidade mínima
284
+ - ✅ **Metadata com checksum**: detecta mudanças
285
+
286
+ ---
287
+
288
+ ## 📖 6. Documentação de Produto (Padrão Profissional)
289
+
290
+ ### Status Atual
291
+ - Documentação: 478 linhas em docs/, aleatória
292
+ - Sem padrão de qualidade
293
+ - Sem "getting started" estruturado
294
+ - Sem diagrama/visual
295
+
296
+ ### Melhoras Tier 1
297
+ **[DOC-001] Estrutura de documentação tipo Stripe/Vercel**
298
+ ```
299
+ 📚 Documentação Root
300
+ ├─ 📄 Getting Started (5 min)
301
+ │ ├─ O que é
302
+ │ ├─ Instalação 3 linhas
303
+ │ ├─ "Hello World"
304
+ │ └─ Próximos passos
305
+ ├─ 🏗️ Conceitos Fundamentais
306
+ │ ├─ Memória Hierárquica
307
+ │ ├─ Agentes e Roles
308
+ │ ├─ Orquestração
309
+ │ └─ Handoff & Continuidade
310
+ ├─ 🔧 Guia de Uso
311
+ │ ├─ Criar Novo Projeto
312
+ │ ├─ Adicionar Domínio
313
+ │ ├─ Configurar Agentes
314
+ │ └─ Usar Scripts
315
+ ├─ 🎓 Tutoriais
316
+ │ ├─ [Caso 1] Projeto com 1 backend + 1 worker
317
+ │ ├─ [Caso 2] Projeto com múltiplos domínios
318
+ │ └─ [Caso 3] Integração com seu CLI favorito
319
+ ├─ 🔍 Referência API
320
+ │ ├─ CLI flags
321
+ │ ├─ Memory structure
322
+ │ └─ Database schema
323
+ ├─ ⚙️ Configuração Avançada
324
+ │ ├─ Custom agents
325
+ │ ├─ Model-specific tuning
326
+ │ └─ Security hardening
327
+ └─ ❓ FAQ & Troubleshooting
328
+ ```
329
+
330
+ **[DOC-002] Padrão de escrita**
331
+ - Cada arquivo: < 500 linhas
332
+ - Títulos H1-H3 apenas
333
+ - Code samples: 5-10 linhas máximo, contexto claro
334
+ - Links internos: `[topic](../path/to/doc.md)`
335
+ - "Próximo passo" em todo artigo
336
+
337
+ **[DOC-003] Diagramas em ASCII + Mermaid**
338
+ - Arquitetura: diagram ASCII em README
339
+ - Fluxo de agentes: Mermaid graph
340
+ - Memory hierarchy: tree ASCII
341
+
342
+ **[DOC-004] Changelog estruturado**
343
+ - Arquivo: `docs/CHANGELOG.md`
344
+ - Versão: major.minor.patch
345
+ - Seções: Added, Changed, Deprecated, Removed, Fixed, Security
346
+ - Link para ADRs relacionadas
347
+
348
+ **[DOC-005] Contributing Guide**
349
+ - Padrão de branches: `feat/`, `fix/`, `docs/`
350
+ - Commit message: `[type] Description`
351
+ - PR template: checklist + referência a ADR
352
+ - Teste: instruções passo a passo
353
+
354
+ ### Decisões
355
+ - ✅ **Estrutura em camadas**: escalável
356
+ - ✅ **Padrão Stripe/Vercel**: familiar, profissional
357
+ - ✅ **Diagrama + texto**: clareza
358
+
359
+ ---
360
+
361
+ ## ⚙️ 7. Metodologia Ágil (Sprint & Entregáveis)
362
+
363
+ ### Status Atual
364
+ - Template de sprint: `current-sprint.md` básico
365
+ - Sem estrutura de planning, retrospectiva
366
+ - Sem definição de "pronto"
367
+ - Sem métricas de velocidade
368
+
369
+ ### Melhoras Tier 1
370
+ **[AGILE-001] Estrutura de sprint**
371
+ ```
372
+ # Sprint NN (Data início - Data fim)
373
+
374
+ ## Objetivo (1-2 frases)
375
+ [O que queremos conseguir]
376
+
377
+ ## Capacidade
378
+ - Devs: 2 pessoas × 5 dias × 6h = 60 horas
379
+ - QA: 1 pessoa × 5 dias × 4h = 20 horas
380
+ - Total: 80 horas
381
+
382
+ ## User Stories
383
+ ### [ID] Título
384
+ - Como [ator]
385
+ - Quero [ação]
386
+ - Para [benefício]
387
+ - AC1: [critério]
388
+ - AC2: [critério]
389
+ - Estimativa: [horas]
390
+ - Dono: [person]
391
+ - Status: `todo` / `in-progress` / `review` / `done`
392
+
393
+ ## Riscos Sprint
394
+ | Risco | Impacto | Mitigation |
395
+ |-------|---------|-----------|
396
+ | ... | ... | ... |
397
+
398
+ ## Métricas
399
+ - Velocity: NN story points
400
+ - Burn down: conforme esperado
401
+ - Bugs encontrados: NN
402
+ ```
403
+
404
+ **[AGILE-002] Definição de "Pronto" (Definition of Done)**
405
+ ```
406
+ - Código implementado
407
+ - Testes escritos (cobertura > 80%)
408
+ - Code review + approval
409
+ - Documentação atualizada
410
+ - ADR criado (se mudança estrutural)
411
+ - Handoff registrado (se cross-agent)
412
+ - Passou em CI/CD
413
+ - Deploy para staging
414
+ ```
415
+
416
+ **[AGILE-003] Estrutura de ceremônias**
417
+ - Planning (2h): decomposição de stories
418
+ - Standup diário (15min): sync
419
+ - Review (1h): demo + feedback
420
+ - Retro (1h): o que foi bem, o que melhorar, ações
421
+
422
+ **[AGILE-004] Matriz de rastreamento**
423
+ - Integrar com `improvement_items` no BD
424
+ - Query: status de todas as melhoras
425
+ - Dashboard: % completo por categoria
426
+
427
+ **[AGILE-005] Release notes profissional**
428
+ - Template: v0.2.0 (YYYY-MM-DD)
429
+ - Seções: Features, Improvements, Fixes, Breaking Changes
430
+ - Incluir: migration guide (se necessário)
431
+
432
+ ### Decisões
433
+ - ✅ **User stories com AC**: clareza de aceite
434
+ - ✅ **Definition of Done explícito**: qualidade
435
+ - ✅ **Rastreamento em BD**: visibilidade
436
+
437
+ ---
438
+
439
+ ## 📊 8. Observabilidade (Logs, Métricas, Tracing)
440
+
441
+ ### Status Atual
442
+ - Logs: genéricos, sem estrutura
443
+ - Métricas: ausentes
444
+ - Tracing: não existe
445
+ - Observabilidade de agentes: 0
446
+
447
+ ### Melhoras Tier 1
448
+ **[OBS-001] Logs estruturados com contexto**
449
+ ```json
450
+ {
451
+ "timestamp": "2026-04-21T09:51:33.423Z",
452
+ "level": "info",
453
+ "agent": "orchestrator",
454
+ "task_id": "task-123",
455
+ "action": "task_decomposed",
456
+ "owner_count": 3,
457
+ "duration_ms": 245,
458
+ "context": {
459
+ "file_count": 12,
460
+ "size_bytes": 45000
461
+ }
462
+ }
463
+ ```
464
+
465
+ **[OBS-002] Decorator para log estruturado em NestJS**
466
+ ```typescript
467
+ @LogStructured('backend-nest', 'implement_endpoint')
468
+ async createUser(dto: CreateUserDto) {
469
+ // Log automático com agent, ação, duração, resultado
470
+ }
471
+ ```
472
+
473
+ **[OBS-003] Métricas de agentes**
474
+ - `agent_task_count`: quantas tarefas por agente
475
+ - `agent_success_rate`: % de sucesso (com base em handoff quality)
476
+ - `agent_context_size`: tamanho médio de contexto carregado
477
+ - `handoff_quality_score`: 1-10 baseado em preenchimento
478
+
479
+ **[OBS-004] Tracing de handoff**
480
+ - Cada handoff recebe ID único: `handoff-uuid-timestamp`
481
+ - Trace: orchestrator -> worker-a -> reviewer -> worker-b
482
+ - Latência entre handoffs: rastreada
483
+ - Alertas: handoff aberto > 1h
484
+
485
+ **[OBS-005] Dashboard de observabilidade**
486
+ - Script: `backend/scripts/memory-db-observability.mjs`
487
+ - Queries pré-prontas:
488
+ - "Handoffs abertos"
489
+ - "Agente com menor taxa de sucesso"
490
+ - "Documentação > 20MB"
491
+ - "ADRs sem impacto vinculado"
492
+
493
+ ### Decisões
494
+ - ✅ **Logs estruturados em JSON**: parseável
495
+ - ✅ **Decorator para automação**: menos boilerplate
496
+ - ✅ **Métricas por agente**: visibilidade
497
+
498
+ ---
499
+
500
+ ## 📈 Roadmap de Implementação
501
+
502
+ ### Fase 1 (Semanas 1-2): Tier 1 Foundation
503
+ - [ ] SEC-001, SEC-002: Validação + Rate-limiting
504
+ - [ ] AGENT-001, AGENT-002: Prompts estruturados
505
+ - [ ] AI-OPT-001: Context packing model-aware
506
+ - [ ] ADR-001: Estrutura robusta
507
+ - [ ] MEM-001: 3 níveis de compactação
508
+ - [ ] DOC-001: Estrutura de documentação
509
+ - [ ] AGILE-001, AGILE-002: Sprint template + DoD
510
+ - [ ] OBS-001: Logs estruturados
511
+
512
+ ### Fase 2 (Semanas 3-4): Tier 1 Completion
513
+ - [ ] SEC-003, SEC-004: Sanitização + Testes
514
+ - [ ] AGENT-003, AGENT-004, AGENT-005: Handoff, roteamento, schema
515
+ - [ ] AI-OPT-002 até AI-OPT-005: Advanced AI optimization
516
+ - [ ] ADR-002, ADR-003, ADR-004: Versionamento + BD + integração
517
+ - [ ] MEM-002 até MEM-005: Compactação inteligente + recovery
518
+ - [ ] DOC-002 até DOC-005: Padrão + diagramas + changelog
519
+ - [ ] AGILE-003, AGILE-004, AGILE-005: Ceremônias + matriz + release notes
520
+ - [ ] OBS-002 até OBS-005: Decorator + métricas + tracing + dashboard
521
+
522
+ ### Fase 3 (Semanas 5-6): Tier 2 + Integração
523
+ - Documentação de Produto (completa)
524
+ - Metodologia Ágil (full ceremonies)
525
+ - Observabilidade (full stack)
526
+
527
+ ---
528
+
529
+ ## 💾 Rastreamento em Banco de Dados
530
+
531
+ Todos os items estão registrados na tabela `improvement_items`:
532
+
533
+ ```sql
534
+ SELECT * FROM improvement_items
535
+ WHERE status != 'done'
536
+ ORDER BY area_id, complexity;
537
+
538
+ -- Atualizar status conforme progresso
539
+ UPDATE improvement_items SET status = 'in_progress'
540
+ WHERE id = 'SEC-001';
541
+ ```
542
+
543
+ Decisões vinculadas em `decisions`:
544
+
545
+ ```sql
546
+ SELECT d.* FROM decisions d
547
+ JOIN improvement_items i ON d.item_id = i.id
548
+ WHERE i.area_id = 'ai-optimization'
549
+ ORDER BY d.created_at DESC;
550
+ ```
551
+
552
+ ---
553
+
554
+ ## ✨ Próximos Passos
555
+
556
+ 1. **Review este documento** com stakeholders
557
+ 2. **Ajustar prioridades** se necessário
558
+ 3. **Começar Fase 1** na próxima sprint
559
+ 4. **Atualizar BD** conforme progresso
560
+ 5. **Documentar decisões** em ADRs quando relevante
561
+
562
+ ---
563
+
564
+ **Versão**: 1.0 | **Data**: 2026-04-21 | **Autor**: Copilot Analysis | **Status**: Aceito para Implementação
565
+