forjajs 2.0.4 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (798) 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 +50 -50
  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 +133 -133
  16. package/CHANGELOG.md +619 -555
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +64 -60
  19. package/LICENSE +21 -21
  20. package/README.md +404 -343
  21. package/README.pt-BR.md +374 -345
  22. package/boilerplates/01-api-rest/README.md +336 -336
  23. package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
  24. package/boilerplates/02-saas-starter/.env.example +25 -25
  25. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
  26. package/boilerplates/02-saas-starter/INFO.md +252 -252
  27. package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
  28. package/boilerplates/02-saas-starter/README.md +305 -305
  29. package/boilerplates/02-saas-starter/START-HERE.md +259 -259
  30. package/boilerplates/02-saas-starter/backend/package.json +87 -87
  31. package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
  32. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
  33. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
  34. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
  35. package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
  36. package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
  37. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
  38. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
  39. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
  40. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
  41. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
  42. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
  43. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
  44. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
  45. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
  46. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
  47. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
  48. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
  49. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
  50. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
  51. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
  52. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
  53. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
  54. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
  55. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
  56. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
  57. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
  58. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
  59. package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
  60. package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
  61. package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
  62. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
  63. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
  64. package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
  65. package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
  66. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
  67. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
  68. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
  69. package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
  70. package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
  71. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
  72. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
  73. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
  74. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
  75. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
  76. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
  77. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
  78. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
  79. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
  80. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
  81. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
  82. package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
  83. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
  84. package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
  85. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
  86. package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
  87. package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
  88. package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
  89. package/boilerplates/03-ecommerce-starter/README.md +465 -465
  90. package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
  91. package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
  92. package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
  93. package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
  94. package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
  95. package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
  96. package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
  97. package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
  98. package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
  99. package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
  100. package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
  101. package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
  102. package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
  103. package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
  104. package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
  105. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
  106. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
  107. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
  108. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
  109. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
  110. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
  111. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
  112. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
  113. package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
  114. package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
  115. package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
  116. package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
  117. package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
  118. package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
  119. package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
  120. package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
  121. package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
  122. package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
  123. package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
  124. package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
  125. package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
  126. package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
  127. package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
  128. package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
  129. package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
  130. package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
  131. package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
  132. package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
  133. package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
  134. package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
  135. package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
  136. package/boilerplates/04-microservices-starter/.env.example +43 -43
  137. package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
  138. package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
  139. package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
  140. package/boilerplates/04-microservices-starter/INDEX.md +377 -377
  141. package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
  142. package/boilerplates/04-microservices-starter/README.md +466 -466
  143. package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
  144. package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
  145. package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
  146. package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
  147. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
  148. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
  149. package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
  150. package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
  151. package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
  152. package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
  153. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
  154. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
  155. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
  156. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
  157. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
  158. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
  159. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
  160. package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
  161. package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
  162. package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
  163. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
  164. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
  165. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
  166. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
  167. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
  168. package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
  169. package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
  170. package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
  171. package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
  172. package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
  173. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
  174. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
  175. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
  176. package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
  177. package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
  178. package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
  179. package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
  180. package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
  181. package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
  182. package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
  183. package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
  184. package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
  185. package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
  186. package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
  187. package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
  188. package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
  189. package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
  190. package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
  191. package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
  192. package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
  193. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
  194. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
  195. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
  196. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
  197. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
  198. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
  199. package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
  200. package/boilerplates/04-microservices-starter/package.json +21 -21
  201. package/boilerplates/05-monorepo-starter/.env.example +1 -1
  202. package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
  203. package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
  204. package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
  205. package/boilerplates/05-monorepo-starter/README.md +318 -318
  206. package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
  207. package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
  208. package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
  209. package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
  210. package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
  211. package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
  212. package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
  213. package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
  214. package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
  215. package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
  216. package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
  217. package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
  218. package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
  219. package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
  220. package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
  221. package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
  222. package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
  223. package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
  224. package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
  225. package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
  226. package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
  227. package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
  228. package/boilerplates/05-monorepo-starter/package.json +30 -30
  229. package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
  230. package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
  231. package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
  232. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
  233. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
  234. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
  235. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
  236. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
  237. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
  238. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
  239. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
  240. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
  241. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
  242. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
  243. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
  244. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
  245. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
  246. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
  247. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
  248. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
  249. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
  250. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
  251. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
  252. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
  253. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
  254. package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
  255. package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
  256. package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
  257. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
  258. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
  259. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
  260. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
  261. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
  262. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
  263. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
  264. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
  265. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
  266. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
  267. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
  268. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
  269. package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
  270. package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
  271. package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
  272. package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
  273. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
  274. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
  275. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
  276. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
  277. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
  278. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
  279. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
  280. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
  281. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
  282. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
  283. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
  284. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
  285. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
  286. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
  287. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
  288. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
  289. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
  290. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
  291. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
  292. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
  293. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
  294. package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
  295. package/boilerplates/05-monorepo-starter/turbo.json +35 -35
  296. package/boilerplates/06-clean-arch/README.md +48 -48
  297. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
  298. package/boilerplates/06-clean-arch/backend/package.json +43 -43
  299. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
  300. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
  301. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
  302. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
  303. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
  304. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
  305. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
  306. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
  307. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
  308. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
  309. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
  310. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
  311. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
  312. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
  313. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
  314. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
  315. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
  316. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
  317. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
  318. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
  319. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
  320. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
  321. package/boilerplates/README.md +427 -427
  322. package/design-md/BRIEF-TEMPLATE.md +47 -47
  323. package/design-md/INDEX.md +35 -35
  324. package/design-md/MATRIX.md +24 -24
  325. package/design-md/PLAYBOOK.md +35 -35
  326. package/design-md/examples/agent-console-brief.md +48 -48
  327. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  328. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  329. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  330. package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
  331. package/dist/apps/server/src/forja-nest.module.js +9 -4
  332. package/dist/apps/server/src/main.js +10 -1
  333. package/dist/bin/create-memory-nest-kit.js +17 -17
  334. package/dist/bin/init-project.js +38 -38
  335. package/dist/lib/audit.js +7 -7
  336. package/dist/lib/code-context.js +6 -0
  337. package/dist/lib/context-builder.js +32 -32
  338. package/dist/lib/core/architecture-gate.d.ts +20 -0
  339. package/dist/lib/core/architecture-gate.js +60 -0
  340. package/dist/lib/core/drift-gate.d.ts +18 -0
  341. package/dist/lib/core/drift-gate.js +55 -0
  342. package/dist/lib/core/gates.d.ts +9 -2
  343. package/dist/lib/core/gates.js +13 -2
  344. package/dist/lib/core/health.js +15 -0
  345. package/dist/lib/core/incident-search.d.ts +19 -0
  346. package/dist/lib/core/incident-search.js +32 -0
  347. package/dist/lib/core/model-pricing.d.ts +31 -0
  348. package/dist/lib/core/model-pricing.js +74 -0
  349. package/dist/lib/core/registry.d.ts +194 -0
  350. package/dist/lib/core/registry.js +194 -0
  351. package/dist/lib/core/release.d.ts +194 -0
  352. package/dist/lib/core/risk-collect.d.ts +19 -0
  353. package/dist/lib/core/risk-collect.js +173 -0
  354. package/dist/lib/drift-sentinel.d.ts +59 -0
  355. package/dist/lib/drift-sentinel.js +126 -0
  356. package/dist/lib/generators/memory-generator.js +691 -691
  357. package/dist/lib/generators/nest-generator.js +412 -398
  358. package/dist/lib/generators/readme-generator.js +180 -180
  359. package/dist/lib/governance-report.js +39 -39
  360. package/dist/lib/workspace.js +29 -29
  361. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  362. package/dist/packages/adapter-git/src/index.js +11 -6
  363. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  364. package/dist/packages/adapter-nest/src/index.js +26 -1
  365. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  366. package/dist/packages/adapter-sqlite/src/index.js +61 -12
  367. package/dist/packages/contracts/src/index.d.ts +33 -0
  368. package/dist/packages/contracts/src/index.js +13 -0
  369. package/dist/packages/core/src/index.d.ts +12 -0
  370. package/dist/packages/core/src/index.js +29 -0
  371. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  372. package/dist/packages/engineering/architecture/src/index.js +131 -0
  373. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  374. package/dist/packages/engineering/evidence/src/index.js +31 -0
  375. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  376. package/dist/packages/engineering/identity/src/index.js +88 -0
  377. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  378. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  379. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  380. package/dist/packages/engineering/provenance/src/index.js +21 -0
  381. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  382. package/dist/packages/engineering/risk/src/index.js +120 -0
  383. package/dist/packages/graph/src/index.d.ts +23 -1
  384. package/dist/packages/graph/src/index.js +88 -15
  385. package/dist/packages/llm/src/index.js +27 -4
  386. package/dist/packages/mcp/src/index.js +27 -8
  387. package/dist/packages/orchestration/src/index.d.ts +11 -1
  388. package/dist/packages/orchestration/src/index.js +34 -7
  389. package/dist/packages/policy/src/index.d.ts +40 -0
  390. package/dist/packages/policy/src/index.js +39 -4
  391. package/dist/packages/runtime/src/index.js +3 -0
  392. package/dist/packages/sandbox/src/index.d.ts +47 -0
  393. package/dist/packages/sandbox/src/index.js +59 -0
  394. package/dist/packages/validator/src/index.d.ts +8 -0
  395. package/dist/packages/validator/src/index.js +21 -6
  396. package/dist/scripts/adr.d.ts +17 -0
  397. package/dist/scripts/adr.js +152 -0
  398. package/dist/scripts/agent-harness.js +72 -64
  399. package/dist/scripts/agent-router.js +20 -20
  400. package/dist/scripts/agent.d.ts +27 -0
  401. package/dist/scripts/agent.js +249 -0
  402. package/dist/scripts/architecture.d.ts +16 -0
  403. package/dist/scripts/architecture.js +186 -0
  404. package/dist/scripts/build-smart-context.js +22 -22
  405. package/dist/scripts/compress-memory.js +8 -8
  406. package/dist/scripts/context-ops.js +29 -29
  407. package/dist/scripts/cost-economy.d.ts +2 -0
  408. package/dist/scripts/cost-economy.js +79 -0
  409. package/dist/scripts/demo-autonomy.js +13 -6
  410. package/dist/scripts/dev.js +13 -13
  411. package/dist/scripts/drift-check.d.ts +17 -0
  412. package/dist/scripts/drift-check.js +63 -0
  413. package/dist/scripts/engineer.d.ts +20 -0
  414. package/dist/scripts/engineer.js +208 -0
  415. package/dist/scripts/evidence.d.ts +12 -0
  416. package/dist/scripts/evidence.js +55 -0
  417. package/dist/scripts/extract-global-knowledge.js +5 -5
  418. package/dist/scripts/gates.d.ts +6 -2
  419. package/dist/scripts/gates.js +14 -4
  420. package/dist/scripts/generate-dashboard.js +11 -11
  421. package/dist/scripts/incident.d.ts +19 -0
  422. package/dist/scripts/incident.js +103 -0
  423. package/dist/scripts/llm-fit.js +32 -3
  424. package/dist/scripts/memory-schema.js +48 -48
  425. package/dist/scripts/provenance.d.ts +14 -0
  426. package/dist/scripts/provenance.js +114 -0
  427. package/dist/scripts/query-universal-memory.js +13 -13
  428. package/dist/scripts/risk.d.ts +15 -0
  429. package/dist/scripts/risk.js +81 -0
  430. package/dist/scripts/simulate.d.ts +20 -0
  431. package/dist/scripts/simulate.js +150 -0
  432. package/dist/scripts/sprint-manager.js +39 -39
  433. package/dist/scripts/sync-universal-memory.js +44 -44
  434. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  435. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  436. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  437. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  438. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  439. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  440. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  441. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  442. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  443. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  444. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  445. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  446. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  447. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  448. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  449. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  450. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  451. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  452. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  453. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  454. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  455. package/docs/agent-harnesses.md +149 -149
  456. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  457. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  458. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  459. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  460. package/docs/archive/FASE2-SUMMARY.md +263 -263
  461. package/docs/archive/FASE3-PROGRESS.md +355 -355
  462. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  463. package/docs/archive/INDICE-MASTER.md +282 -282
  464. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  465. package/docs/archive/README-REFINAMENTO.md +293 -293
  466. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  467. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  468. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  469. package/docs/archive/START-HERE.md +319 -319
  470. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  471. package/docs/archive/examples/v1/AGENTS.md +10 -10
  472. package/docs/archive/examples/v1/README.md +36 -36
  473. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  474. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  475. package/docs/archive/examples/v1/backend/package.json +42 -42
  476. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  477. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  478. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  479. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  480. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  481. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  482. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  483. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  484. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  485. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  486. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  487. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  488. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  489. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  490. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  491. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  492. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  493. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  494. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  495. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  496. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  497. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  498. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  499. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  500. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  501. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  502. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  503. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  504. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  505. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  506. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  507. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  508. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  509. package/docs/archive/examples/v2/AGENTS.md +16 -16
  510. package/docs/archive/examples/v2/README.md +35 -35
  511. package/docs/archive/examples/v2/agents/README.md +3 -3
  512. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  513. package/docs/archive/examples/v2/agents/dba.md +4 -4
  514. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  515. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  516. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  517. package/docs/archive/examples/v2/agents/security.md +4 -4
  518. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  519. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  520. package/docs/archive/examples/v2/backend/package.json +42 -42
  521. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  522. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  523. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  524. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  525. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  526. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  527. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  528. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  529. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  530. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  531. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  532. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  533. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  534. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  535. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  536. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  537. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  538. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  539. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  540. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  541. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  542. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  543. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  544. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  545. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  546. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  547. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  548. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  549. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  550. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  551. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  552. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  553. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  554. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  555. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  556. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  557. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  558. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  559. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  560. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  561. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  562. package/docs/archive/examples/v2/memory/README.md +8 -8
  563. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  564. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  565. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  566. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  567. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  568. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  569. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  570. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  571. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  572. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  573. package/docs/capacidades-externas.md +86 -86
  574. package/docs/cli-first-operacao.md +74 -74
  575. package/docs/dev-workflow.md +421 -421
  576. package/docs/examples.md +546 -546
  577. package/docs/fluxo.md +103 -103
  578. package/docs/glossary.md +453 -453
  579. package/docs/init-project.md +457 -457
  580. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  581. package/docs/personas/architect/README.md +333 -333
  582. package/docs/personas/developer/README.md +371 -371
  583. package/docs/personas/executive/README.md +172 -172
  584. package/docs/personas/qa/README.md +350 -350
  585. package/docs/processo-projeto.md +138 -138
  586. package/docs/publishing.md +377 -377
  587. package/docs/quick-reference.md +409 -409
  588. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  589. package/docs/structure.md +360 -360
  590. package/docs/token-optimization.md +502 -502
  591. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  592. package/memory/00-global/mission.md +15 -15
  593. package/memory/00-global/shared-knowledge.md +8 -8
  594. package/memory/00-global/standards.md +47 -47
  595. package/memory/10-product/personas.md +21 -21
  596. package/memory/10-product/vision.md +27 -27
  597. package/memory/30-projects/README.md +15 -15
  598. package/memory/40-delivery/backlog.md +15 -15
  599. package/memory/40-delivery/current-sprint.md +20 -20
  600. package/memory/50-orchestration/gsd-harness.md +55 -55
  601. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  602. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  603. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  604. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  605. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  606. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  607. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  608. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  609. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  610. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  611. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  612. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  613. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  614. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  615. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  616. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  617. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  618. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  619. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  620. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  621. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  622. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  623. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  624. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  625. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  626. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  627. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  628. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  629. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  630. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  631. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  632. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  633. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  634. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  635. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  636. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  637. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  638. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  639. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  640. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  641. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  642. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  643. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  644. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  645. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  646. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  647. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  648. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  649. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  650. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  651. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  652. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  653. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  654. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  655. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  656. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  657. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  658. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  659. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  660. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  661. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  662. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  663. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  664. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  665. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  666. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  667. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  668. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  669. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  670. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  671. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  672. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  673. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  674. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  675. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  676. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  677. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  678. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  679. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  680. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  681. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  682. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  683. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  684. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  685. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  686. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  687. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  688. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  689. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  690. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  691. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  692. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  693. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  694. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  695. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  696. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  697. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  698. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  699. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  700. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  701. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  702. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  703. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  704. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  705. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  706. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  707. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  708. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  709. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  710. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  711. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  712. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  713. package/memory/90-decisions/_template.md +28 -28
  714. package/package.json +157 -157
  715. package/prompts/context-engineer-agent.md +19 -19
  716. package/prompts/governance-agent.md +16 -16
  717. package/prompts/marketing-agent.md +13 -13
  718. package/prompts/orchestrator-agent.md +18 -18
  719. package/prompts/product-agent.md +13 -13
  720. package/prompts/sdd-architect-agent.md +20 -20
  721. package/specs/README.md +70 -70
  722. package/specs/_templates/plan.md +43 -43
  723. package/specs/_templates/spec.md +43 -43
  724. package/specs/_templates/tasks.md +32 -32
  725. package/specs/agent-identity-reputation/plan.md +133 -0
  726. package/specs/agent-identity-reputation/spec.md +125 -0
  727. package/specs/agent-identity-reputation/tasks.md +51 -0
  728. package/specs/agent-runtime-monitoring/plan.md +78 -0
  729. package/specs/agent-runtime-monitoring/spec.md +92 -0
  730. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  731. package/specs/ai-code-provenance/plan.md +71 -0
  732. package/specs/ai-code-provenance/spec.md +97 -0
  733. package/specs/ai-code-provenance/tasks.md +39 -0
  734. package/specs/architecture-constitution/plan.md +110 -0
  735. package/specs/architecture-constitution/spec.md +114 -0
  736. package/specs/architecture-constitution/tasks.md +58 -0
  737. package/specs/change-risk-engine/plan.md +130 -0
  738. package/specs/change-risk-engine/spec.md +119 -0
  739. package/specs/change-risk-engine/tasks.md +72 -0
  740. package/specs/clean-arch-boilerplate/plan.md +137 -137
  741. package/specs/clean-arch-boilerplate/spec.md +121 -121
  742. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  743. package/specs/cli-first-operacao/plan.md +53 -53
  744. package/specs/cli-first-operacao/spec.md +53 -53
  745. package/specs/cli-first-operacao/tasks.md +53 -53
  746. package/specs/code-context/spec.md +56 -56
  747. package/specs/coerencia-do-sistema/plan.md +155 -155
  748. package/specs/coerencia-do-sistema/spec.md +123 -123
  749. package/specs/coerencia-do-sistema/tasks.md +115 -115
  750. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  751. package/specs/dev-token-assets-db/plan.md +71 -71
  752. package/specs/dev-token-assets-db/spec.md +58 -58
  753. package/specs/dev-token-assets-db/tasks.md +58 -58
  754. package/specs/doctor-do-nucleo/plan.md +165 -165
  755. package/specs/doctor-do-nucleo/spec.md +139 -139
  756. package/specs/doctor-do-nucleo/tasks.md +172 -172
  757. package/specs/drift-sentinel/spec.md +117 -0
  758. package/specs/engineer-facade-extension/plan.md +71 -0
  759. package/specs/engineer-facade-extension/spec.md +98 -0
  760. package/specs/engineer-facade-extension/tasks.md +36 -0
  761. package/specs/engineering-evidence-ledger/plan.md +121 -0
  762. package/specs/engineering-evidence-ledger/spec.md +90 -0
  763. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  764. package/specs/engineering-graph-extensions/plan.md +92 -0
  765. package/specs/engineering-graph-extensions/spec.md +101 -0
  766. package/specs/engineering-graph-extensions/tasks.md +60 -0
  767. package/specs/engineering-intelligence/spec.md +177 -0
  768. package/specs/forja-core/spec.md +71 -71
  769. package/specs/gates/spec.md +63 -63
  770. package/specs/governanca-visivel/plan.md +122 -122
  771. package/specs/governanca-visivel/spec.md +112 -112
  772. package/specs/governanca-visivel/tasks.md +60 -60
  773. package/specs/harness-codegraph/spec.md +71 -71
  774. package/specs/learning-loop-incidents/plan.md +59 -0
  775. package/specs/learning-loop-incidents/spec.md +93 -0
  776. package/specs/learning-loop-incidents/tasks.md +36 -0
  777. package/specs/memory-audit/spec.md +54 -54
  778. package/specs/orchestrate/spec.md +108 -108
  779. package/specs/orchestration-coherent/spec.md +95 -95
  780. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  781. package/specs/predictive-change-simulation/plan.md +109 -0
  782. package/specs/predictive-change-simulation/spec.md +107 -0
  783. package/specs/predictive-change-simulation/tasks.md +41 -0
  784. package/specs/project-smoke/spec.md +96 -96
  785. package/specs/project-upgrade/spec.md +58 -58
  786. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  787. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  788. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  789. package/specs/release-auditor-health/spec.md +23 -23
  790. package/specs/release-gate/plan.md +174 -174
  791. package/specs/release-gate/spec.md +122 -122
  792. package/specs/release-gate/tasks.md +183 -183
  793. package/specs/smart-agent-routing/plan.md +55 -0
  794. package/specs/smart-agent-routing/spec.md +85 -0
  795. package/specs/smart-agent-routing/tasks.md +26 -0
  796. package/specs/ts-migration/plan.md +200 -200
  797. package/specs/ts-migration/spec.md +119 -119
  798. package/specs/ts-migration/tasks.md +110 -110
