forjajs 2.0.4 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (825) hide show
  1. package/.claude/agents/context-engineer.md +19 -25
  2. package/.claude/agents/governance.md +19 -55
  3. package/.claude/agents/marketing.md +19 -24
  4. package/.claude/agents/orchestrator.md +19 -31
  5. package/.claude/agents/product.md +19 -26
  6. package/.claude/agents/release-auditor.md +50 -50
  7. package/.claude/agents/sdd-architect.md +19 -34
  8. package/.claude/settings.json +76 -76
  9. package/.claude/skills/new-adr/SKILL.md +61 -61
  10. package/.claude/skills/new-command/SKILL.md +67 -67
  11. package/.gemini-instructions.md +93 -87
  12. package/.github/copilot-instructions.md +93 -87
  13. package/.memoryrc.json +104 -104
  14. package/.openai-instructions.md +93 -87
  15. package/AGENTS.md +137 -134
  16. package/CHANGELOG.md +656 -555
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +68 -60
  19. package/LICENSE +21 -21
  20. package/README.md +404 -343
  21. package/README.pt-BR.md +374 -345
  22. package/boilerplates/01-api-rest/README.md +336 -336
  23. package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
  24. package/boilerplates/02-saas-starter/.env.example +25 -25
  25. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
  26. package/boilerplates/02-saas-starter/INFO.md +252 -252
  27. package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
  28. package/boilerplates/02-saas-starter/README.md +305 -305
  29. package/boilerplates/02-saas-starter/START-HERE.md +259 -259
  30. package/boilerplates/02-saas-starter/backend/package.json +87 -87
  31. package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
  32. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
  33. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
  34. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
  35. package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
  36. package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
  37. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
  38. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
  39. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
  40. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
  41. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
  42. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
  43. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
  44. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
  45. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
  46. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
  47. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
  48. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
  49. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
  50. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
  51. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
  52. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
  53. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
  54. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
  55. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
  56. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
  57. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
  58. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
  59. package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
  60. package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
  61. package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
  62. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
  63. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
  64. package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
  65. package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
  66. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
  67. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
  68. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
  69. package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
  70. package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
  71. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
  72. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
  73. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
  74. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
  75. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
  76. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
  77. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
  78. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
  79. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
  80. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
  81. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
  82. package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
  83. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
  84. package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
  85. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
  86. package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
  87. package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
  88. package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
  89. package/boilerplates/03-ecommerce-starter/README.md +465 -465
  90. package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
  91. package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
  92. package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
  93. package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
  94. package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
  95. package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
  96. package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
  97. package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
  98. package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
  99. package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
  100. package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
  101. package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
  102. package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
  103. package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
  104. package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
  105. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
  106. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
  107. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
  108. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
  109. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
  110. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
  111. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
  112. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
  113. package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
  114. package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
  115. package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
  116. package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
  117. package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
  118. package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
  119. package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
  120. package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
  121. package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
  122. package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
  123. package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
  124. package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
  125. package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
  126. package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
  127. package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
  128. package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
  129. package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
  130. package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
  131. package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
  132. package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
  133. package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
  134. package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
  135. package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
  136. package/boilerplates/04-microservices-starter/.env.example +43 -43
  137. package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
  138. package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
  139. package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
  140. package/boilerplates/04-microservices-starter/INDEX.md +377 -377
  141. package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
  142. package/boilerplates/04-microservices-starter/README.md +466 -466
  143. package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
  144. package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
  145. package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
  146. package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
  147. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
  148. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
  149. package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
  150. package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
  151. package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
  152. package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
  153. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
  154. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
  155. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
  156. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
  157. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
  158. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
  159. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
  160. package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
  161. package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
  162. package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
  163. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
  164. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
  165. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
  166. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
  167. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
  168. package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
  169. package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
  170. package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
  171. package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
  172. package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
  173. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
  174. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
  175. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
  176. package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
  177. package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
  178. package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
  179. package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
  180. package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
  181. package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
  182. package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
  183. package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
  184. package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
  185. package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
  186. package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
  187. package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
  188. package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
  189. package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
  190. package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
  191. package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
  192. package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
  193. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
  194. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
  195. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
  196. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
  197. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
  198. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
  199. package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
  200. package/boilerplates/04-microservices-starter/package.json +21 -21
  201. package/boilerplates/05-monorepo-starter/.env.example +1 -1
  202. package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
  203. package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
  204. package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
  205. package/boilerplates/05-monorepo-starter/README.md +318 -318
  206. package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
  207. package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
  208. package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
  209. package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
  210. package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
  211. package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
  212. package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
  213. package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
  214. package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
  215. package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
  216. package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
  217. package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
  218. package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
  219. package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
  220. package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
  221. package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
  222. package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
  223. package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
  224. package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
  225. package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
  226. package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
  227. package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
  228. package/boilerplates/05-monorepo-starter/package.json +30 -30
  229. package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
  230. package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
  231. package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
  232. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
  233. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
  234. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
  235. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
  236. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
  237. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
  238. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
  239. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
  240. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
  241. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
  242. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
  243. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
  244. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
  245. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
  246. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
  247. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
  248. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
  249. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
  250. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
  251. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
  252. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
  253. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
  254. package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
  255. package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
  256. package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
  257. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
  258. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
  259. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
  260. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
  261. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
  262. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
  263. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
  264. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
  265. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
  266. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
  267. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
  268. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
  269. package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
  270. package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
  271. package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
  272. package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
  273. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
  274. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
  275. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
  276. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
  277. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
  278. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
  279. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
  280. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
  281. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
  282. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
  283. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
  284. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
  285. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
  286. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
  287. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
  288. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
  289. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
  290. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
  291. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
  292. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
  293. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
  294. package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
  295. package/boilerplates/05-monorepo-starter/turbo.json +35 -35
  296. package/boilerplates/06-clean-arch/README.md +48 -48
  297. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
  298. package/boilerplates/06-clean-arch/backend/package.json +43 -43
  299. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
  300. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
  301. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
  302. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
  303. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
  304. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
  305. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
  306. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
  307. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
  308. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
  309. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
  310. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
  311. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
  312. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
  313. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
  314. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
  315. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
  316. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
  317. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
  318. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
  319. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
  320. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
  321. package/boilerplates/README.md +427 -427
  322. package/design-md/BRIEF-TEMPLATE.md +47 -47
  323. package/design-md/INDEX.md +35 -35
  324. package/design-md/MATRIX.md +24 -24
  325. package/design-md/PLAYBOOK.md +35 -35
  326. package/design-md/examples/agent-console-brief.md +48 -48
  327. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  328. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  329. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  330. package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
  331. package/dist/apps/server/src/forja-nest.module.js +9 -4
  332. package/dist/apps/server/src/main.js +10 -1
  333. package/dist/bin/create-memory-nest-kit.js +17 -17
  334. package/dist/bin/init-project.js +38 -38
  335. package/dist/lib/audit.js +7 -7
  336. package/dist/lib/code-context.js +6 -0
  337. package/dist/lib/context-builder.js +32 -32
  338. package/dist/lib/core/architecture-gate.d.ts +20 -0
  339. package/dist/lib/core/architecture-gate.js +60 -0
  340. package/dist/lib/core/drift-gate.d.ts +18 -0
  341. package/dist/lib/core/drift-gate.js +55 -0
  342. package/dist/lib/core/gates.d.ts +9 -2
  343. package/dist/lib/core/gates.js +13 -2
  344. package/dist/lib/core/health.js +17 -1
  345. package/dist/lib/core/incident-search.d.ts +19 -0
  346. package/dist/lib/core/incident-search.js +32 -0
  347. package/dist/lib/core/model-pricing.d.ts +31 -0
  348. package/dist/lib/core/model-pricing.js +74 -0
  349. package/dist/lib/core/registry.d.ts +194 -0
  350. package/dist/lib/core/registry.js +194 -0
  351. package/dist/lib/core/release.d.ts +194 -0
  352. package/dist/lib/core/release.js +3 -0
  353. package/dist/lib/core/risk-collect.d.ts +19 -0
  354. package/dist/lib/core/risk-collect.js +173 -0
  355. package/dist/lib/drift-sentinel.d.ts +59 -0
  356. package/dist/lib/drift-sentinel.js +126 -0
  357. package/dist/lib/generators/memory-generator.js +691 -691
  358. package/dist/lib/generators/nest-generator.js +412 -398
  359. package/dist/lib/generators/readme-generator.js +180 -180
  360. package/dist/lib/governance-report.js +39 -39
  361. package/dist/lib/llm/codex-output.d.ts +12 -0
  362. package/dist/lib/llm/codex-output.js +56 -0
  363. package/dist/lib/llm/context.d.ts +5 -0
  364. package/dist/lib/llm/context.js +17 -0
  365. package/dist/lib/llm/session.d.ts +18 -0
  366. package/dist/lib/llm/session.js +34 -0
  367. package/dist/lib/llm/validation.d.ts +37 -0
  368. package/dist/lib/llm/validation.js +88 -0
  369. package/dist/lib/workspace.js +29 -29
  370. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  371. package/dist/packages/adapter-git/src/index.js +11 -6
  372. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  373. package/dist/packages/adapter-nest/src/index.js +26 -1
  374. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  375. package/dist/packages/adapter-sqlite/src/index.js +61 -12
  376. package/dist/packages/contracts/src/index.d.ts +33 -0
  377. package/dist/packages/contracts/src/index.js +13 -0
  378. package/dist/packages/core/src/index.d.ts +12 -0
  379. package/dist/packages/core/src/index.js +29 -0
  380. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  381. package/dist/packages/engineering/architecture/src/index.js +131 -0
  382. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  383. package/dist/packages/engineering/evidence/src/index.js +31 -0
  384. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  385. package/dist/packages/engineering/identity/src/index.js +88 -0
  386. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  387. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  388. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  389. package/dist/packages/engineering/provenance/src/index.js +21 -0
  390. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  391. package/dist/packages/engineering/risk/src/index.js +120 -0
  392. package/dist/packages/evals/src/index.js +6 -0
  393. package/dist/packages/graph/src/index.d.ts +23 -1
  394. package/dist/packages/graph/src/index.js +88 -15
  395. package/dist/packages/llm/src/index.d.ts +8 -1
  396. package/dist/packages/llm/src/index.js +64 -7
  397. package/dist/packages/mcp/src/index.js +27 -8
  398. package/dist/packages/orchestration/src/index.d.ts +11 -1
  399. package/dist/packages/orchestration/src/index.js +34 -7
  400. package/dist/packages/policy/src/index.d.ts +40 -0
  401. package/dist/packages/policy/src/index.js +39 -4
  402. package/dist/packages/runtime/src/index.js +3 -0
  403. package/dist/packages/sandbox/src/index.d.ts +47 -0
  404. package/dist/packages/sandbox/src/index.js +59 -0
  405. package/dist/packages/validator/src/index.d.ts +8 -0
  406. package/dist/packages/validator/src/index.js +21 -6
  407. package/dist/scripts/adr.d.ts +17 -0
  408. package/dist/scripts/adr.js +152 -0
  409. package/dist/scripts/agent-harness.js +72 -64
  410. package/dist/scripts/agent-router.js +20 -20
  411. package/dist/scripts/agent.d.ts +27 -0
  412. package/dist/scripts/agent.js +249 -0
  413. package/dist/scripts/architecture.d.ts +16 -0
  414. package/dist/scripts/architecture.js +186 -0
  415. package/dist/scripts/build-smart-context.js +22 -22
  416. package/dist/scripts/compress-memory.js +8 -8
  417. package/dist/scripts/context-ops.js +29 -29
  418. package/dist/scripts/cost-economy.d.ts +2 -0
  419. package/dist/scripts/cost-economy.js +79 -0
  420. package/dist/scripts/demo-autonomy.js +13 -6
  421. package/dist/scripts/dev.js +13 -13
  422. package/dist/scripts/drift-check.d.ts +17 -0
  423. package/dist/scripts/drift-check.js +63 -0
  424. package/dist/scripts/engineer.d.ts +20 -0
  425. package/dist/scripts/engineer.js +208 -0
  426. package/dist/scripts/evidence.d.ts +12 -0
  427. package/dist/scripts/evidence.js +55 -0
  428. package/dist/scripts/extract-global-knowledge.js +5 -5
  429. package/dist/scripts/gates.d.ts +6 -2
  430. package/dist/scripts/gates.js +14 -4
  431. package/dist/scripts/generate-dashboard.js +11 -11
  432. package/dist/scripts/incident.d.ts +19 -0
  433. package/dist/scripts/incident.js +103 -0
  434. package/dist/scripts/llm-fit.js +85 -9
  435. package/dist/scripts/memory-schema.js +48 -48
  436. package/dist/scripts/provenance.d.ts +14 -0
  437. package/dist/scripts/provenance.js +114 -0
  438. package/dist/scripts/query-universal-memory.js +13 -13
  439. package/dist/scripts/risk.d.ts +15 -0
  440. package/dist/scripts/risk.js +81 -0
  441. package/dist/scripts/simulate.d.ts +20 -0
  442. package/dist/scripts/simulate.js +150 -0
  443. package/dist/scripts/sprint-manager.js +39 -39
  444. package/dist/scripts/sync-universal-memory.js +44 -44
  445. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  446. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  447. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  448. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  449. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  450. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  451. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  452. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  453. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  454. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  455. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  456. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  457. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  458. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  459. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  460. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  461. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  462. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  463. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  464. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  465. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  466. package/docs/agent-harnesses.md +149 -149
  467. package/docs/agent-operating-contract.md +26 -0
  468. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  469. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  470. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  471. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  472. package/docs/archive/FASE2-SUMMARY.md +263 -263
  473. package/docs/archive/FASE3-PROGRESS.md +355 -355
  474. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  475. package/docs/archive/INDICE-MASTER.md +282 -282
  476. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  477. package/docs/archive/README-REFINAMENTO.md +293 -293
  478. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  479. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  480. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  481. package/docs/archive/START-HERE.md +319 -319
  482. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  483. package/docs/archive/examples/v1/AGENTS.md +10 -10
  484. package/docs/archive/examples/v1/README.md +36 -36
  485. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  486. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  487. package/docs/archive/examples/v1/backend/package.json +42 -42
  488. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  489. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  490. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  491. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  492. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  493. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  494. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  495. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  496. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  497. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  498. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  499. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  500. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  501. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  502. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  503. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  504. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  505. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  506. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  507. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  508. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  509. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  510. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  511. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  512. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  513. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  514. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  515. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  516. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  517. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  518. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  519. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  520. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  521. package/docs/archive/examples/v2/AGENTS.md +16 -16
  522. package/docs/archive/examples/v2/README.md +35 -35
  523. package/docs/archive/examples/v2/agents/README.md +3 -3
  524. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  525. package/docs/archive/examples/v2/agents/dba.md +4 -4
  526. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  527. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  528. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  529. package/docs/archive/examples/v2/agents/security.md +4 -4
  530. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  531. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  532. package/docs/archive/examples/v2/backend/package.json +42 -42
  533. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  534. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  535. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  536. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  537. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  538. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  539. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  540. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  541. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  542. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  543. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  544. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  545. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  546. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  547. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  548. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  549. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  550. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  551. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  552. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  553. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  554. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  555. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  556. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  557. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  558. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  559. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  560. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  561. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  562. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  563. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  564. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  565. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  566. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  567. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  568. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  569. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  570. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  571. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  572. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  573. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  574. package/docs/archive/examples/v2/memory/README.md +8 -8
  575. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  576. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  577. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  578. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  579. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  580. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  581. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  582. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  583. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  584. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  585. package/docs/capacidades-externas.md +86 -86
  586. package/docs/cli-first-operacao.md +74 -74
  587. package/docs/dev-workflow.md +421 -421
  588. package/docs/examples.md +546 -546
  589. package/docs/fluxo.md +103 -103
  590. package/docs/glossary.md +453 -453
  591. package/docs/init-project.md +457 -457
  592. package/docs/llm-evolution.md +51 -0
  593. package/docs/llm-fit-loop.md +134 -5
  594. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  595. package/docs/personas/architect/README.md +333 -333
  596. package/docs/personas/developer/README.md +371 -371
  597. package/docs/personas/executive/README.md +172 -172
  598. package/docs/personas/qa/README.md +350 -350
  599. package/docs/processo-projeto.md +138 -138
  600. package/docs/publishing.md +49 -377
  601. package/docs/quick-reference.md +409 -409
  602. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  603. package/docs/structure.md +360 -360
  604. package/docs/token-optimization.md +502 -502
  605. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  606. package/memory/00-global/mission.md +15 -15
  607. package/memory/00-global/shared-knowledge.md +8 -8
  608. package/memory/00-global/standards.md +47 -47
  609. package/memory/10-product/personas.md +21 -21
  610. package/memory/10-product/vision.md +27 -27
  611. package/memory/30-projects/README.md +15 -15
  612. package/memory/40-delivery/backlog.md +15 -15
  613. package/memory/40-delivery/current-sprint.md +20 -20
  614. package/memory/50-orchestration/gsd-harness.md +55 -55
  615. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  616. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  617. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  618. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  619. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  620. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  621. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  622. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  623. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  624. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  625. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  626. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  627. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  628. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  629. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  630. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  631. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  632. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  633. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  634. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  635. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  636. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  637. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  638. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  639. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  640. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  641. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  642. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  643. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  644. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  645. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  646. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  647. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  648. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  649. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  650. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  651. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  652. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  653. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  654. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  655. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  656. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  657. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  658. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  659. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  660. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  661. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  662. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  663. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  664. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  665. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  666. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  667. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  668. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  669. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  670. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  671. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  672. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  673. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  674. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  675. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  676. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  677. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  678. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  679. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  680. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  681. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  682. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  683. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  684. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  685. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  686. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  687. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  688. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  689. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  690. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  691. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  692. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  693. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  694. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  695. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  696. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  697. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  698. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  699. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  700. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  701. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  702. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  703. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  704. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  705. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  706. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  707. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  708. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  709. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  710. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  711. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  712. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  713. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  714. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  715. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  716. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  717. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  718. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  719. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  720. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  721. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  722. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  723. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  724. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  725. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  726. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  727. package/memory/90-decisions/0080-llm-execution-evidence.md +42 -0
  728. package/memory/90-decisions/0081-llm-resume-validation.md +42 -0
  729. package/memory/90-decisions/_template.md +28 -28
  730. package/package.json +159 -157
  731. package/prompts/context-engineer-agent.md +13 -19
  732. package/prompts/governance-agent.md +13 -16
  733. package/prompts/marketing-agent.md +13 -13
  734. package/prompts/orchestrator-agent.md +13 -18
  735. package/prompts/product-agent.md +13 -13
  736. package/prompts/sdd-architect-agent.md +13 -20
  737. package/skills/MANIFEST.json +10 -0
  738. package/skills/llm-provider-routing/SKILL.md +18 -0
  739. package/specs/README.md +70 -70
  740. package/specs/_templates/plan.md +50 -43
  741. package/specs/_templates/spec.md +50 -43
  742. package/specs/_templates/tasks.md +39 -32
  743. package/specs/agent-identity-reputation/plan.md +133 -0
  744. package/specs/agent-identity-reputation/spec.md +125 -0
  745. package/specs/agent-identity-reputation/tasks.md +51 -0
  746. package/specs/agent-instructions-v4/plan.md +8 -0
  747. package/specs/agent-instructions-v4/spec.md +21 -0
  748. package/specs/agent-instructions-v4/tasks.md +12 -0
  749. package/specs/agent-runtime-monitoring/plan.md +78 -0
  750. package/specs/agent-runtime-monitoring/spec.md +92 -0
  751. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  752. package/specs/ai-code-provenance/plan.md +71 -0
  753. package/specs/ai-code-provenance/spec.md +97 -0
  754. package/specs/ai-code-provenance/tasks.md +39 -0
  755. package/specs/architecture-constitution/plan.md +110 -0
  756. package/specs/architecture-constitution/spec.md +114 -0
  757. package/specs/architecture-constitution/tasks.md +58 -0
  758. package/specs/change-risk-engine/plan.md +130 -0
  759. package/specs/change-risk-engine/spec.md +119 -0
  760. package/specs/change-risk-engine/tasks.md +72 -0
  761. package/specs/clean-arch-boilerplate/plan.md +137 -137
  762. package/specs/clean-arch-boilerplate/spec.md +121 -121
  763. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  764. package/specs/cli-first-operacao/plan.md +53 -53
  765. package/specs/cli-first-operacao/spec.md +53 -53
  766. package/specs/cli-first-operacao/tasks.md +53 -53
  767. package/specs/code-context/spec.md +56 -56
  768. package/specs/coerencia-do-sistema/plan.md +155 -155
  769. package/specs/coerencia-do-sistema/spec.md +123 -123
  770. package/specs/coerencia-do-sistema/tasks.md +115 -115
  771. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  772. package/specs/dev-token-assets-db/plan.md +71 -71
  773. package/specs/dev-token-assets-db/spec.md +58 -58
  774. package/specs/dev-token-assets-db/tasks.md +58 -58
  775. package/specs/doctor-do-nucleo/plan.md +165 -165
  776. package/specs/doctor-do-nucleo/spec.md +139 -139
  777. package/specs/doctor-do-nucleo/tasks.md +172 -172
  778. package/specs/drift-sentinel/spec.md +117 -0
  779. package/specs/engineer-facade-extension/plan.md +71 -0
  780. package/specs/engineer-facade-extension/spec.md +98 -0
  781. package/specs/engineer-facade-extension/tasks.md +36 -0
  782. package/specs/engineering-evidence-ledger/plan.md +121 -0
  783. package/specs/engineering-evidence-ledger/spec.md +90 -0
  784. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  785. package/specs/engineering-graph-extensions/plan.md +92 -0
  786. package/specs/engineering-graph-extensions/spec.md +101 -0
  787. package/specs/engineering-graph-extensions/tasks.md +60 -0
  788. package/specs/engineering-intelligence/spec.md +177 -0
  789. package/specs/forja-core/spec.md +71 -71
  790. package/specs/gates/spec.md +63 -63
  791. package/specs/governanca-visivel/plan.md +122 -122
  792. package/specs/governanca-visivel/spec.md +112 -112
  793. package/specs/governanca-visivel/tasks.md +60 -60
  794. package/specs/harness-codegraph/spec.md +71 -71
  795. package/specs/learning-loop-incidents/plan.md +59 -0
  796. package/specs/learning-loop-incidents/spec.md +93 -0
  797. package/specs/learning-loop-incidents/tasks.md +36 -0
  798. package/specs/llm-integration-v2/plan.md +55 -0
  799. package/specs/llm-integration-v2/spec.md +61 -0
  800. package/specs/llm-integration-v2/tasks.md +28 -0
  801. package/specs/llm-resume-validation/plan.md +50 -0
  802. package/specs/llm-resume-validation/spec.md +35 -0
  803. package/specs/llm-resume-validation/tasks.md +19 -0
  804. package/specs/memory-audit/spec.md +54 -54
  805. package/specs/orchestrate/spec.md +108 -108
  806. package/specs/orchestration-coherent/spec.md +95 -95
  807. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  808. package/specs/predictive-change-simulation/plan.md +109 -0
  809. package/specs/predictive-change-simulation/spec.md +107 -0
  810. package/specs/predictive-change-simulation/tasks.md +41 -0
  811. package/specs/project-smoke/spec.md +96 -96
  812. package/specs/project-upgrade/spec.md +58 -58
  813. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  814. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  815. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  816. package/specs/release-auditor-health/spec.md +23 -23
  817. package/specs/release-gate/plan.md +174 -174
  818. package/specs/release-gate/spec.md +122 -122
  819. package/specs/release-gate/tasks.md +183 -183
  820. package/specs/smart-agent-routing/plan.md +55 -0
  821. package/specs/smart-agent-routing/spec.md +85 -0
  822. package/specs/smart-agent-routing/tasks.md +26 -0
  823. package/specs/ts-migration/plan.md +200 -200
  824. package/specs/ts-migration/spec.md +119 -119
  825. package/specs/ts-migration/tasks.md +110 -110