@@ -1,108 +1,108 @@
1
- # Spec: orchestrate — o motor de orquestração (exploratória, 2.0)
2
-
3
- - **ID**: SPEC-021
4
- - **Status**: done
5
- - **Owner**: apk
6
- - **ADRs relacionadas**: ADR-0005 (handoff 7 campos), ADR-0019 (workspace), ADR-0020 (core/registry), SPEC-019 (topologia coerente), ADR-0023/0024/0029 (os gates), ADR-0009 (memória)
7
-
8
- > **Exploratória.** O objetivo desta spec não é fechar o escopo — é tornar o conceito concreto o
9
- > bastante para decidir o formato, e expor as decisões duras antes de virar plano. As perguntas
10
- > abertas da §8 são o coração; as respostas remodelam o resto.
11
-
12
- ## 1. Problema
13
-
14
- O nome do framework é **orquestração multiagente**. A SPEC-019 provou que a topologia é *coerente* —
15
- mas orquestração coerente não é orquestração que **acontece**. Hoje um fluxo multi-papel (product →
16
- architect → worker → governance) vive em três lugares soltos: a prosa do `AGENTS.md`, os handoffs
17
- avulsos do `agent-router` (cada um independente, sem noção de cadeia), e a disciplina de quem lembra
18
- de rodar `spec:check` entre uma etapa e outra. **Não existe uma cadeia que roda, gate a gate.** O
19
- namesake é a última grande superfície que ainda vive por disciplina.
20
-
21
- ## 2. A tensão central (a decisão que organiza tudo)
22
-
23
- **O framework não roda IA autonomamente.** Ele não pode "chamar o Claude e mandar implementar". Quem
24
- executa o *trabalho* de cada papel é um agente de IA (sub-agent do Claude Code) ou um humano.
25
-
26
- Então "orquestração que executa" **não** pode significar "o framework faz o trabalho". Significa:
27
-
28
- > O framework é a **máquina de estados da cadeia de handoffs**, com **transições guardadas por
29
- > gates**. Ele decompõe o objetivo, abre o handoff certo, roda o gate quando a etapa fecha, e — se o
30
- > gate passa — abre a próxima; se falha, trava com o parecer. O *trabalho* dentro de cada etapa é de
31
- > quem pega o handoff. **O framework orquestra e guarda; o agente executa.**
32
-
33
- Isto é honesto (não finge autonomia de IA) e ainda assim é um motor de execução real: a cadeia
34
- progride dirigida por **veredito de gate**, não por memória. É o pipeline SDD/GSD virado máquina.
35
-
36
- ## 3. Proposta de valor
37
-
38
- Um objetivo vira uma **cadeia auditável e guardada**: cada etapa só abre quando a anterior passou no
39
- seu gate. A pergunta "o processo foi seguido?" deixa de ser uma promessa e vira o estado de uma
40
- máquina — e a governança do Forja chega ao próprio ato de orquestrar.
41
-
42
- ## 4. Formato proposto (v1 — a discutir)
43
-
44
- ```bash
45
- forja orchestrate "adicionar pagamento pix" --slug pagamentos-pix
46
- # → decompõe numa cadeia de handoffs (o runbook), abre a 1ª etapa
47
-
48
- forja orchestrate:status pagamentos-pix
49
- # → o estado da máquina: etapa aberta, feitas, bloqueadas, último veredito de gate
50
-
51
- forja orchestrate:advance pagamentos-pix
52
- # → o dono da etapa atual fez o trabalho; roda o GATE da etapa;
53
- # verde → fecha o handoff + abre o próximo; vermelho → trava com o parecer
54
- ```
55
-
56
- **A cadeia (v1, determinística — o pipeline SDD/GSD):**
57
-
58
- | # | Papel | Etapa | Gate da transição |
59
- |---|---|---|---|
60
- | 1 | product | `spec` | `spec:check` (spec aprovada) |
61
- | 2 | sdd-architect | `plan` | `spec:check` (plan aprovado) |
62
- | 3 | sdd-architect | `tasks` | `spec:check` (tasks aprovado) |
63
- | 4 | worker | `implement` | `project:check` / `code:check` |
64
- | 5 | governance | `review` | `check:all` |
65
-
66
- Cada transição é um handoff ADR-0005 (7 campos) gravado pelo `agent-router`, e cada `advance` é uma
67
- linha na trilha de auditoria. A topologia coerente da SPEC-019 é o grafo que a máquina percorre.
68
-
69
- ## 5. Escopo
70
-
71
- **Dentro (v1)**:
72
- - A máquina de estados da cadeia (decompor → abrir → gate → avançar/travar), sobre o `agent-router`.
73
- - Gates como transições: a etapa não avança sem o gate verde.
74
- - `orchestrate` / `orchestrate:status` / `orchestrate:advance` no registry; tudo auditado.
75
-
76
- **Fora (explícito — a fronteira honesta)**:
77
- - **Rodar a IA que faz o trabalho de cada etapa.** Isso é o Claude Code (ou o humano) que pega o
78
- handoff aberto. O framework abre a etapa e a guarda; não a executa.
79
- - **Decomposição por LLM.** v1 usa a cadeia determinística do SDD/GSD — provável e auditável. Um
80
- planejador de IA que monta cadeias sob medida é evolução, não a base.
81
- - Paralelismo / cadeias ramificadas — v1 é linear. Ramos e fan-out ficam para depois.
82
-
83
- ## 6. Riscos
84
-
85
- | Risco | Prob. | Impacto | Mitigação |
86
- |---|---|---|---|
87
- | Virar "só um wrapper do agent-router + gates" (pouco valor) | M | A | o valor é a **transição guardada** — a etapa que não avança sem o gate; isso não existe hoje |
88
- | Acoplar ao Claude Code e ferir a promessa multi-IA | M | M | o motor é agnóstico: abre handoffs; *quem* os pega (Claude/humano/outra IA) é externo |
89
- | Reimplementar o que o SDD já faz | B | M | compõe `spec:check`/`project:check`/`check:all` — não reimplementa gate nenhum |
90
-
91
- ## 7. Métricas de sucesso
92
-
93
- Um objetivo levado do `orchestrate` até o `review` com **cada transição guardada por um gate verde**,
94
- a corrida inteira reconstruível a partir do `forja-runs.jsonl` — e uma tentativa de pular etapa
95
- (avançar com o gate vermelho) **bloqueada** pela máquina. A orquestração deixa de ser prosa.
96
-
97
- ## 8. Decisões (aprovadas)
98
-
99
- 1. **`advance` manual.** O dono da etapa roda `orchestrate:advance` quando terminou; o motor roda o
100
- gate e decide. Acionar o sub-agent automaticamente fica para uma iteração futura — decidida com os
101
- dados do uso manual.
102
- 2. **Roda onde é invocado (`cwd`).** Framework primeiro como dogfood; por construção da 1.6.2 (o
103
- dispatcher propaga o cwd), o mesmo motor funciona num projeto consumidor sem código extra. O
104
- estado vive em `<cwd>/.context/orchestrate-<slug>.json`, ao lado dos runbooks GSD.
105
- 3. **Cadeia determinística SDD/GSD no v1.** Auditável e provável. Planejador de IA é evolução.
106
- 4. **O motor é a v1.7.0** (aditivo, não quebra nada). O 2.0 fica para a limpeza breaking
107
- (`dashboard/`, `projects/`, Node ≥22.6 formal) + o salto de identidade escolhido com os dados do
108
- motor em uso.
1
+ # Spec: orchestrate — o motor de orquestração (exploratória, 2.0)
2
+
3
+ - **ID**: SPEC-021
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0005 (handoff 7 campos), ADR-0019 (workspace), ADR-0020 (core/registry), SPEC-019 (topologia coerente), ADR-0023/0024/0029 (os gates), ADR-0009 (memória)
7
+
8
+ > **Exploratória.** O objetivo desta spec não é fechar o escopo — é tornar o conceito concreto o
9
+ > bastante para decidir o formato, e expor as decisões duras antes de virar plano. As perguntas
10
+ > abertas da §8 são o coração; as respostas remodelam o resto.
11
+
12
+ ## 1. Problema
13
+
14
+ O nome do framework é **orquestração multiagente**. A SPEC-019 provou que a topologia é *coerente* —
15
+ mas orquestração coerente não é orquestração que **acontece**. Hoje um fluxo multi-papel (product →
16
+ architect → worker → governance) vive em três lugares soltos: a prosa do `AGENTS.md`, os handoffs
17
+ avulsos do `agent-router` (cada um independente, sem noção de cadeia), e a disciplina de quem lembra
18
+ de rodar `spec:check` entre uma etapa e outra. **Não existe uma cadeia que roda, gate a gate.** O
19
+ namesake é a última grande superfície que ainda vive por disciplina.
20
+
21
+ ## 2. A tensão central (a decisão que organiza tudo)
22
+
23
+ **O framework não roda IA autonomamente.** Ele não pode "chamar o Claude e mandar implementar". Quem
24
+ executa o *trabalho* de cada papel é um agente de IA (sub-agent do Claude Code) ou um humano.
25
+
26
+ Então "orquestração que executa" **não** pode significar "o framework faz o trabalho". Significa:
27
+
28
+ > O framework é a **máquina de estados da cadeia de handoffs**, com **transições guardadas por
29
+ > gates**. Ele decompõe o objetivo, abre o handoff certo, roda o gate quando a etapa fecha, e — se o
30
+ > gate passa — abre a próxima; se falha, trava com o parecer. O *trabalho* dentro de cada etapa é de
31
+ > quem pega o handoff. **O framework orquestra e guarda; o agente executa.**
32
+
33
+ Isto é honesto (não finge autonomia de IA) e ainda assim é um motor de execução real: a cadeia
34
+ progride dirigida por **veredito de gate**, não por memória. É o pipeline SDD/GSD virado máquina.
35
+
36
+ ## 3. Proposta de valor
37
+
38
+ Um objetivo vira uma **cadeia auditável e guardada**: cada etapa só abre quando a anterior passou no
39
+ seu gate. A pergunta "o processo foi seguido?" deixa de ser uma promessa e vira o estado de uma
40
+ máquina — e a governança do Forja chega ao próprio ato de orquestrar.
41
+
42
+ ## 4. Formato proposto (v1 — a discutir)
43
+
44
+ ```bash
45
+ forja orchestrate "adicionar pagamento pix" --slug pagamentos-pix
46
+ # → decompõe numa cadeia de handoffs (o runbook), abre a 1ª etapa
47
+
48
+ forja orchestrate:status pagamentos-pix
49
+ # → o estado da máquina: etapa aberta, feitas, bloqueadas, último veredito de gate
50
+
51
+ forja orchestrate:advance pagamentos-pix
52
+ # → o dono da etapa atual fez o trabalho; roda o GATE da etapa;
53
+ # verde → fecha o handoff + abre o próximo; vermelho → trava com o parecer
54
+ ```
55
+
56
+ **A cadeia (v1, determinística — o pipeline SDD/GSD):**
57
+
58
+ | # | Papel | Etapa | Gate da transição |
59
+ |---|---|---|---|
60
+ | 1 | product | `spec` | `spec:check` (spec aprovada) |
61
+ | 2 | sdd-architect | `plan` | `spec:check` (plan aprovado) |
62
+ | 3 | sdd-architect | `tasks` | `spec:check` (tasks aprovado) |
63
+ | 4 | worker | `implement` | `project:check` / `code:check` |
64
+ | 5 | governance | `review` | `check:all` |
65
+
66
+ Cada transição é um handoff ADR-0005 (7 campos) gravado pelo `agent-router`, e cada `advance` é uma
67
+ linha na trilha de auditoria. A topologia coerente da SPEC-019 é o grafo que a máquina percorre.
68
+
69
+ ## 5. Escopo
70
+
71
+ **Dentro (v1)**:
72
+ - A máquina de estados da cadeia (decompor → abrir → gate → avançar/travar), sobre o `agent-router`.
73
+ - Gates como transições: a etapa não avança sem o gate verde.
74
+ - `orchestrate` / `orchestrate:status` / `orchestrate:advance` no registry; tudo auditado.
75
+
76
+ **Fora (explícito — a fronteira honesta)**:
77
+ - **Rodar a IA que faz o trabalho de cada etapa.** Isso é o Claude Code (ou o humano) que pega o
78
+ handoff aberto. O framework abre a etapa e a guarda; não a executa.
79
+ - **Decomposição por LLM.** v1 usa a cadeia determinística do SDD/GSD — provável e auditável. Um
80
+ planejador de IA que monta cadeias sob medida é evolução, não a base.
81
+ - Paralelismo / cadeias ramificadas — v1 é linear. Ramos e fan-out ficam para depois.
82
+
83
+ ## 6. Riscos
84
+
85
+ | Risco | Prob. | Impacto | Mitigação |
86
+ |---|---|---|---|
87
+ | Virar "só um wrapper do agent-router + gates" (pouco valor) | M | A | o valor é a **transição guardada** — a etapa que não avança sem o gate; isso não existe hoje |
88
+ | Acoplar ao Claude Code e ferir a promessa multi-IA | M | M | o motor é agnóstico: abre handoffs; *quem* os pega (Claude/humano/outra IA) é externo |
89
+ | Reimplementar o que o SDD já faz | B | M | compõe `spec:check`/`project:check`/`check:all` — não reimplementa gate nenhum |
90
+
91
+ ## 7. Métricas de sucesso
92
+
93
+ Um objetivo levado do `orchestrate` até o `review` com **cada transição guardada por um gate verde**,
94
+ a corrida inteira reconstruível a partir do `forja-runs.jsonl` — e uma tentativa de pular etapa
95
+ (avançar com o gate vermelho) **bloqueada** pela máquina. A orquestração deixa de ser prosa.
96
+
97
+ ## 8. Decisões (aprovadas)
98
+
99
+ 1. **`advance` manual.** O dono da etapa roda `orchestrate:advance` quando terminou; o motor roda o
100
+ gate e decide. Acionar o sub-agent automaticamente fica para uma iteração futura — decidida com os
101
+ dados do uso manual.
102
+ 2. **Roda onde é invocado (`cwd`).** Framework primeiro como dogfood; por construção da 1.6.2 (o
103
+ dispatcher propaga o cwd), o mesmo motor funciona num projeto consumidor sem código extra. O
104
+ estado vive em `<cwd>/.context/orchestrate-<slug>.json`, ao lado dos runbooks GSD.
105
+ 3. **Cadeia determinística SDD/GSD no v1.** Auditável e provável. Planejador de IA é evolução.
106
+ 4. **O motor é a v1.7.0** (aditivo, não quebra nada). O 2.0 fica para a limpeza breaking
107
+ (`dashboard/`, `projects/`, Node ≥22.6 formal) + o salto de identidade escolhido com os dados do
108
+ motor em uso.
@@ -1,95 +1,95 @@
1
- # Spec: orchestration-coherent
2
-
3
- - **ID**: SPEC-019
4
- - **Status**: done
5
- - **Owner**: apk
6
- - **ADRs relacionadas**: ADR-0021 (invariante > disciplina), ADR-0025 (coerência da doc — a mesma classe), ADR-0005 (handoff 7 campos), ADR-0020 (core/registry)
7
-
8
- ## 1. Problema
9
-
10
- O nome do repositório é **orquestração multiagente** — e é a parte **menos harnessed** do framework.
11
- A topologia de quem-orquestra-quem é descrita em **três lugares independentes**, e nada garante que
12
- concordem:
13
-
14
- 1. `AGENTS.md` — a prosa: os papéis e a topologia.
15
- 2. `scripts/agent-router.ts` (`VALID_AGENTS`) — o código: para quem um handoff pode ser roteado.
16
- 3. `.claude/agents/*.md` — os sub-agents executáveis: quem, de fato, faz o trabalho.
17
-
18
- Três descrições da mesma coisa divergem em silêncio. **E já divergem hoje** (medido antes de escrever
19
- esta spec — a mesma prova que o `adr-refs` deu):
20
-
21
- - **`worker`** está no `VALID_AGENTS` e no `AGENTS.md`, mas **não tem** `.claude/agent`. Um papel que
22
- recebe handoff sem definição executável — prosa que o código não implementa.
23
- - **`release-auditor`** é um sub-agent executável, mas **não está** no `VALID_AGENTS`. Um agente para
24
- o qual o router não consegue rotear — implementação que a orquestração não alcança.
25
- - **`architect`** (AGENTS.md) vs **`sdd-architect`** (router/agents) — o mesmo papel com dois nomes.
26
-
27
- Pelo critério do ADR-0021, isto não é orquestração: é sugestão. A topologia vive por disciplina, e
28
- está silenciosamente incoerente **agora**. Não é conhecimento que falta — é execução.
29
-
30
- ## 2. Proposta de valor
31
-
32
- A topologia de agentes deixa de poder divergir em silêncio: **as três fontes de verdade
33
- (AGENTS.md ↔ router ↔ .claude/agents) são conferidas por um gate**. Um papel sem agente executável,
34
- um agente sem rota, um nome divergente — tudo reprova. A orquestração descrita passa a ser a
35
- orquestração implementada.
36
-
37
- ## 3. User stories
38
-
39
- - **Como** mantenedor, **quero** que um papel citado na topologia sem sub-agent executável **reprove**,
40
- **para que** a orquestração não prometa um agente que não existe.
41
- - **Como** mantenedor, **quero** que um sub-agent para o qual o router não roteia seja apontado,
42
- **para que** eu não tenha implementação órfã que a orquestração nunca aciona.
43
- - **Como** governança, **quero** rodar isso no `tools:doctor`, **para que** a coerência da topologia
44
- seja um artefato verificável, não uma afirmação no README.
45
-
46
- ## 4. Critérios de aceite (Definition of Done)
47
-
48
- - [ ] AC-1: Um check `agent-topology` (no catálogo do `tools:doctor`, via runner de `checks.ts`)
49
- cruza as três fontes e **reprova** (ou avisa) quando divergem:
50
- - papel roteável (`VALID_AGENTS`, menos `user`) **sem** `.claude/agents/<papel>.md` → o router
51
- promete um destino que não tem executor;
52
- - `.claude/agents/<x>.md` que **não** está em `VALID_AGENTS` → agente executável que ninguém roteia;
53
- - papel citado no `AGENTS.md` que não bate com nenhuma das outras fontes → prosa órfã.
54
- - [ ] AC-2: `user` é reconhecido como destino válido de handoff **sem** exigir um agent (é o humano —
55
- não tem `.claude/agent`, e tudo bem).
56
- - [ ] AC-3: O check roda no `tools:doctor` e reporta as divergências reais que já existem hoje
57
- (`worker`, `release-auditor`, `architect`/`sdd-architect`) — a prova de que a fronteira estava
58
- descoberta.
59
- - [ ] AC-4: Fechada a incoerência: cada divergência resolvida (criar o agent, ajustar o router, ou
60
- alinhar o nome) até o check ficar verde — decidido caso a caso, não no atacado.
61
- - [ ] AC-5: Lógica pura e testável (extrai a topologia de fontes injetáveis; testes com fixtures).
62
-
63
- ## 5. Escopo
64
-
65
- **Dentro**: conferir a **coerência estrutural** da topologia — os nomes de papéis/agentes batem entre
66
- as três fontes.
67
-
68
- **Fora** (explícito — a fronteira honesta):
69
- - **Rodar os agentes de IA autonomamente.** O framework não executa um loop de IA; quem aciona os
70
- sub-agents é o Claude Code, no uso. Este gate prova que a topologia é *coerente e acionável*, não
71
- que a IA fez um bom trabalho. "Provar que a orquestração produz bom output" não é harness — é
72
- julgamento, e fica fora.
73
- - Validar o *conteúdo* de cada `.claude/agent` (o prompt está bom?) — é qualidade, não topologia.
74
- - Um motor de execução de handoffs em cadeia (state machine que dirige o fluxo) — pode ser SPEC
75
- futura; esta fecha a **coerência**, o pré-requisito de qualquer execução.
76
-
77
- ## 6. NFRs / restrições
78
-
79
- - **Compatibilidade**: só lê as três fontes; não muda o comportamento do router nem dos agents.
80
- - **Severidade honesta**: divergência que quebra a orquestração (papel roteável sem executor) =
81
- provável `critical`/`warn` a decidir no plan; nome divergente = `warn`. A calibração fica para o
82
- plan, à luz do que as divergências reais pedem.
83
-
84
- ## 7. Riscos e mitigação
85
-
86
- | Risco | Prob. | Impacto | Mitigação |
87
- |---|---|---|---|
88
- | O check vira ruído (muitos avisos aceitáveis) | M | M | severidade calibrada no plan; `user` e casos legítimos isentos (AC-2) |
89
- | Alinhar os nomes quebra referências em prosa | B | M | AC-4 resolve caso a caso, com o gate confirmando cada passo |
90
-
91
- ## 8. Métricas de sucesso
92
-
93
- As três divergências de hoje (`worker`, `release-auditor`, `architect`/`sdd-architect`) resolvidas, o
94
- `agent-topology` verde no `tools:doctor`, e uma futura divergência (um agent novo sem rota, um papel
95
- renomeado) pega pelo gate antes do merge. A orquestração descrita = a orquestração implementada.
1
+ # Spec: orchestration-coherent
2
+
3
+ - **ID**: SPEC-019
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0021 (invariante > disciplina), ADR-0025 (coerência da doc — a mesma classe), ADR-0005 (handoff 7 campos), ADR-0020 (core/registry)
7
+
8
+ ## 1. Problema
9
+
10
+ O nome do repositório é **orquestração multiagente** — e é a parte **menos harnessed** do framework.
11
+ A topologia de quem-orquestra-quem é descrita em **três lugares independentes**, e nada garante que
12
+ concordem:
13
+
14
+ 1. `AGENTS.md` — a prosa: os papéis e a topologia.
15
+ 2. `scripts/agent-router.ts` (`VALID_AGENTS`) — o código: para quem um handoff pode ser roteado.
16
+ 3. `.claude/agents/*.md` — os sub-agents executáveis: quem, de fato, faz o trabalho.
17
+
18
+ Três descrições da mesma coisa divergem em silêncio. **E já divergem hoje** (medido antes de escrever
19
+ esta spec — a mesma prova que o `adr-refs` deu):
20
+
21
+ - **`worker`** está no `VALID_AGENTS` e no `AGENTS.md`, mas **não tem** `.claude/agent`. Um papel que
22
+ recebe handoff sem definição executável — prosa que o código não implementa.
23
+ - **`release-auditor`** é um sub-agent executável, mas **não está** no `VALID_AGENTS`. Um agente para
24
+ o qual o router não consegue rotear — implementação que a orquestração não alcança.
25
+ - **`architect`** (AGENTS.md) vs **`sdd-architect`** (router/agents) — o mesmo papel com dois nomes.
26
+
27
+ Pelo critério do ADR-0021, isto não é orquestração: é sugestão. A topologia vive por disciplina, e
28
+ está silenciosamente incoerente **agora**. Não é conhecimento que falta — é execução.
29
+
30
+ ## 2. Proposta de valor
31
+
32
+ A topologia de agentes deixa de poder divergir em silêncio: **as três fontes de verdade
33
+ (AGENTS.md ↔ router ↔ .claude/agents) são conferidas por um gate**. Um papel sem agente executável,
34
+ um agente sem rota, um nome divergente — tudo reprova. A orquestração descrita passa a ser a
35
+ orquestração implementada.
36
+
37
+ ## 3. User stories
38
+
39
+ - **Como** mantenedor, **quero** que um papel citado na topologia sem sub-agent executável **reprove**,
40
+ **para que** a orquestração não prometa um agente que não existe.
41
+ - **Como** mantenedor, **quero** que um sub-agent para o qual o router não roteia seja apontado,
42
+ **para que** eu não tenha implementação órfã que a orquestração nunca aciona.
43
+ - **Como** governança, **quero** rodar isso no `tools:doctor`, **para que** a coerência da topologia
44
+ seja um artefato verificável, não uma afirmação no README.
45
+
46
+ ## 4. Critérios de aceite (Definition of Done)
47
+
48
+ - [ ] AC-1: Um check `agent-topology` (no catálogo do `tools:doctor`, via runner de `checks.ts`)
49
+ cruza as três fontes e **reprova** (ou avisa) quando divergem:
50
+ - papel roteável (`VALID_AGENTS`, menos `user`) **sem** `.claude/agents/<papel>.md` → o router
51
+ promete um destino que não tem executor;
52
+ - `.claude/agents/<x>.md` que **não** está em `VALID_AGENTS` → agente executável que ninguém roteia;
53
+ - papel citado no `AGENTS.md` que não bate com nenhuma das outras fontes → prosa órfã.
54
+ - [ ] AC-2: `user` é reconhecido como destino válido de handoff **sem** exigir um agent (é o humano —
55
+ não tem `.claude/agent`, e tudo bem).
56
+ - [ ] AC-3: O check roda no `tools:doctor` e reporta as divergências reais que já existem hoje
57
+ (`worker`, `release-auditor`, `architect`/`sdd-architect`) — a prova de que a fronteira estava
58
+ descoberta.
59
+ - [ ] AC-4: Fechada a incoerência: cada divergência resolvida (criar o agent, ajustar o router, ou
60
+ alinhar o nome) até o check ficar verde — decidido caso a caso, não no atacado.
61
+ - [ ] AC-5: Lógica pura e testável (extrai a topologia de fontes injetáveis; testes com fixtures).
62
+
63
+ ## 5. Escopo
64
+
65
+ **Dentro**: conferir a **coerência estrutural** da topologia — os nomes de papéis/agentes batem entre
66
+ as três fontes.
67
+
68
+ **Fora** (explícito — a fronteira honesta):
69
+ - **Rodar os agentes de IA autonomamente.** O framework não executa um loop de IA; quem aciona os
70
+ sub-agents é o Claude Code, no uso. Este gate prova que a topologia é *coerente e acionável*, não
71
+ que a IA fez um bom trabalho. "Provar que a orquestração produz bom output" não é harness — é
72
+ julgamento, e fica fora.
73
+ - Validar o *conteúdo* de cada `.claude/agent` (o prompt está bom?) — é qualidade, não topologia.
74
+ - Um motor de execução de handoffs em cadeia (state machine que dirige o fluxo) — pode ser SPEC
75
+ futura; esta fecha a **coerência**, o pré-requisito de qualquer execução.
76
+
77
+ ## 6. NFRs / restrições
78
+
79
+ - **Compatibilidade**: só lê as três fontes; não muda o comportamento do router nem dos agents.
80
+ - **Severidade honesta**: divergência que quebra a orquestração (papel roteável sem executor) =
81
+ provável `critical`/`warn` a decidir no plan; nome divergente = `warn`. A calibração fica para o
82
+ plan, à luz do que as divergências reais pedem.
83
+
84
+ ## 7. Riscos e mitigação
85
+
86
+ | Risco | Prob. | Impacto | Mitigação |
87
+ |---|---|---|---|
88
+ | O check vira ruído (muitos avisos aceitáveis) | M | M | severidade calibrada no plan; `user` e casos legítimos isentos (AC-2) |
89
+ | Alinhar os nomes quebra referências em prosa | B | M | AC-4 resolve caso a caso, com o gate confirmando cada passo |
90
+
91
+ ## 8. Métricas de sucesso
92
+
93
+ As três divergências de hoje (`worker`, `release-auditor`, `architect`/`sdd-architect`) resolvidas, o
94
+ `agent-topology` verde no `tools:doctor`, e uma futura divergência (um agent novo sem rota, um papel
95
+ renomeado) pega pelo gate antes do merge. A orquestração descrita = a orquestração implementada.
@@ -1,61 +1,61 @@
1
- # Spec: pipeline-sdd-e-orquestracao
2
-
3
- - **ID**: SPEC-001
4
- - **Status**: done
5
- - **Owner**: framework-team
6
- - **Criado em**: 2026-05-10
7
- - **Sprint alvo**: refator-2026-05
8
- - **ADRs relacionadas**: ADR-0007 (SDD), ADR-0008 (sub-agents executáveis)
9
-
10
- ## 1. Problema
11
- O framework declara "spec-driven" e "orquestração" no AGENTS.md mas não há mecânica: nenhum comando força spec antes de código, e os 6 papéis de AGENTS.md não têm sub-agents executáveis em `.claude/agents/`. Handoffs vivem como markdown manual em `memory/50-orchestration/handoffs/`. Resultado: cada agente reinventa formato, retrabalho alto, decisões perdidas.
12
-
13
- ## 2. Proposta de valor
14
- Toda feature não-trivial passa por `spec → plan → tasks` validado por CLI, e tarefas são roteadas para sub-agents Claude com handoff rastreável em SQLite. Spec-driven e orquestração deixam de ser slogans.
15
-
16
- ## 3. User stories
17
- - **Como** Product Agent, **quero** rascunhar uma spec em 5 min com template, **para que** o backlog tenha entrada estruturada
18
- - **Como** SDD Architect, **quero** que `spec:plan` só funcione com spec aprovada, **para que** ninguém pule etapa
19
- - **Como** Worker, **quero** receber handoff com 7 campos via tabela SQLite, **para que** eu não pesque contexto em markdown
20
- - **Como** Governance Agent, **quero** rodar `project:check` que falha se há código novo sem spec ativa, **para que** dívida não se acumule
21
-
22
- ## 4. Critérios de aceite
23
- - [x] AC-1: `npm run spec:new <feature>` cria diretório com spec.md preenchido a partir do template
24
- - [x] AC-2: `npm run spec:plan` e `spec:tasks` só rodam se a fase anterior está `approved+`
25
- - [x] AC-3: `npm run spec:check` lista status de todas as features e falha com exit≠0 se inconsistente
26
- - [ ] AC-4: `.claude/agents/*.md` para 6 papéis funcionando como sub-agents
27
- - [ ] AC-5: handoffs registrados em tabela SQLite (`universal.db.handoffs`) com 7 campos da ADR-0005
28
- - [ ] AC-6: `agent:route` aceita handoff e dispara sub-agent correspondente
29
- - [ ] AC-7: hook `UserPromptSubmit` injeta smart-context automaticamente
30
-
31
- ## 5. Escopo
32
- **Dentro**:
33
- - CLI `spec-cli.mjs` (new/plan/tasks/check)
34
- - Templates em `specs/_templates/`
35
- - 6 sub-agents em `.claude/agents/`
36
- - Tabela `handoffs` no `universal.db` + script `agent-router.mjs`
37
- - Hooks em `.claude/settings.json`
38
-
39
- **Fora**:
40
- - Embeddings semânticos (mantém FTS5)
41
- - UI/dashboard interativo de specs
42
- - Migrar handoffs antigos em markdown — só novos
43
- - Sub-agents para outros provedores (Copilot, Gemini) — só Claude nesta rodada
44
-
45
- ## 6. NFRs
46
- - Performance: `spec:check` < 500ms em 100 specs
47
- - Compatibilidade: scripts npm existentes não quebram
48
- - Segurança: nenhum script gera token/secret embedido
49
- - Observabilidade: cada invocação de sub-agent loga em `60-runs/`
50
-
51
- ## 7. Riscos
52
- | Risco | P | I | Mitigação |
53
- |---|---|---|---|
54
- | Hook UserPromptSubmit causa latência | M | M | Cache por hash do prompt + cap de bytes |
55
- | Sub-agents disputam contexto | B | A | Roteamento explícito via handoff, sem broadcast |
56
- | SDD vira burocracia | M | A | Lista clara em README de "quando NÃO precisa de spec" |
57
-
58
- ## 8. Métricas de sucesso (30d)
59
- - ≥80% das features novas atravessam o pipeline completo
60
- - 0 PRs mergeados com `spec:check` falhando
61
- - Tempo médio spec→tasks < 1 dia
1
+ # Spec: pipeline-sdd-e-orquestracao
2
+
3
+ - **ID**: SPEC-001
4
+ - **Status**: done
5
+ - **Owner**: framework-team
6
+ - **Criado em**: 2026-05-10
7
+ - **Sprint alvo**: refator-2026-05
8
+ - **ADRs relacionadas**: ADR-0007 (SDD), ADR-0008 (sub-agents executáveis)
9
+
10
+ ## 1. Problema
11
+ O framework declara "spec-driven" e "orquestração" no AGENTS.md mas não há mecânica: nenhum comando força spec antes de código, e os 6 papéis de AGENTS.md não têm sub-agents executáveis em `.claude/agents/`. Handoffs vivem como markdown manual em `memory/50-orchestration/handoffs/`. Resultado: cada agente reinventa formato, retrabalho alto, decisões perdidas.
12
+
13
+ ## 2. Proposta de valor
14
+ Toda feature não-trivial passa por `spec → plan → tasks` validado por CLI, e tarefas são roteadas para sub-agents Claude com handoff rastreável em SQLite. Spec-driven e orquestração deixam de ser slogans.
15
+
16
+ ## 3. User stories
17
+ - **Como** Product Agent, **quero** rascunhar uma spec em 5 min com template, **para que** o backlog tenha entrada estruturada
18
+ - **Como** SDD Architect, **quero** que `spec:plan` só funcione com spec aprovada, **para que** ninguém pule etapa
19
+ - **Como** Worker, **quero** receber handoff com 7 campos via tabela SQLite, **para que** eu não pesque contexto em markdown
20
+ - **Como** Governance Agent, **quero** rodar `project:check` que falha se há código novo sem spec ativa, **para que** dívida não se acumule
21
+
22
+ ## 4. Critérios de aceite
23
+ - [x] AC-1: `npm run spec:new <feature>` cria diretório com spec.md preenchido a partir do template
24
+ - [x] AC-2: `npm run spec:plan` e `spec:tasks` só rodam se a fase anterior está `approved+`
25
+ - [x] AC-3: `npm run spec:check` lista status de todas as features e falha com exit≠0 se inconsistente
26
+ - [ ] AC-4: `.claude/agents/*.md` para 6 papéis funcionando como sub-agents
27
+ - [ ] AC-5: handoffs registrados em tabela SQLite (`universal.db.handoffs`) com 7 campos da ADR-0005
28
+ - [ ] AC-6: `agent:route` aceita handoff e dispara sub-agent correspondente
29
+ - [ ] AC-7: hook `UserPromptSubmit` injeta smart-context automaticamente
30
+
31
+ ## 5. Escopo
32
+ **Dentro**:
33
+ - CLI `spec-cli.mjs` (new/plan/tasks/check)
34
+ - Templates em `specs/_templates/`
35
+ - 6 sub-agents em `.claude/agents/`
36
+ - Tabela `handoffs` no `universal.db` + script `agent-router.mjs`
37
+ - Hooks em `.claude/settings.json`
38
+
39
+ **Fora**:
40
+ - Embeddings semânticos (mantém FTS5)
41
+ - UI/dashboard interativo de specs
42
+ - Migrar handoffs antigos em markdown — só novos
43
+ - Sub-agents para outros provedores (Copilot, Gemini) — só Claude nesta rodada
44
+
45
+ ## 6. NFRs
46
+ - Performance: `spec:check` < 500ms em 100 specs
47
+ - Compatibilidade: scripts npm existentes não quebram
48
+ - Segurança: nenhum script gera token/secret embedido
49
+ - Observabilidade: cada invocação de sub-agent loga em `60-runs/`
50
+
51
+ ## 7. Riscos
52
+ | Risco | P | I | Mitigação |
53
+ |---|---|---|---|
54
+ | Hook UserPromptSubmit causa latência | M | M | Cache por hash do prompt + cap de bytes |
55
+ | Sub-agents disputam contexto | B | A | Roteamento explícito via handoff, sem broadcast |
56
+ | SDD vira burocracia | M | A | Lista clara em README de "quando NÃO precisa de spec" |
57
+
58
+ ## 8. Métricas de sucesso (30d)
59
+ - ≥80% das features novas atravessam o pipeline completo
60
+ - 0 PRs mergeados com `spec:check` falhando
61
+ - Tempo médio spec→tasks < 1 dia
@@ -0,0 +1,109 @@
1
+ # Plan: Predictive Change Simulation
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-01
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ `scripts/simulate.ts`, adapter puro de composição (mesmo padrão de `scripts/engineer.ts`) — nenhum
10
+ pacote novo em `packages/engineering`, porque não há lógica de domínio nova aqui, só orquestração
11
+ de engines já existentes (`SandboxEngine`, `checkConstitution`, `assessRisk`).
12
+
13
+ Ciclo do sandbox usado (D1): `create({sourceRef: ref})` → `prepare` → `execute(testCommand)` →
14
+ `reject` → `destroy`. **Não** usa `validate`/`diff`/`promote` do `SandboxEngine` — esses passos
15
+ existem pra "modifiquei o worktree, quero decidir se aplico as mudanças na árvore real"; aqui o
16
+ worktree já nasce checked out no `ref` (nada é modificado depois), e a árvore real nunca deveria
17
+ receber nada desta simulação. `reject()` aceita o estado `'validating'` (onde a sessão fica logo
18
+ após `execute()`) — não precisa passar por `validate()` pra chegar lá. Isso torna
19
+ "nunca promove" uma propriedade estrutural do código (a função `promote()` simplesmente nunca é
20
+ chamada em lugar nenhum deste arquivo), não uma disciplina que dependeria de lembrar de não chamar.
21
+
22
+ ## 2. Módulos afetados
23
+
24
+ | Caminho | Mudança | Risco |
25
+ |---|---|---|
26
+ | `scripts/simulate.ts` | novo — `forja simulate <ref>` | Médio — orquestra sandbox real + grafo temporário, mas cada peça já existe e testada |
27
+ | `lib/core/registry.ts` | 1 comando novo | Baixo |
28
+ | `test/simulate-cli.test.js` (novo) | fixture git isolada, verifica não-promoção e destruição do worktree | — |
29
+
30
+ ## 3. Diagrama de fluxo
31
+
32
+ ```text
33
+ forja simulate <ref> [--command "npm test"]
34
+ │
35
+ ├─► SandboxEngine.create({sourceRef: ref}) — GitWorktreeBackend, worktree isolado real
36
+ ├─► SandboxEngine.prepare
37
+ ├─► SandboxEngine.execute({command}) — roda o teste DENTRO do worktree
38
+ │ │
39
+ │ ▼ (sessão em 'validating')
40
+ ├─► SqliteMigrationRunner sobre um SQLite TEMPORÁRIO (mkdtemp, não getWorkspaceDbPath)
41
+ ├─► GraphIndexer.sync(GitGraphDocumentSource(session.root)) — indexa o worktree isolado
42
+ ├─► checkConstitution(constitution.json do worktree, arestas do grafo temporário)
43
+ ├─► buildRiskInput(changedFiles, database-temporário) + assessRisk
44
+ │
45
+ ├─► SandboxEngine.reject(session.id) — nunca promote()
46
+ └─► SandboxEngine.destroy(session.id) — sempre, mesmo em erro (try/finally)
47
+ │
48
+ ▼
49
+ SimulationReport { testResult, architectureCheck, risk, recommendation }
50
+ ```
51
+
52
+ ## 4. Contratos (CLI/Schema)
53
+
54
+ ```ts
55
+ // scripts/simulate.ts
56
+ interface SimulationReport {
57
+ readonly ref: string;
58
+ readonly changedFiles: readonly string[];
59
+ readonly testCommand: string;
60
+ readonly testResult: { readonly exitCode: number; readonly durationMs: number; readonly passed: boolean };
61
+ readonly architectureCheck: ArchitectureCheckReport | { readonly note: string };
62
+ readonly risk: ChangeRiskAssessment;
63
+ readonly recommendation: 'promote' | 'review' | 'discard';
64
+ }
65
+ ```
66
+
67
+ ```bash
68
+ simulate <ref> [--command "npm test"] [--json]
69
+ ```
70
+
71
+ ## 5. Decisões e alternativas
72
+
73
+ **D1**: ciclo `create→prepare→execute→reject→destroy`, sem `validate`/`diff`/`promote` — ver §1.
74
+ Alternativa considerada: usar o ciclo completo de `runSandboxedCapability` — rejeitada porque esse
75
+ helper foi desenhado pra capabilities que **modificam** o worktree via `work()` e depois decidem
76
+ promover; aqui o "trabalho" é só checkout+teste, sem modificação, e a promoção nunca deveria
77
+ acontecer — usar o ciclo completo introduziria um caminho de código (`promote`) que não deveria
78
+ nunca ser exercitado, risco desnecessário pro que AC-3 exige.
79
+
80
+ **D2**: `changedFiles` vem de `git diff --name-only HEAD <ref>` (reaproveita
81
+ `lib/core/risk-collect.ts.changedFiles`, mesma função de `risk:assess`/`forja engineer`) — rodado
82
+ **antes** de criar o sandbox, contra a árvore real (só leitura, `git diff` não modifica nada).
83
+
84
+ **D3**: grafo + banco da simulação são **completamente isolados** do workspace real — SQLite em
85
+ `fs.mkdtempSync`, apontando `FORJA_GRAPH_ROOT` pro `session.root` só durante a chamada de
86
+ `buildRiskInput`/`checkConstitution` (restaurado no `finally`, mesmo em exceção). Alternativa
87
+ rejeitada: reaproveitar `getWorkspaceDbPath()` — violaria AC-2/NFR explicitamente (contaminaria o
88
+ grafo persistente com o estado de um ref que pode nunca ser integrado).
89
+
90
+ **D4**: `recommendation` — `discard` se o teste falhar (hard gate); senão `review` se houver
91
+ violação de arquitetura `active` OU `risk.autonomyBand` for `supervised`/`human_in_the_loop`;
92
+ senão `promote`. Mesma filosofia de "informa, não decide" de `RiskEngine` (SPEC-034 D3) —
93
+ `forja simulate` nunca aplica a mudança sozinho independente da recomendação.
94
+
95
+ ## 6. Dependências
96
+
97
+ - SPEC-033 (`checkConstitution`), SPEC-034 (`assessRisk`/`buildRiskInput`, `lib/core/risk-collect.ts`)
98
+ — reaproveitados sem mudança.
99
+ - `packages/sandbox.SandboxEngine`/`packages/adapter-git.GitWorktreeBackend` — já existentes.
100
+
101
+ ## 7. Rollout
102
+
103
+ Sem migração, sem feature flag — comando novo, opt-in.
104
+
105
+ ## 8. Kill criteria
106
+
107
+ Se a recomendação não corresponder a julgamento humano sobre um ref real (§8 do spec), os pesos de
108
+ D4 são revisados antes de qualquer consumo automático futuro (fora de escopo desta spec de
109
+ qualquer forma, §5 "Fora").