@@ -1,139 +1,139 @@
1
- # Spec: doctor-do-nucleo
2
-
3
- - **ID**: SPEC-009
4
- - **Status**: done
5
- - **Owner**: apk
6
- - **Criado em**: 2026-07-13
7
- - **Sprint alvo**: S?
8
- - **ADRs relacionadas**: [ADR-0018](../../memory/90-decisions/0018-ferramentas-de-processo.md) (tools:doctor), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails de harness), [ADR-0019](../../memory/90-decisions/0019-workspace-separado.md) (workspace), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
9
-
10
- ## 1. Problema
11
-
12
- O `tools:doctor` audita cinco ferramentas **externas e opcionais** e conclui com a própria
13
- ressalva: *"ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas."*
14
- Ele diagnostica exatamente aquilo que não é crítico, e é cego para tudo que é.
15
-
16
- Em 2026-07-13, com `better-sqlite3` compilado contra o ABI do Node 24 num runtime Node 26,
17
- a memória universal — a aposta nº 1 da visão, *"memória que sobrevive"* — estava **morta**:
18
- `query:universal`, `sync:universal`, `context:smart`, `agent:route`, `memory:compress` e
19
- `project:dashboard` todos inoperantes. O framework reagiu assim:
20
-
21
- | Superfície | O que fez | O que deveria ter feito |
22
- |---|---|---|
23
- | `tools:doctor` | Reportou `2/5 ferramentas disponíveis`, tudo aparentemente normal | Falhar apontando o ABI quebrado |
24
- | `SessionStart` | Detectou, mas prescreveu `npm install` + `sync:universal` | Prescrever `npm rebuild better-sqlite3` |
25
- | `npm test` | Stack trace de `ERR_DLOPEN_FAILED` | — (aceitável, mas sem orientação) |
26
-
27
- A prescrição errada é o pior dos três. `npm install` **não** recompila binário nativo quando o
28
- lock já bate; quem seguisse a instrução do próprio framework não consertaria nada e concluiria
29
- que o problema era outro.
30
-
31
- Esta é a **quinta ocorrência** da classe de falha que o ADR-0021 nomeia — *"erram sem avisar…
32
- produzem trabalho errado com aparência de trabalho certo"*. As quatro anteriores receberam
33
- correções pontuais. Falta o gate genérico: **nada valida o núcleo do framework**, e dois dos
34
- quatro casos já corrigidos (`.mcp.json` com path absoluto; `better-sqlite3` fora de
35
- `dependencies`) podem reincidir sem que nenhum teste ou gate perceba.
36
-
37
- ## 2. Proposta de valor
38
-
39
- Uma única fonte de verdade sobre a saúde do núcleo, consumida por todas as superfícies de
40
- diagnóstico: **toda quebra do núcleo é detectada na primeira vez que o operador toca o
41
- framework, com o comando de correção correto ao lado.**
42
-
43
- ## 3. User stories
44
-
45
- - **Como** operador, **quero** que `tools:doctor` falhe quando o núcleo está quebrado,
46
- **para que** eu não descubra por um stack trace de `dlopen` trinta minutos depois.
47
- - **Como** operador que trocou de versão do Node, **quero** a prescrição certa
48
- (`npm rebuild better-sqlite3`), **para que** eu não perca tempo seguindo um conselho errado
49
- do próprio framework.
50
- - **Como** agente iniciando sessão, **quero** saber que a memória está defasada ou morta antes
51
- de confiar num `query:universal`, **para que** eu não construa raciocínio sobre contexto vazio.
52
- - **Como** governança, **quero** um gate que reprove um release em que os invariantes do
53
- ADR-0021 regrediram, **para que** as correções pontuais não se percam com o tempo.
54
- - **Como** autor de uma spec do framework, **quero** que ela seja versionada por padrão,
55
- **para que** eu não a perca sem aviso — hoje o `.gitignore` a descarta calado.
56
-
57
- ## 4. Critérios de aceite (Definition of Done)
58
-
59
- - [x] AC-1: Existe `lib/core/health.mjs` exportando os checks de núcleo como dados
60
- (`{ id, severity, probe, fix }`), sem I/O de apresentação.
61
- - [x] AC-2: `tools:doctor` reporta **duas seções** — Núcleo e Ferramentas — e sai com código
62
- **≠ 0** se e somente se algum check `critical` do núcleo falhar. Ausência de ferramenta
63
- opcional continua sendo `exit 0` (contrato do ADR-0018 preservado).
64
- - [x] AC-3: Check de **ABI nativa**: com `better-sqlite3` compilado para outro `NODE_MODULE_VERSION`,
65
- o doctor falha com a mensagem apontando `npm rebuild better-sqlite3`. Testável simulando
66
- o `ERR_DLOPEN_FAILED`.
67
- - [x] AC-4: Check de **memória**: distingue os três estados — banco ausente, banco inacessível,
68
- banco defasado (`memory/` alterado depois do último sync) — cada um com sua correção.
69
- - [x] AC-5: Check de **workspace**: `lib/workspace.mjs` resolve para diretório existente; se não,
70
- prescreve `npm run workspace:init`.
71
- - [x] AC-6: Check de **deps de runtime** (regressão do ADR-0021 §2): todo módulo importado
72
- estaticamente por scripts sob `files[]` está em `dependencies`, não em `devDependencies`.
73
- - [x] AC-7: Check de **`.mcp.json`** (regressão do ADR-0021 §1): nenhum path absoluto versionado.
74
- - [x] AC-8: O hook `SessionStart` consome `lib/core/health.mjs` — **zero heurística própria** — e
75
- a prescrição errada atual (`npm install`) deixa de existir no código.
76
- - [x] AC-9: Testes cobrindo cada check nos dois estados (são e quebrado), com a suíte verde.
77
- - [x] AC-10: ADR registrando a decisão (doctor como gate do núcleo vs. relatório de ferramentas).
78
- - [x] AC-11: `spec:new` **mantém a allow-list do `.gitignore` sozinho** ao criar uma spec do
79
- framework. Criar uma spec e rodar `git status` passa a mostrá-la, sem passo manual.
80
- *(Emenda de 2026-07-13 — ver §5.)*
81
-
82
- ## 5. Escopo
83
-
84
- **Dentro**:
85
- - `lib/core/health.mjs` — os checks como dados, reutilizáveis.
86
- - `scripts/tools-doctor.mjs` — passa a consumir a lib; ganha seção de núcleo e exit code.
87
- - `scripts/hook-session-start.mjs` (ou equivalente) — passa a consumir a lib.
88
- - Os sete checks: ABI nativa, banco presente, banco fresco, workspace resolvido, deps de runtime,
89
- `.mcp.json` limpo, Node vs. `engines`.
90
- - `scripts/spec-cli.mjs` — allow-list do `.gitignore` mantida pelo harness (AC-11).
91
- - ADR + testes.
92
-
93
- > **Emenda (2026-07-13).** Ao escrever o plano, descobrimos que o `.gitignore` ignora `/specs/*` e
94
- > mantém uma allow-list manual: **toda spec nova do framework nasce invisível ao git**. O `spec:new`
95
- > cria, o `spec:check` aprova, e o git descarta calado — aconteceu com esta própria spec. É a mesma
96
- > classe de falha do ADR-0021, dentro da ferramenta que estamos consertando.
97
- >
98
- > Rejeitamos resolver isso com um *check* no doctor (`spec-allowlist` → warn): trocaria uma falha
99
- > silenciosa por um lembrete recorrente que se aprende a ignorar. Seguimos o próprio ADR-0021 —
100
- > *"mover a aplicação das regras do texto para o harness"* — e fazemos o `spec:new` manter a lista.
101
- > A classe de erro deixa de existir em vez de ser reportada.
102
-
103
- **Fora** (explícito, evita scope creep):
104
- - **Autocorreção.** O doctor diagnostica e prescreve; não executa `npm rebuild` sozinho.
105
- Rodar comandos de build sem consentimento é a classe de risco oposta.
106
- - Novos gates de qualidade de código (lint, cobertura) — não é sobre isso.
107
- - Alterar o conjunto das cinco ferramentas opcionais do ADR-0018.
108
- - Reindexação automática da memória (`sync:universal` permanece explícito).
109
-
110
- ## 6. NFRs / restrições
111
-
112
- - **Performance**: o doctor completo roda em < 2s. O `SessionStart` não pode ficar perceptivelmente
113
- mais lento — os checks caros (deps, `.mcp.json`) só entram no doctor, não no hook.
114
- - **Resiliência**: todo acesso a SQLite permanece *lazy* (ADR-0021). O doctor precisa funcionar
115
- **sem `node_modules`** — é justamente aí que ele mais importa. Um check que estoura ao
116
- diagnosticar é pior que check nenhum.
117
- - **Contrato**: `exit 0` continua significando "posso trabalhar". Ferramenta opcional ausente
118
- nunca trava; núcleo quebrado sempre trava.
119
- - **Compatibilidade**: o comando `tools:doctor` mantém nome, entrada no registry (ADR-0020) e
120
- saída legível.
121
-
122
- ## 7. Riscos e mitigação
123
-
124
- | Risco | Probabilidade | Impacto | Mitigação |
125
- |---|---|---|---|
126
- | Doctor vira gate ruidoso e o operador aprende a ignorá-lo | M | A | Só `critical` trava. Warning (índice defasado) informa sem falhar |
127
- | Check de deps de runtime dá falso positivo (import dinâmico, opcional) | M | M | Parser estático conservador: na dúvida, warning e não erro |
128
- | Detecção de ABI depende de string de erro do Node | M | M | Casar por `err.code === 'ERR_DLOPEN_FAILED'`, não por mensagem |
129
- | Doctor duplica o que o `release-auditor` já faz | B | B | Agente simula tarball (pré-publicação); doctor valida o repo vivo. `release-auditor` pode passar a consumir a mesma lib |
130
- | Escopo escorrega para "doctor conserta tudo" | M | A | Autocorreção está explicitamente fora |
131
-
132
- ## 8. Métricas de sucesso
133
-
134
- - **Zero** falhas silenciosas da classe ADR-0021 nos 30 dias após o release: toda quebra do núcleo
135
- aparece no primeiro comando executado, não num sintoma indireto.
136
- - Tempo entre quebrar o ambiente (ex.: trocar a major do Node) e ter o diagnóstico correto em mãos:
137
- de *indefinido* (hoje o operador é ativamente mal orientado) para **um comando**.
138
- - Os quatro invariantes já corrigidos pelo ADR-0021 passam a ter cobertura executável — regressão
139
- em qualquer um deles reprova o gate em vez de reaparecer em produção.
1
+ # Spec: doctor-do-nucleo
2
+
3
+ - **ID**: SPEC-009
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-13
7
+ - **Sprint alvo**: S?
8
+ - **ADRs relacionadas**: [ADR-0018](../../memory/90-decisions/0018-ferramentas-de-processo.md) (tools:doctor), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails de harness), [ADR-0019](../../memory/90-decisions/0019-workspace-separado.md) (workspace), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
9
+
10
+ ## 1. Problema
11
+
12
+ O `tools:doctor` audita cinco ferramentas **externas e opcionais** e conclui com a própria
13
+ ressalva: *"ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas."*
14
+ Ele diagnostica exatamente aquilo que não é crítico, e é cego para tudo que é.
15
+
16
+ Em 2026-07-13, com `better-sqlite3` compilado contra o ABI do Node 24 num runtime Node 26,
17
+ a memória universal — a aposta nº 1 da visão, *"memória que sobrevive"* — estava **morta**:
18
+ `query:universal`, `sync:universal`, `context:smart`, `agent:route`, `memory:compress` e
19
+ `project:dashboard` todos inoperantes. O framework reagiu assim:
20
+
21
+ | Superfície | O que fez | O que deveria ter feito |
22
+ |---|---|---|
23
+ | `tools:doctor` | Reportou `2/5 ferramentas disponíveis`, tudo aparentemente normal | Falhar apontando o ABI quebrado |
24
+ | `SessionStart` | Detectou, mas prescreveu `npm install` + `sync:universal` | Prescrever `npm rebuild better-sqlite3` |
25
+ | `npm test` | Stack trace de `ERR_DLOPEN_FAILED` | — (aceitável, mas sem orientação) |
26
+
27
+ A prescrição errada é o pior dos três. `npm install` **não** recompila binário nativo quando o
28
+ lock já bate; quem seguisse a instrução do próprio framework não consertaria nada e concluiria
29
+ que o problema era outro.
30
+
31
+ Esta é a **quinta ocorrência** da classe de falha que o ADR-0021 nomeia — *"erram sem avisar…
32
+ produzem trabalho errado com aparência de trabalho certo"*. As quatro anteriores receberam
33
+ correções pontuais. Falta o gate genérico: **nada valida o núcleo do framework**, e dois dos
34
+ quatro casos já corrigidos (`.mcp.json` com path absoluto; `better-sqlite3` fora de
35
+ `dependencies`) podem reincidir sem que nenhum teste ou gate perceba.
36
+
37
+ ## 2. Proposta de valor
38
+
39
+ Uma única fonte de verdade sobre a saúde do núcleo, consumida por todas as superfícies de
40
+ diagnóstico: **toda quebra do núcleo é detectada na primeira vez que o operador toca o
41
+ framework, com o comando de correção correto ao lado.**
42
+
43
+ ## 3. User stories
44
+
45
+ - **Como** operador, **quero** que `tools:doctor` falhe quando o núcleo está quebrado,
46
+ **para que** eu não descubra por um stack trace de `dlopen` trinta minutos depois.
47
+ - **Como** operador que trocou de versão do Node, **quero** a prescrição certa
48
+ (`npm rebuild better-sqlite3`), **para que** eu não perca tempo seguindo um conselho errado
49
+ do próprio framework.
50
+ - **Como** agente iniciando sessão, **quero** saber que a memória está defasada ou morta antes
51
+ de confiar num `query:universal`, **para que** eu não construa raciocínio sobre contexto vazio.
52
+ - **Como** governança, **quero** um gate que reprove um release em que os invariantes do
53
+ ADR-0021 regrediram, **para que** as correções pontuais não se percam com o tempo.
54
+ - **Como** autor de uma spec do framework, **quero** que ela seja versionada por padrão,
55
+ **para que** eu não a perca sem aviso — hoje o `.gitignore` a descarta calado.
56
+
57
+ ## 4. Critérios de aceite (Definition of Done)
58
+
59
+ - [x] AC-1: Existe `lib/core/health.mjs` exportando os checks de núcleo como dados
60
+ (`{ id, severity, probe, fix }`), sem I/O de apresentação.
61
+ - [x] AC-2: `tools:doctor` reporta **duas seções** — Núcleo e Ferramentas — e sai com código
62
+ **≠ 0** se e somente se algum check `critical` do núcleo falhar. Ausência de ferramenta
63
+ opcional continua sendo `exit 0` (contrato do ADR-0018 preservado).
64
+ - [x] AC-3: Check de **ABI nativa**: com `better-sqlite3` compilado para outro `NODE_MODULE_VERSION`,
65
+ o doctor falha com a mensagem apontando `npm rebuild better-sqlite3`. Testável simulando
66
+ o `ERR_DLOPEN_FAILED`.
67
+ - [x] AC-4: Check de **memória**: distingue os três estados — banco ausente, banco inacessível,
68
+ banco defasado (`memory/` alterado depois do último sync) — cada um com sua correção.
69
+ - [x] AC-5: Check de **workspace**: `lib/workspace.mjs` resolve para diretório existente; se não,
70
+ prescreve `npm run workspace:init`.
71
+ - [x] AC-6: Check de **deps de runtime** (regressão do ADR-0021 §2): todo módulo importado
72
+ estaticamente por scripts sob `files[]` está em `dependencies`, não em `devDependencies`.
73
+ - [x] AC-7: Check de **`.mcp.json`** (regressão do ADR-0021 §1): nenhum path absoluto versionado.
74
+ - [x] AC-8: O hook `SessionStart` consome `lib/core/health.mjs` — **zero heurística própria** — e
75
+ a prescrição errada atual (`npm install`) deixa de existir no código.
76
+ - [x] AC-9: Testes cobrindo cada check nos dois estados (são e quebrado), com a suíte verde.
77
+ - [x] AC-10: ADR registrando a decisão (doctor como gate do núcleo vs. relatório de ferramentas).
78
+ - [x] AC-11: `spec:new` **mantém a allow-list do `.gitignore` sozinho** ao criar uma spec do
79
+ framework. Criar uma spec e rodar `git status` passa a mostrá-la, sem passo manual.
80
+ *(Emenda de 2026-07-13 — ver §5.)*
81
+
82
+ ## 5. Escopo
83
+
84
+ **Dentro**:
85
+ - `lib/core/health.mjs` — os checks como dados, reutilizáveis.
86
+ - `scripts/tools-doctor.mjs` — passa a consumir a lib; ganha seção de núcleo e exit code.
87
+ - `scripts/hook-session-start.mjs` (ou equivalente) — passa a consumir a lib.
88
+ - Os sete checks: ABI nativa, banco presente, banco fresco, workspace resolvido, deps de runtime,
89
+ `.mcp.json` limpo, Node vs. `engines`.
90
+ - `scripts/spec-cli.mjs` — allow-list do `.gitignore` mantida pelo harness (AC-11).
91
+ - ADR + testes.
92
+
93
+ > **Emenda (2026-07-13).** Ao escrever o plano, descobrimos que o `.gitignore` ignora `/specs/*` e
94
+ > mantém uma allow-list manual: **toda spec nova do framework nasce invisível ao git**. O `spec:new`
95
+ > cria, o `spec:check` aprova, e o git descarta calado — aconteceu com esta própria spec. É a mesma
96
+ > classe de falha do ADR-0021, dentro da ferramenta que estamos consertando.
97
+ >
98
+ > Rejeitamos resolver isso com um *check* no doctor (`spec-allowlist` → warn): trocaria uma falha
99
+ > silenciosa por um lembrete recorrente que se aprende a ignorar. Seguimos o próprio ADR-0021 —
100
+ > *"mover a aplicação das regras do texto para o harness"* — e fazemos o `spec:new` manter a lista.
101
+ > A classe de erro deixa de existir em vez de ser reportada.
102
+
103
+ **Fora** (explícito, evita scope creep):
104
+ - **Autocorreção.** O doctor diagnostica e prescreve; não executa `npm rebuild` sozinho.
105
+ Rodar comandos de build sem consentimento é a classe de risco oposta.
106
+ - Novos gates de qualidade de código (lint, cobertura) — não é sobre isso.
107
+ - Alterar o conjunto das cinco ferramentas opcionais do ADR-0018.
108
+ - Reindexação automática da memória (`sync:universal` permanece explícito).
109
+
110
+ ## 6. NFRs / restrições
111
+
112
+ - **Performance**: o doctor completo roda em < 2s. O `SessionStart` não pode ficar perceptivelmente
113
+ mais lento — os checks caros (deps, `.mcp.json`) só entram no doctor, não no hook.
114
+ - **Resiliência**: todo acesso a SQLite permanece *lazy* (ADR-0021). O doctor precisa funcionar
115
+ **sem `node_modules`** — é justamente aí que ele mais importa. Um check que estoura ao
116
+ diagnosticar é pior que check nenhum.
117
+ - **Contrato**: `exit 0` continua significando "posso trabalhar". Ferramenta opcional ausente
118
+ nunca trava; núcleo quebrado sempre trava.
119
+ - **Compatibilidade**: o comando `tools:doctor` mantém nome, entrada no registry (ADR-0020) e
120
+ saída legível.
121
+
122
+ ## 7. Riscos e mitigação
123
+
124
+ | Risco | Probabilidade | Impacto | Mitigação |
125
+ |---|---|---|---|
126
+ | Doctor vira gate ruidoso e o operador aprende a ignorá-lo | M | A | Só `critical` trava. Warning (índice defasado) informa sem falhar |
127
+ | Check de deps de runtime dá falso positivo (import dinâmico, opcional) | M | M | Parser estático conservador: na dúvida, warning e não erro |
128
+ | Detecção de ABI depende de string de erro do Node | M | M | Casar por `err.code === 'ERR_DLOPEN_FAILED'`, não por mensagem |
129
+ | Doctor duplica o que o `release-auditor` já faz | B | B | Agente simula tarball (pré-publicação); doctor valida o repo vivo. `release-auditor` pode passar a consumir a mesma lib |
130
+ | Escopo escorrega para "doctor conserta tudo" | M | A | Autocorreção está explicitamente fora |
131
+
132
+ ## 8. Métricas de sucesso
133
+
134
+ - **Zero** falhas silenciosas da classe ADR-0021 nos 30 dias após o release: toda quebra do núcleo
135
+ aparece no primeiro comando executado, não num sintoma indireto.
136
+ - Tempo entre quebrar o ambiente (ex.: trocar a major do Node) e ter o diagnóstico correto em mãos:
137
+ de *indefinido* (hoje o operador é ativamente mal orientado) para **um comando**.
138
+ - Os quatro invariantes já corrigidos pelo ADR-0021 passam a ter cobertura executável — regressão
139
+ em qualquer um deles reprova o gate em vez de reaparecer em produção.
@@ -1,172 +1,172 @@
1
- # Tasks: doctor-do-nucleo
2
-
3
- - **Spec**: ./spec.md
4
- - **Plan**: ./plan.md
5
- - **Status**: done
6
- - **Criado em**: 2026-07-13
7
-
8
- > Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
9
-
10
- Convenção de IDs: `T1`, `T2`, … A sequência reflete a **ordem de merge do plano §7**: a lib e os
11
- testes primeiro (nada a consome ainda), depois as superfícies, e o hook por último — é o de maior
12
- risco e o único que roda em toda sessão.
13
-
14
- ---
15
-
16
- ## T1 — Runner e contrato de `lib/core/health.mjs`
17
- - **Owner**: Worker
18
- - **Estimativa**: M
19
- - **Depende de**: —
20
- - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
21
- - **Escopo**: o esqueleto sem nenhum probe real — `CHECKS[]` vazio ou com um probe de fixture.
22
- - **Done quando**:
23
- - [x] `runChecks({ scope, env })` e `worstStatus(results)` exportados conforme plano §4 (AC-1)
24
- - [x] Cascata: check com `dependsOn` que falhou é reportado `skipped`, nunca `fail`
25
- - [x] Runner blinda o probe: probe que **lança** vira `fail` com o erro no `detail`, e o runner
26
- continua os demais — nunca propaga exceção (NFR de resiliência)
27
- - [x] `worstStatus` só devolve `fail` para `critical`; `warn` nunca escala
28
- - [x] `env` injetável (`{ root, importModule, fs, workspace }`) com default real (D5)
29
- - [x] `test/health.test.js` cobre cascata, blindagem e `worstStatus` com probes de fixture
30
- - [x] Zero dependências novas (plano §6)
31
-
32
- ## T2 — Probes de memória: `native-abi`, `memory-db`, `memory-fresh`
33
- - **Owner**: Worker
34
- - **Estimativa**: M
35
- - **Depende de**: T1
36
- - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
37
- - **Escopo**: os três checks que teriam pego a quebra de hoje. É o núcleo do núcleo.
38
- - **Done quando**:
39
- - [x] `native-abi` (critical) classifica por `err.code`, **não** por string de mensagem (risco da
40
- spec): `ERR_DLOPEN_FAILED` → `npm rebuild better-sqlite3`; `ERR_MODULE_NOT_FOUND` →
41
- `npm install` (AC-3)
42
- - [x] `memory-db` (critical, `dependsOn: native-abi`) distingue **ausente** de **inacessível**,
43
- cada um com sua correção (AC-4)
44
- - [x] `memory-fresh` (**warn**, `dependsOn: memory-db`): `memory/` alterado depois do último sync
45
- → `npm run sync:universal`. Reaproveita a lógica de `newestMemoryMtime` que hoje vive no
46
- hook (AC-4)
47
- - [x] Teste do ABI quebrado injeta `env.importModule` que lança `ERR_DLOPEN_FAILED` — sem mock de
48
- módulo, sem corromper `node_modules` (D5)
49
- - [x] Cada probe testado nos dois estados: são e quebrado (AC-9)
50
-
51
- ## T3 — Probes de ambiente: `workspace`, `node-engines`
52
- - **Owner**: Worker
53
- - **Estimativa**: P
54
- - **Depende de**: T1
55
- - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
56
- - **Done quando**:
57
- - [x] `workspace` (**warn**, D4) usa `getWorkspaceInfo()` de `lib/workspace.mjs`; se não resolve
58
- para diretório existente → `npm run workspace:init`. Reporta também a **origem** da
59
- resolução (`FORJA_WORKSPACE` / `~/.forjarc.json` / default), que é metade do diagnóstico
60
- quando o workspace certo existe mas não é o que está sendo usado (AC-5)
61
- - [x] `node-engines` (**warn**) compara `process.versions.node` com `engines.node` do
62
- `package.json`
63
- - [x] Ambos testados nos dois estados via `env.fs` / `env.workspace` injetados
64
-
65
- ## T4 — Probes de regressão do repo: `runtime-deps`, `mcp-json`
66
- - **Owner**: Worker
67
- - **Estimativa**: M
68
- - **Depende de**: T1
69
- - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
70
- - **Escopo**: converte em gate executável os dois invariantes que o ADR-0021 corrigiu à mão e que
71
- hoje podem reincidir sem que nada perceba.
72
- - **Done quando**:
73
- - [x] Ambos com `scope: 'repo'` — **não** rodam fora do repo do framework, onde produziriam falso
74
- positivo crítico na máquina do usuário final (D3). Detecção: `.git` + `package.json` com
75
- `name: forjajs`
76
- - [x] `runtime-deps` (critical): todo módulo importado **estaticamente** por script sob `files[]`
77
- está em `dependencies`, não em `devDependencies` (AC-6). Parser **conservador**: import
78
- dinâmico ou não resolvido → `warn`, nunca `fail` (risco da spec)
79
- - [x] `mcp-json` (critical): nenhum path absoluto versionado em `.mcp.json` (AC-7)
80
- - [x] Teste com fixture de `package.json`/`.mcp.json` quebrados, via `env.fs` e `env.root`
81
- - [x] Teste garantindo que ambos são `skipped` quando `scope: 'runtime'`
82
-
83
- ## T5 — `tools:doctor` consome a lib e vira gate
84
- - **Owner**: Worker
85
- - **Estimativa**: M
86
- - **Depende de**: T2, T3, T4
87
- - **Paths**: `scripts/tools-doctor.mjs`
88
- - **Done quando**:
89
- - [x] Duas seções na saída: **Núcleo** e **Ferramentas** (AC-2)
90
- - [x] `exit 1` **se e somente se** algum check `critical` do núcleo falhar. Ferramenta opcional
91
- ausente segue `exit 0` — contrato do ADR-0018 preservado (AC-2, D4)
92
- - [x] `TOOLS[]` das cinco ferramentas opcionais permanece intocado (spec §5, fora de escopo)
93
- - [x] Cada falha imprime o comando de correção ao lado
94
- - [x] Roda em < 2s (NFR)
95
- - [x] Funciona **sem `node_modules`** — é justamente aí que ele mais importa (NFR)
96
-
97
- ## T6 — `SessionStart` consome a lib e perde a heurística própria
98
- - **Owner**: Worker
99
- - **Estimativa**: M
100
- - **Depende de**: T2, T3
101
- - **Paths**: `scripts/hook-session-start.mjs`
102
- - **Escopo**: a task de maior risco. O hook roda em toda sessão e o ADR-0021 o marcou como "nunca
103
- pode derrubar a sessão".
104
- - **Done quando**:
105
- - [x] `resolveDbPath()` e `staleIndex()` **deixam de existir** — o `catch { return null }` que
106
- colapsa três causas distintas é a raiz do problema (plano §1)
107
- - [x] A prescrição errada (`npm install` para ABI quebrado, linha 91) não existe mais no código
108
- (AC-8)
109
- - [x] Chama `runChecks({ scope: 'runtime' })` — zero heurística própria (AC-8)
110
- - [x] **Sempre `exit 0`**: o hook reporta, nunca trava a sessão (ADR-0021)
111
- - [x] Cabe com folga no timeout de 5s; se não couber, ver kill criteria do plano §8
112
- - [x] `test/hooks.test.js` estendido: sem `node_modules` o hook degrada, não estoura
113
-
114
- ## T7 — ADR-0023
115
- - **Owner**: SDD Architect
116
- - **Estimativa**: P
117
- - **Depende de**: T5, T6
118
- - **Paths**: `memory/90-decisions/0023-doctor-como-gate-do-nucleo.md`
119
- - **Done quando**:
120
- - [x] Registra D1 (checks como dados), D3 (`scope` repo/runtime) e a mudança de contrato do exit
121
- code (AC-10)
122
- - [x] Referencia ADR-0018 (que estende) e ADR-0021 (a classe de falha que fecha)
123
- - [x] Segue `memory/90-decisions/_template.md`
124
-
125
- ## T8 — Registry e documentação
126
- - **Owner**: Worker
127
- - **Estimativa**: P
128
- - **Depende de**: T5
129
- - **Paths**: `lib/core/registry.mjs`, `CLAUDE.md`, `docs/`
130
- - **Done quando**:
131
- - [x] `desc` do `tools:doctor` no registry reflete o novo papel (deixa de ser só "ferramentas de
132
- processo")
133
- - [x] `CLAUDE.md` e `docs/` onde o comando é descrito como "raio-x de ferramentas"
134
- - [x] `npm test` verde, incluindo `test/forja-core.test.js` (integridade do registry, ADR-0020)
135
-
136
- ## T9 — Validação no cenário real
137
- - **Owner**: Governance
138
- - **Estimativa**: P
139
- - **Depende de**: T5, T6, T7, T8
140
- - **Paths**: —
141
- - **Done quando**:
142
- - [x] `tools:doctor` roda sob um Node de **major diferente** e reporta o ABI quebrado com a
143
- prescrição certa. Um doctor de ABI que nunca viu um ABI quebrado não está testado, está
144
- escrito (plano §7)
145
- - [x] `npm run project:check` e `npm test` verdes
146
- - [x] `gitleaks detect --no-banner` limpo
147
- - [x] Suíte completa verde (AC-9); spec → `done`
148
-
149
- ## T10 — `spec:new` mantém a allow-list do `.gitignore`
150
- - **Owner**: Worker
151
- - **Estimativa**: P
152
- - **Depende de**: — *(independente da lib; pode ir primeiro)*
153
- - **Paths**: `scripts/spec-cli.mjs`, `test/spec-cli.test.js`
154
- - **Contexto**: descoberto ao escrever o plano. O `.gitignore` ignora `/specs/*` e mantém uma
155
- allow-list manual; **toda spec nova do framework nasce invisível ao git**. Aconteceu com esta
156
- própria spec. Emenda de 2026-07-13 à spec (AC-11).
157
- - **Done quando**:
158
- - [x] `spec:new <slug>` acrescenta `!/specs/<slug>` ao bloco de allow-list do `.gitignore`
159
- - [x] **Idempotente**: rodar duas vezes não duplica a linha
160
- - [x] Insere **dentro do bloco existente** (após a última `!/specs/…`), não no fim do arquivo —
161
- as regras seguintes do `.gitignore` dependem da ordem
162
- - [x] Se o bloco não existir (ou o `.gitignore` sumir), **não falha** a criação da spec: avisa e
163
- segue. Criar spec é o trabalho; manter o gitignore é o efeito colateral
164
- - [x] Teste: cria spec num `.gitignore` de fixture e verifica a linha, a idempotência e a posição
165
- - [x] `git status` mostra a spec recém-criada, sem passo manual (AC-11)
166
-
167
- ---
168
-
169
- ## Handoffs entre agentes
170
-
171
- Este conjunto atravessa Worker (T1-T6, T8, T10), SDD Architect (T7) e Governance (T9). Registrar
172
- handoff a cada fronteira via `npm run agent:route` — 7 campos obrigatórios (ADR-0005).
1
+ # Tasks: doctor-do-nucleo
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: done
6
+ - **Criado em**: 2026-07-13
7
+
8
+ > Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
9
+
10
+ Convenção de IDs: `T1`, `T2`, … A sequência reflete a **ordem de merge do plano §7**: a lib e os
11
+ testes primeiro (nada a consome ainda), depois as superfícies, e o hook por último — é o de maior
12
+ risco e o único que roda em toda sessão.
13
+
14
+ ---
15
+
16
+ ## T1 — Runner e contrato de `lib/core/health.mjs`
17
+ - **Owner**: Worker
18
+ - **Estimativa**: M
19
+ - **Depende de**: —
20
+ - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
21
+ - **Escopo**: o esqueleto sem nenhum probe real — `CHECKS[]` vazio ou com um probe de fixture.
22
+ - **Done quando**:
23
+ - [x] `runChecks({ scope, env })` e `worstStatus(results)` exportados conforme plano §4 (AC-1)
24
+ - [x] Cascata: check com `dependsOn` que falhou é reportado `skipped`, nunca `fail`
25
+ - [x] Runner blinda o probe: probe que **lança** vira `fail` com o erro no `detail`, e o runner
26
+ continua os demais — nunca propaga exceção (NFR de resiliência)
27
+ - [x] `worstStatus` só devolve `fail` para `critical`; `warn` nunca escala
28
+ - [x] `env` injetável (`{ root, importModule, fs, workspace }`) com default real (D5)
29
+ - [x] `test/health.test.js` cobre cascata, blindagem e `worstStatus` com probes de fixture
30
+ - [x] Zero dependências novas (plano §6)
31
+
32
+ ## T2 — Probes de memória: `native-abi`, `memory-db`, `memory-fresh`
33
+ - **Owner**: Worker
34
+ - **Estimativa**: M
35
+ - **Depende de**: T1
36
+ - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
37
+ - **Escopo**: os três checks que teriam pego a quebra de hoje. É o núcleo do núcleo.
38
+ - **Done quando**:
39
+ - [x] `native-abi` (critical) classifica por `err.code`, **não** por string de mensagem (risco da
40
+ spec): `ERR_DLOPEN_FAILED` → `npm rebuild better-sqlite3`; `ERR_MODULE_NOT_FOUND` →
41
+ `npm install` (AC-3)
42
+ - [x] `memory-db` (critical, `dependsOn: native-abi`) distingue **ausente** de **inacessível**,
43
+ cada um com sua correção (AC-4)
44
+ - [x] `memory-fresh` (**warn**, `dependsOn: memory-db`): `memory/` alterado depois do último sync
45
+ → `npm run sync:universal`. Reaproveita a lógica de `newestMemoryMtime` que hoje vive no
46
+ hook (AC-4)
47
+ - [x] Teste do ABI quebrado injeta `env.importModule` que lança `ERR_DLOPEN_FAILED` — sem mock de
48
+ módulo, sem corromper `node_modules` (D5)
49
+ - [x] Cada probe testado nos dois estados: são e quebrado (AC-9)
50
+
51
+ ## T3 — Probes de ambiente: `workspace`, `node-engines`
52
+ - **Owner**: Worker
53
+ - **Estimativa**: P
54
+ - **Depende de**: T1
55
+ - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
56
+ - **Done quando**:
57
+ - [x] `workspace` (**warn**, D4) usa `getWorkspaceInfo()` de `lib/workspace.mjs`; se não resolve
58
+ para diretório existente → `npm run workspace:init`. Reporta também a **origem** da
59
+ resolução (`FORJA_WORKSPACE` / `~/.forjarc.json` / default), que é metade do diagnóstico
60
+ quando o workspace certo existe mas não é o que está sendo usado (AC-5)
61
+ - [x] `node-engines` (**warn**) compara `process.versions.node` com `engines.node` do
62
+ `package.json`
63
+ - [x] Ambos testados nos dois estados via `env.fs` / `env.workspace` injetados
64
+
65
+ ## T4 — Probes de regressão do repo: `runtime-deps`, `mcp-json`
66
+ - **Owner**: Worker
67
+ - **Estimativa**: M
68
+ - **Depende de**: T1
69
+ - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
70
+ - **Escopo**: converte em gate executável os dois invariantes que o ADR-0021 corrigiu à mão e que
71
+ hoje podem reincidir sem que nada perceba.
72
+ - **Done quando**:
73
+ - [x] Ambos com `scope: 'repo'` — **não** rodam fora do repo do framework, onde produziriam falso
74
+ positivo crítico na máquina do usuário final (D3). Detecção: `.git` + `package.json` com
75
+ `name: forjajs`
76
+ - [x] `runtime-deps` (critical): todo módulo importado **estaticamente** por script sob `files[]`
77
+ está em `dependencies`, não em `devDependencies` (AC-6). Parser **conservador**: import
78
+ dinâmico ou não resolvido → `warn`, nunca `fail` (risco da spec)
79
+ - [x] `mcp-json` (critical): nenhum path absoluto versionado em `.mcp.json` (AC-7)
80
+ - [x] Teste com fixture de `package.json`/`.mcp.json` quebrados, via `env.fs` e `env.root`
81
+ - [x] Teste garantindo que ambos são `skipped` quando `scope: 'runtime'`
82
+
83
+ ## T5 — `tools:doctor` consome a lib e vira gate
84
+ - **Owner**: Worker
85
+ - **Estimativa**: M
86
+ - **Depende de**: T2, T3, T4
87
+ - **Paths**: `scripts/tools-doctor.mjs`
88
+ - **Done quando**:
89
+ - [x] Duas seções na saída: **Núcleo** e **Ferramentas** (AC-2)
90
+ - [x] `exit 1` **se e somente se** algum check `critical` do núcleo falhar. Ferramenta opcional
91
+ ausente segue `exit 0` — contrato do ADR-0018 preservado (AC-2, D4)
92
+ - [x] `TOOLS[]` das cinco ferramentas opcionais permanece intocado (spec §5, fora de escopo)
93
+ - [x] Cada falha imprime o comando de correção ao lado
94
+ - [x] Roda em < 2s (NFR)
95
+ - [x] Funciona **sem `node_modules`** — é justamente aí que ele mais importa (NFR)
96
+
97
+ ## T6 — `SessionStart` consome a lib e perde a heurística própria
98
+ - **Owner**: Worker
99
+ - **Estimativa**: M
100
+ - **Depende de**: T2, T3
101
+ - **Paths**: `scripts/hook-session-start.mjs`
102
+ - **Escopo**: a task de maior risco. O hook roda em toda sessão e o ADR-0021 o marcou como "nunca
103
+ pode derrubar a sessão".
104
+ - **Done quando**:
105
+ - [x] `resolveDbPath()` e `staleIndex()` **deixam de existir** — o `catch { return null }` que
106
+ colapsa três causas distintas é a raiz do problema (plano §1)
107
+ - [x] A prescrição errada (`npm install` para ABI quebrado, linha 91) não existe mais no código
108
+ (AC-8)
109
+ - [x] Chama `runChecks({ scope: 'runtime' })` — zero heurística própria (AC-8)
110
+ - [x] **Sempre `exit 0`**: o hook reporta, nunca trava a sessão (ADR-0021)
111
+ - [x] Cabe com folga no timeout de 5s; se não couber, ver kill criteria do plano §8
112
+ - [x] `test/hooks.test.js` estendido: sem `node_modules` o hook degrada, não estoura
113
+
114
+ ## T7 — ADR-0023
115
+ - **Owner**: SDD Architect
116
+ - **Estimativa**: P
117
+ - **Depende de**: T5, T6
118
+ - **Paths**: `memory/90-decisions/0023-doctor-como-gate-do-nucleo.md`
119
+ - **Done quando**:
120
+ - [x] Registra D1 (checks como dados), D3 (`scope` repo/runtime) e a mudança de contrato do exit
121
+ code (AC-10)
122
+ - [x] Referencia ADR-0018 (que estende) e ADR-0021 (a classe de falha que fecha)
123
+ - [x] Segue `memory/90-decisions/_template.md`
124
+
125
+ ## T8 — Registry e documentação
126
+ - **Owner**: Worker
127
+ - **Estimativa**: P
128
+ - **Depende de**: T5
129
+ - **Paths**: `lib/core/registry.mjs`, `CLAUDE.md`, `docs/`
130
+ - **Done quando**:
131
+ - [x] `desc` do `tools:doctor` no registry reflete o novo papel (deixa de ser só "ferramentas de
132
+ processo")
133
+ - [x] `CLAUDE.md` e `docs/` onde o comando é descrito como "raio-x de ferramentas"
134
+ - [x] `npm test` verde, incluindo `test/forja-core.test.js` (integridade do registry, ADR-0020)
135
+
136
+ ## T9 — Validação no cenário real
137
+ - **Owner**: Governance
138
+ - **Estimativa**: P
139
+ - **Depende de**: T5, T6, T7, T8
140
+ - **Paths**: —
141
+ - **Done quando**:
142
+ - [x] `tools:doctor` roda sob um Node de **major diferente** e reporta o ABI quebrado com a
143
+ prescrição certa. Um doctor de ABI que nunca viu um ABI quebrado não está testado, está
144
+ escrito (plano §7)
145
+ - [x] `npm run project:check` e `npm test` verdes
146
+ - [x] `gitleaks detect --no-banner` limpo
147
+ - [x] Suíte completa verde (AC-9); spec → `done`
148
+
149
+ ## T10 — `spec:new` mantém a allow-list do `.gitignore`
150
+ - **Owner**: Worker
151
+ - **Estimativa**: P
152
+ - **Depende de**: — *(independente da lib; pode ir primeiro)*
153
+ - **Paths**: `scripts/spec-cli.mjs`, `test/spec-cli.test.js`
154
+ - **Contexto**: descoberto ao escrever o plano. O `.gitignore` ignora `/specs/*` e mantém uma
155
+ allow-list manual; **toda spec nova do framework nasce invisível ao git**. Aconteceu com esta
156
+ própria spec. Emenda de 2026-07-13 à spec (AC-11).
157
+ - **Done quando**:
158
+ - [x] `spec:new <slug>` acrescenta `!/specs/<slug>` ao bloco de allow-list do `.gitignore`
159
+ - [x] **Idempotente**: rodar duas vezes não duplica a linha
160
+ - [x] Insere **dentro do bloco existente** (após a última `!/specs/…`), não no fim do arquivo —
161
+ as regras seguintes do `.gitignore` dependem da ordem
162
+ - [x] Se o bloco não existir (ou o `.gitignore` sumir), **não falha** a criação da spec: avisa e
163
+ segue. Criar spec é o trabalho; manter o gitignore é o efeito colateral
164
+ - [x] Teste: cria spec num `.gitignore` de fixture e verifica a linha, a idempotência e a posição
165
+ - [x] `git status` mostra a spec recém-criada, sem passo manual (AC-11)
166
+
167
+ ---
168
+
169
+ ## Handoffs entre agentes
170
+
171
+ Este conjunto atravessa Worker (T1-T6, T8, T10), SDD Architect (T7) e Governance (T9). Registrar
172
+ handoff a cada fronteira via `npm run agent:route` — 7 campos obrigatórios (ADR-0005).