forjajs 2.0.3 → 2.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (701) hide show
  1. package/.claude/agents/context-engineer.md +25 -25
  2. package/.claude/agents/governance.md +55 -55
  3. package/.claude/agents/marketing.md +24 -24
  4. package/.claude/agents/orchestrator.md +31 -31
  5. package/.claude/agents/product.md +26 -26
  6. package/.claude/agents/release-auditor.md +68 -59
  7. package/.claude/agents/sdd-architect.md +34 -34
  8. package/.claude/settings.json +76 -76
  9. package/.claude/skills/new-adr/SKILL.md +61 -61
  10. package/.claude/skills/new-command/SKILL.md +67 -67
  11. package/.gemini-instructions.md +87 -87
  12. package/.github/copilot-instructions.md +87 -87
  13. package/.memoryrc.json +104 -104
  14. package/.openai-instructions.md +87 -87
  15. package/AGENTS.md +134 -134
  16. package/CHANGELOG.md +566 -550
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +65 -60
  19. package/LICENSE +21 -21
  20. package/README.md +358 -339
  21. package/README.pt-BR.md +345 -345
  22. package/boilerplates/01-api-rest/README.md +336 -336
  23. package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
  24. package/boilerplates/02-saas-starter/.env.example +25 -25
  25. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
  26. package/boilerplates/02-saas-starter/INFO.md +252 -252
  27. package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
  28. package/boilerplates/02-saas-starter/README.md +305 -305
  29. package/boilerplates/02-saas-starter/START-HERE.md +259 -259
  30. package/boilerplates/02-saas-starter/backend/package.json +87 -87
  31. package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
  32. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
  33. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
  34. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
  35. package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
  36. package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
  37. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
  38. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
  39. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
  40. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
  41. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
  42. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
  43. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
  44. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
  45. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
  46. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
  47. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
  48. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
  49. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
  50. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
  51. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
  52. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
  53. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
  54. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
  55. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
  56. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
  57. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
  58. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
  59. package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
  60. package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
  61. package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
  62. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
  63. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
  64. package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
  65. package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
  66. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
  67. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
  68. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
  69. package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
  70. package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
  71. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
  72. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
  73. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
  74. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
  75. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
  76. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
  77. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
  78. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
  79. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
  80. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
  81. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
  82. package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
  83. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
  84. package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
  85. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
  86. package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
  87. package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
  88. package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
  89. package/boilerplates/03-ecommerce-starter/README.md +465 -465
  90. package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
  91. package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
  92. package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
  93. package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
  94. package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
  95. package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
  96. package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
  97. package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
  98. package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
  99. package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
  100. package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
  101. package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
  102. package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
  103. package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
  104. package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
  105. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
  106. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
  107. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
  108. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
  109. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
  110. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
  111. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
  112. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
  113. package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
  114. package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
  115. package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
  116. package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
  117. package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
  118. package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
  119. package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
  120. package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
  121. package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
  122. package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
  123. package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
  124. package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
  125. package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
  126. package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
  127. package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
  128. package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
  129. package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
  130. package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
  131. package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
  132. package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
  133. package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
  134. package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
  135. package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
  136. package/boilerplates/04-microservices-starter/.env.example +43 -43
  137. package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
  138. package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
  139. package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
  140. package/boilerplates/04-microservices-starter/INDEX.md +377 -377
  141. package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
  142. package/boilerplates/04-microservices-starter/README.md +466 -466
  143. package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
  144. package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
  145. package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
  146. package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
  147. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
  148. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
  149. package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
  150. package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
  151. package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
  152. package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
  153. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
  154. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
  155. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
  156. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
  157. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
  158. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
  159. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
  160. package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
  161. package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
  162. package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
  163. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
  164. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
  165. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
  166. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
  167. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
  168. package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
  169. package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
  170. package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
  171. package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
  172. package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
  173. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
  174. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
  175. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
  176. package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
  177. package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
  178. package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
  179. package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
  180. package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
  181. package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
  182. package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
  183. package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
  184. package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
  185. package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
  186. package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
  187. package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
  188. package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
  189. package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
  190. package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
  191. package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
  192. package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
  193. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
  194. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
  195. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
  196. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
  197. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
  198. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
  199. package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
  200. package/boilerplates/04-microservices-starter/package.json +21 -21
  201. package/boilerplates/05-monorepo-starter/.env.example +1 -1
  202. package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
  203. package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
  204. package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
  205. package/boilerplates/05-monorepo-starter/README.md +318 -318
  206. package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
  207. package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
  208. package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
  209. package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
  210. package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
  211. package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
  212. package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
  213. package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
  214. package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
  215. package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
  216. package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
  217. package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
  218. package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
  219. package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
  220. package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
  221. package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
  222. package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
  223. package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
  224. package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
  225. package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
  226. package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
  227. package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
  228. package/boilerplates/05-monorepo-starter/package.json +30 -30
  229. package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
  230. package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
  231. package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
  232. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
  233. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
  234. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
  235. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
  236. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
  237. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
  238. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
  239. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
  240. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
  241. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
  242. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
  243. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
  244. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
  245. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
  246. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
  247. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
  248. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
  249. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
  250. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
  251. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
  252. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
  253. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
  254. package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
  255. package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
  256. package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
  257. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
  258. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
  259. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
  260. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
  261. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
  262. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
  263. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
  264. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
  265. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
  266. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
  267. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
  268. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
  269. package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
  270. package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
  271. package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
  272. package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
  273. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
  274. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
  275. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
  276. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
  277. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
  278. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
  279. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
  280. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
  281. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
  282. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
  283. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
  284. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
  285. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
  286. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
  287. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
  288. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
  289. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
  290. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
  291. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
  292. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
  293. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
  294. package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
  295. package/boilerplates/05-monorepo-starter/turbo.json +35 -35
  296. package/boilerplates/06-clean-arch/README.md +48 -48
  297. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
  298. package/boilerplates/06-clean-arch/backend/package.json +43 -43
  299. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
  300. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
  301. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
  302. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
  303. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
  304. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
  305. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
  306. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
  307. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
  308. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
  309. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
  310. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
  311. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
  312. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
  313. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
  314. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
  315. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
  316. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
  317. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
  318. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
  319. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
  320. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
  321. package/boilerplates/README.md +427 -427
  322. package/design-md/BRIEF-TEMPLATE.md +47 -47
  323. package/design-md/INDEX.md +35 -35
  324. package/design-md/MATRIX.md +24 -24
  325. package/design-md/PLAYBOOK.md +35 -35
  326. package/design-md/examples/agent-console-brief.md +48 -48
  327. package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
  328. package/dist/bin/create-memory-nest-kit.js +17 -17
  329. package/dist/bin/forja.js +14 -2
  330. package/dist/bin/init-project.js +38 -38
  331. package/dist/lib/audit.js +7 -7
  332. package/dist/lib/context-builder.js +32 -32
  333. package/dist/lib/core/doc-graph.js +6 -4
  334. package/dist/lib/core/registry.d.ts +54 -0
  335. package/dist/lib/core/registry.js +55 -0
  336. package/dist/lib/core/release.d.ts +53 -0
  337. package/dist/lib/core/release.js +5 -1
  338. package/dist/lib/generators/memory-generator.js +700 -698
  339. package/dist/lib/generators/nest-generator.js +398 -398
  340. package/dist/lib/generators/readme-generator.js +180 -180
  341. package/dist/lib/governance-report.js +39 -39
  342. package/dist/lib/project-upgrade.js +1 -1
  343. package/dist/lib/workspace.d.ts +7 -0
  344. package/dist/lib/workspace.js +63 -34
  345. package/dist/packages/adapter-sqlite/src/index.js +12 -12
  346. package/dist/packages/llm/src/index.d.ts +43 -0
  347. package/dist/packages/llm/src/index.js +108 -0
  348. package/dist/scripts/agent-harness.js +66 -64
  349. package/dist/scripts/agent-router.js +20 -20
  350. package/dist/scripts/build-smart-context.js +22 -22
  351. package/dist/scripts/compress-memory.js +8 -8
  352. package/dist/scripts/context-ops.js +29 -29
  353. package/dist/scripts/demo-autonomy.js +2 -2
  354. package/dist/scripts/demo-workspace.d.ts +6 -0
  355. package/dist/scripts/demo-workspace.js +101 -0
  356. package/dist/scripts/dev.js +13 -13
  357. package/dist/scripts/extract-global-knowledge.js +5 -5
  358. package/dist/scripts/generate-dashboard.js +11 -11
  359. package/dist/scripts/llm-fit.js +131 -0
  360. package/dist/scripts/memory-schema.js +48 -48
  361. package/dist/scripts/query-universal-memory.js +13 -13
  362. package/dist/scripts/sprint-manager.js +39 -39
  363. package/dist/scripts/sync-universal-memory.js +63 -50
  364. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  365. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  366. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  367. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  368. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  369. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  370. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  371. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  372. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  373. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  374. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  375. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  376. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  377. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  378. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  379. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  380. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  381. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  382. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  383. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  384. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  385. package/docs/agent-harnesses.md +149 -149
  386. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  387. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  388. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  389. package/docs/archive/FASE2-SUMMARY.md +263 -263
  390. package/docs/archive/FASE3-PROGRESS.md +355 -355
  391. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  392. package/docs/archive/INDICE-MASTER.md +282 -282
  393. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  394. package/docs/archive/README-REFINAMENTO.md +293 -293
  395. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  396. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  397. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  398. package/docs/archive/START-HERE.md +319 -319
  399. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  400. package/docs/archive/examples/v1/AGENTS.md +10 -10
  401. package/docs/archive/examples/v1/README.md +36 -36
  402. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  403. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  404. package/docs/archive/examples/v1/backend/package.json +42 -42
  405. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  406. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  407. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  408. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  409. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  410. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  411. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  412. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  413. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  414. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  415. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  416. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  417. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  418. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  419. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  420. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  421. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  422. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  423. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  424. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  425. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  426. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  427. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  428. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  429. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  430. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  431. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  432. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  433. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  434. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  435. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  436. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  437. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  438. package/docs/archive/examples/v2/AGENTS.md +16 -16
  439. package/docs/archive/examples/v2/README.md +35 -35
  440. package/docs/archive/examples/v2/agents/README.md +3 -3
  441. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  442. package/docs/archive/examples/v2/agents/dba.md +4 -4
  443. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  444. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  445. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  446. package/docs/archive/examples/v2/agents/security.md +4 -4
  447. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  448. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  449. package/docs/archive/examples/v2/backend/package.json +42 -42
  450. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  451. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  452. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  453. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  454. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  455. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  456. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  457. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  458. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  459. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  460. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  461. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  462. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  463. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  464. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  465. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  466. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  467. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  468. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  469. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  470. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  471. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  472. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  473. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  474. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  475. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  476. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  477. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  478. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  479. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  480. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  481. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  482. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  483. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  484. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  485. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  486. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  487. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  488. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  489. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  490. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  491. package/docs/archive/examples/v2/memory/README.md +8 -8
  492. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  493. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  494. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  495. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  496. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  497. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  498. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  499. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  500. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  501. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  502. package/docs/capacidades-externas.md +86 -86
  503. package/docs/cli-first-operacao.md +74 -74
  504. package/docs/dev-workflow.md +421 -421
  505. package/docs/examples.md +546 -546
  506. package/docs/fluxo.md +103 -103
  507. package/docs/glossary.md +453 -453
  508. package/docs/init-project.md +457 -457
  509. package/docs/llm-fit-loop.md +41 -0
  510. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  511. package/docs/modos-de-operacao.md +52 -0
  512. package/docs/personas/architect/README.md +333 -333
  513. package/docs/personas/developer/README.md +371 -371
  514. package/docs/personas/executive/README.md +172 -172
  515. package/docs/personas/qa/README.md +350 -350
  516. package/docs/processo-projeto.md +138 -138
  517. package/docs/produto/factsheet-marketing.md +151 -0
  518. package/docs/produto/roteiro-demo.md +47 -0
  519. package/docs/publishing.md +377 -377
  520. package/docs/quick-reference.md +409 -409
  521. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  522. package/docs/structure.md +360 -360
  523. package/docs/token-optimization.md +502 -502
  524. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  525. package/memory/00-global/mission.md +15 -15
  526. package/memory/00-global/shared-knowledge.md +8 -8
  527. package/memory/00-global/standards.md +47 -47
  528. package/memory/10-product/personas.md +21 -21
  529. package/memory/10-product/vision.md +27 -27
  530. package/memory/30-projects/README.md +15 -15
  531. package/memory/40-delivery/backlog.md +15 -15
  532. package/memory/40-delivery/current-sprint.md +23 -26
  533. package/memory/50-orchestration/gsd-harness.md +55 -55
  534. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  535. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  536. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  537. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  538. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  539. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  540. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  541. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  542. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  543. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  544. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  545. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  546. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  547. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  548. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  549. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  550. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  551. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  552. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  553. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  554. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  555. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  556. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  557. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  558. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  559. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  560. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  561. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  562. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  563. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  564. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  565. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  566. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  567. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  568. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  569. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  570. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  571. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  572. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  573. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  574. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  575. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  576. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  577. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  578. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  579. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  580. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  581. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  582. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  583. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  584. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  585. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  586. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  587. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  588. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  589. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  590. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  591. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  592. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  593. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  594. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  595. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  596. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  597. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  598. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  599. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  600. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  601. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  602. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  603. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  604. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  605. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  606. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  607. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  608. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  609. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  610. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  611. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  612. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  613. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  614. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  615. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  616. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  617. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  618. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  619. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  620. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  621. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  622. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  623. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  624. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  625. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  626. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  627. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  628. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  629. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  630. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  631. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  632. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  633. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  634. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  635. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  636. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  637. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  638. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  639. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  640. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  641. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  642. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  643. package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
  644. package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
  645. package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
  646. package/memory/90-decisions/_template.md +28 -28
  647. package/package.json +157 -150
  648. package/prompts/context-engineer-agent.md +19 -19
  649. package/prompts/governance-agent.md +16 -16
  650. package/prompts/marketing-agent.md +13 -13
  651. package/prompts/orchestrator-agent.md +18 -18
  652. package/prompts/product-agent.md +13 -13
  653. package/prompts/sdd-architect-agent.md +20 -20
  654. package/specs/README.md +70 -70
  655. package/specs/_templates/plan.md +43 -43
  656. package/specs/_templates/spec.md +43 -43
  657. package/specs/_templates/tasks.md +32 -32
  658. package/specs/clean-arch-boilerplate/plan.md +137 -137
  659. package/specs/clean-arch-boilerplate/spec.md +121 -121
  660. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  661. package/specs/cli-first-operacao/plan.md +53 -53
  662. package/specs/cli-first-operacao/spec.md +53 -53
  663. package/specs/cli-first-operacao/tasks.md +53 -53
  664. package/specs/code-context/spec.md +56 -56
  665. package/specs/coerencia-do-sistema/plan.md +155 -155
  666. package/specs/coerencia-do-sistema/spec.md +123 -123
  667. package/specs/coerencia-do-sistema/tasks.md +115 -115
  668. package/specs/dev-token-assets-db/plan.md +71 -71
  669. package/specs/dev-token-assets-db/spec.md +58 -58
  670. package/specs/dev-token-assets-db/tasks.md +58 -58
  671. package/specs/doctor-do-nucleo/plan.md +165 -165
  672. package/specs/doctor-do-nucleo/spec.md +139 -139
  673. package/specs/doctor-do-nucleo/tasks.md +172 -172
  674. package/specs/forja-core/spec.md +71 -71
  675. package/specs/gates/spec.md +63 -63
  676. package/specs/governanca-visivel/plan.md +122 -122
  677. package/specs/governanca-visivel/spec.md +112 -112
  678. package/specs/governanca-visivel/tasks.md +60 -60
  679. package/specs/harness-codegraph/spec.md +71 -71
  680. package/specs/memory-audit/spec.md +54 -54
  681. package/specs/orchestrate/spec.md +108 -108
  682. package/specs/orchestration-coherent/spec.md +95 -95
  683. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  684. package/specs/project-smoke/spec.md +96 -96
  685. package/specs/project-upgrade/spec.md +58 -58
  686. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  687. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  688. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  689. package/specs/release-auditor-health/plan.md +88 -0
  690. package/specs/release-auditor-health/spec.md +82 -0
  691. package/specs/release-auditor-health/tasks.md +72 -0
  692. package/specs/release-gate/plan.md +174 -174
  693. package/specs/release-gate/spec.md +122 -122
  694. package/specs/release-gate/tasks.md +183 -183
  695. package/specs/ts-migration/plan.md +200 -200
  696. package/specs/ts-migration/spec.md +119 -119
  697. package/specs/ts-migration/tasks.md +110 -110
  698. package/dist/scripts/server-persistence-probe.d.ts +0 -1
  699. package/dist/scripts/server-persistence-probe.js +0 -52
  700. package/dist/scripts/server-persistence-probe.mjs +0 -52
  701. /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
@@ -1,165 +1,165 @@
1
- # Plan: doctor-do-nucleo
2
-
3
- - **Spec**: ./spec.md
4
- - **Status**: done
5
- - **Criado em**: 2026-07-13
6
-
7
- > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
-
9
- ## 1. Abordagem técnica
10
-
11
- **Extend, não rewrite.** O `tools-doctor.mjs` já tem a forma certa — uma lista declarativa
12
- (`TOOLS[]`) percorrida por um runner burro. Erramos no *conteúdo* da lista, não na estrutura.
13
-
14
- Extraímos os checks para `lib/core/health.mjs` como **dados** (`CHECKS[]`), com um runner que os
15
- executa e devolve resultados estruturados. O `tools-doctor` vira uma das três superfícies de
16
- apresentação; `SessionStart` vira outra. Nenhuma superfície tem heurística própria — é justamente
17
- isso que permitiu, hoje, uma delas prescrever a correção errada sozinha.
18
-
19
- A mudança central de comportamento é **parar de colapsar causas distintas num booleano**. Hoje
20
- `hook-session-start.mjs:38-45` faz `catch { return null }`, engolindo *sem `node_modules`*,
21
- *ABI incompatível* e *banco ausente* no mesmo `null` — e a linha 91 prescreve a correção de apenas
22
- uma das três. Cada probe passa a **classificar a causa** e devolver a correção dela.
23
-
24
- ## 2. Módulos afetados
25
-
26
- | Caminho | Mudança | Risco |
27
- |---|---|---|
28
- | `lib/core/health.mjs` | **criar** — `CHECKS[]` + runner. Fonte única de verdade | M |
29
- | `scripts/tools-doctor.mjs` | editar — consome a lib; ganha seção Núcleo + exit code | M |
30
- | `scripts/hook-session-start.mjs` | editar — remove heurística própria (`resolveDbPath`, `staleIndex`) e a prescrição errada | A |
31
- | `lib/core/registry.mjs` | editar — `desc` do `tools:doctor` reflete o novo papel | B |
32
- | `scripts/spec-cli.mjs` | editar — `spec:new` mantém a allow-list do `.gitignore` (AC-11) | B |
33
- | `test/health.test.js` | **criar** — cada check nos dois estados | B |
34
- | `memory/90-decisions/0023-doctor-como-gate-do-nucleo.md` | **criar** — ADR | B |
35
- | `CLAUDE.md`, `docs/` | editar — `tools:doctor` deixa de ser "raio-x de ferramentas" | B |
36
-
37
- Risco alto no hook: ele roda em **toda** sessão e o ADR-0021 já o marcou como "nunca pode derrubar
38
- a sessão". Qualquer regressão ali é sentida imediatamente e em todo lugar.
39
-
40
- ## 3. Diagrama de fluxo
41
-
42
- ```
43
- tools:doctor ────┐
44
- SessionStart ────┼──► lib/core/health.mjs :: runChecks({ scope })
45
- release-auditor ─┘ │
46
- ▼
47
- ┌──────────────── CHECKS[] (declarativo) ────────────────┐
48
- │ id severity scope dependsOn │
49
- │ native-abi critical runtime — │
50
- │ memory-db critical runtime native-abi │
51
- │ memory-fresh warn runtime memory-db │
52
- │ workspace warn runtime — │
53
- │ node-engines warn runtime — │
54
- │ runtime-deps critical repo — │
55
- │ mcp-json critical repo — │
56
- └────────────────────────────────────────────────────────┘
57
- │
58
- Result[] { id, status, detail, fix, severity }
59
- │
60
- ┌───────────────────┴───────────────────┐
61
- ▼ ▼
62
- doctor: 2 seções + exit(1) se hook: só scope=runtime,
63
- algum critical falhou sempre exit(0), warn no contexto
64
- ```
65
-
66
- **Cascata (`dependsOn`)** é o que evita o pior modo de falha de um diagnóstico: com o ABI quebrado,
67
- `memory-db` e `memory-fresh` também falhariam, e o operador veria **três** erros sem saber qual é a
68
- raiz. Um check cujo `dependsOn` falhou é reportado como `skipped`, não como `fail`. Uma causa, uma
69
- linha vermelha, uma correção.
70
-
71
- ## 4. Contratos (API/CLI/Schema)
72
-
73
- ```js
74
- // lib/core/health.mjs
75
-
76
- /** @typedef {'critical'|'warn'} Severity */
77
- /** @typedef {'runtime'|'repo'} Scope */
78
- /** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
79
- /** @typedef {{ id, title, severity: Severity, scope: Scope, dependsOn?: string, probe }} Check */
80
- /** @typedef {{ id, title, severity, status: Status, detail: string, fix: string|null }} Result */
81
-
82
- export const CHECKS;
83
-
84
- /** Executa os checks. `scope: 'runtime'` roda só os baratos e portáveis (hook). */
85
- export async function runChecks(opts); // { scope = 'all', env } -> Promise<Result[]>
86
-
87
- /** 'fail' se algum critical falhou; senão 'warn' se houver warn; senão 'ok'. */
88
- export function worstStatus(results); // -> 'ok' | 'warn' | 'fail'
89
- ```
90
-
91
- O `probe` recebe um **ambiente injetável** (`env = { root, importModule, fs, workspace }`) e devolve
92
- `{ status, detail, fix }`. Nunca lança: o runner o envolve em try/catch e converte exceção
93
- inesperada em `fail` — um check que estoura ao diagnosticar é pior que check nenhum (NFR).
94
-
95
- **CLI** — `tools:doctor` mantém nome e entrada no registry (ADR-0020). Muda o contrato de saída:
96
-
97
- | Situação | Antes | Depois |
98
- |---|---|---|
99
- | Tudo são | `exit 0` | `exit 0` |
100
- | Ferramenta opcional ausente | `exit 0` | `exit 0` *(ADR-0018 preservado)* |
101
- | Índice defasado / workspace ausente | — | `exit 0` + aviso |
102
- | **Núcleo quebrado** | `exit 0` | **`exit 1`** + correção |
103
-
104
- ## 5. Decisões e alternativas
105
-
106
- **D1: Checks como dados, não como funções que imprimem.** Permite três superfícies com uma lógica
107
- só. Alternativa rejeitada: cada superfície chama helpers e formata do seu jeito — é literalmente o
108
- que temos hoje, e é a causa da divergência entre o que o doctor diz e o que o hook diz.
109
-
110
- **D2: Probes classificam a causa; o runner nunca colapsa em booleano.** `ERR_DLOPEN_FAILED` →
111
- `npm rebuild better-sqlite3`. `ERR_MODULE_NOT_FOUND` → `npm install`. Banco ausente →
112
- `npm run sync:universal`. Alternativa rejeitada: manter `catch → null` e só melhorar o texto da
113
- mensagem — daria uma prescrição *genérica*, e o problema de hoje foi precisamente uma prescrição
114
- genérica aplicada a um caso específico.
115
-
116
- **D3: `scope: repo | runtime`.** `runtime-deps` e `mcp-json` são checks de **regressão do
117
- repositório** — não fazem sentido numa instalação `npm i -g forjajs`, onde não há `devDependencies`
118
- instaladas nem `.mcp.json` versionado. Rodá-los fora do repo produziria falso positivo crítico no
119
- ambiente do usuário final. Detecção: presença de `.git` + `package.json` com `name: forjajs`.
120
-
121
- **D4: Só `critical` trava.** `workspace` ausente e `node-engines` abaixo do declarado entram como
122
- `warn`, não `fail` — o framework funciona sem workspace (só `project:new` não). Um gate que reprova
123
- o que não impede trabalho é um gate que se aprende a ignorar (risco nº 1 da spec).
124
-
125
- **D5: Injeção de dependência no probe (`env`).** Testar ABI quebrada exigiria mockar o loader de
126
- módulos do Node. Com `env.importModule` injetável, o teste passa uma função que lança
127
- `ERR_DLOPEN_FAILED` e verifica a prescrição — sem mock de módulo, sem corromper `node_modules`.
128
-
129
- **D6: Doctor diagnostica, não conserta.** Sem `--fix`. Rodar `npm rebuild` sem consentimento é a
130
- classe de risco oposta à que estamos consertando (spec §5, fora de escopo).
131
-
132
- D1, D3 e a mudança de contrato de exit code são estruturais → **ADR-0023**
133
- (`memory/90-decisions/0023-doctor-como-gate-do-nucleo.md`), referenciando ADR-0018 (que ele estende)
134
- e ADR-0021 (a classe de falha que ele fecha).
135
-
136
- ## 6. Dependências
137
-
138
- - **Specs**: nenhuma. Fecha a classe do ADR-0021; não depende de spec aberta.
139
- - **Pacotes npm**: **nenhum novo.** Tudo com `node:fs`, `node:path` e o `better-sqlite3` que já é
140
- `dependency`. Adicionar dependência a um módulo cujo propósito é funcionar quando as dependências
141
- quebram seria autodestrutivo.
142
- - **Migrações**: nenhuma. Nada de schema, nada de dado.
143
-
144
- ## 7. Rollout
145
-
146
- - [ ] Feature flag necessária? **Não.** A mudança é aditiva, exceto pelo exit code — que só passa a
147
- falhar em ambiente que **já está** quebrado.
148
- - [ ] Migração de dados existentes? **Não.**
149
- - [x] Doc/persona impactada? `CLAUDE.md` (tabela de comandos) e `docs/` onde `tools:doctor` é
150
- descrito como "raio-x de ferramentas". Persona **qa/governança** ganha gate novo.
151
- - [ ] **Ordem de merge**: `lib/core/health.mjs` + testes primeiro (nada consome ainda), depois as
152
- superfícies. O hook por último — é o de maior risco e o único que roda sempre.
153
- - [ ] Validar com `npm run tools:doctor` num Node de major diferente (o cenário de hoje) **antes**
154
- de fechar. Um doctor de ABI que nunca viu um ABI quebrado não está testado, está escrito.
155
-
156
- ## 8. Sinais de fracasso (kill criteria)
157
-
158
- - **O hook fica lento ou instável.** Ele roda em toda sessão e não pode derrubá-la (ADR-0021). Se
159
- `runChecks({ scope: 'runtime' })` não couber com folga no timeout de 5s, o hook volta a ter
160
- caminho próprio (mínimo, ainda consumindo a lib) em vez de arrastarmos o custo para toda sessão.
161
- - **`runtime-deps` vira ruído.** Se o parser estático de imports gerar falso positivo crítico mais
162
- de uma vez, ele é rebaixado a `warn` — a spec já prevê isso no risco, e um crítico que mente é
163
- pior que um warning honesto.
164
- - **O operador passa a rodar `tools:doctor` já sabendo o resultado.** Se o gate vira ritual, erramos
165
- a calibragem de severidade e voltamos a D4.
1
+ # Plan: doctor-do-nucleo
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: done
5
+ - **Criado em**: 2026-07-13
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ **Extend, não rewrite.** O `tools-doctor.mjs` já tem a forma certa — uma lista declarativa
12
+ (`TOOLS[]`) percorrida por um runner burro. Erramos no *conteúdo* da lista, não na estrutura.
13
+
14
+ Extraímos os checks para `lib/core/health.mjs` como **dados** (`CHECKS[]`), com um runner que os
15
+ executa e devolve resultados estruturados. O `tools-doctor` vira uma das três superfícies de
16
+ apresentação; `SessionStart` vira outra. Nenhuma superfície tem heurística própria — é justamente
17
+ isso que permitiu, hoje, uma delas prescrever a correção errada sozinha.
18
+
19
+ A mudança central de comportamento é **parar de colapsar causas distintas num booleano**. Hoje
20
+ `hook-session-start.mjs:38-45` faz `catch { return null }`, engolindo *sem `node_modules`*,
21
+ *ABI incompatível* e *banco ausente* no mesmo `null` — e a linha 91 prescreve a correção de apenas
22
+ uma das três. Cada probe passa a **classificar a causa** e devolver a correção dela.
23
+
24
+ ## 2. Módulos afetados
25
+
26
+ | Caminho | Mudança | Risco |
27
+ |---|---|---|
28
+ | `lib/core/health.mjs` | **criar** — `CHECKS[]` + runner. Fonte única de verdade | M |
29
+ | `scripts/tools-doctor.mjs` | editar — consome a lib; ganha seção Núcleo + exit code | M |
30
+ | `scripts/hook-session-start.mjs` | editar — remove heurística própria (`resolveDbPath`, `staleIndex`) e a prescrição errada | A |
31
+ | `lib/core/registry.mjs` | editar — `desc` do `tools:doctor` reflete o novo papel | B |
32
+ | `scripts/spec-cli.mjs` | editar — `spec:new` mantém a allow-list do `.gitignore` (AC-11) | B |
33
+ | `test/health.test.js` | **criar** — cada check nos dois estados | B |
34
+ | `memory/90-decisions/0023-doctor-como-gate-do-nucleo.md` | **criar** — ADR | B |
35
+ | `CLAUDE.md`, `docs/` | editar — `tools:doctor` deixa de ser "raio-x de ferramentas" | B |
36
+
37
+ Risco alto no hook: ele roda em **toda** sessão e o ADR-0021 já o marcou como "nunca pode derrubar
38
+ a sessão". Qualquer regressão ali é sentida imediatamente e em todo lugar.
39
+
40
+ ## 3. Diagrama de fluxo
41
+
42
+ ```
43
+ tools:doctor ────┐
44
+ SessionStart ────┼──► lib/core/health.mjs :: runChecks({ scope })
45
+ release-auditor ─┘ │
46
+ ▼
47
+ ┌──────────────── CHECKS[] (declarativo) ────────────────┐
48
+ │ id severity scope dependsOn │
49
+ │ native-abi critical runtime — │
50
+ │ memory-db critical runtime native-abi │
51
+ │ memory-fresh warn runtime memory-db │
52
+ │ workspace warn runtime — │
53
+ │ node-engines warn runtime — │
54
+ │ runtime-deps critical repo — │
55
+ │ mcp-json critical repo — │
56
+ └────────────────────────────────────────────────────────┘
57
+ │
58
+ Result[] { id, status, detail, fix, severity }
59
+ │
60
+ ┌───────────────────┴───────────────────┐
61
+ ▼ ▼
62
+ doctor: 2 seções + exit(1) se hook: só scope=runtime,
63
+ algum critical falhou sempre exit(0), warn no contexto
64
+ ```
65
+
66
+ **Cascata (`dependsOn`)** é o que evita o pior modo de falha de um diagnóstico: com o ABI quebrado,
67
+ `memory-db` e `memory-fresh` também falhariam, e o operador veria **três** erros sem saber qual é a
68
+ raiz. Um check cujo `dependsOn` falhou é reportado como `skipped`, não como `fail`. Uma causa, uma
69
+ linha vermelha, uma correção.
70
+
71
+ ## 4. Contratos (API/CLI/Schema)
72
+
73
+ ```js
74
+ // lib/core/health.mjs
75
+
76
+ /** @typedef {'critical'|'warn'} Severity */
77
+ /** @typedef {'runtime'|'repo'} Scope */
78
+ /** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
79
+ /** @typedef {{ id, title, severity: Severity, scope: Scope, dependsOn?: string, probe }} Check */
80
+ /** @typedef {{ id, title, severity, status: Status, detail: string, fix: string|null }} Result */
81
+
82
+ export const CHECKS;
83
+
84
+ /** Executa os checks. `scope: 'runtime'` roda só os baratos e portáveis (hook). */
85
+ export async function runChecks(opts); // { scope = 'all', env } -> Promise<Result[]>
86
+
87
+ /** 'fail' se algum critical falhou; senão 'warn' se houver warn; senão 'ok'. */
88
+ export function worstStatus(results); // -> 'ok' | 'warn' | 'fail'
89
+ ```
90
+
91
+ O `probe` recebe um **ambiente injetável** (`env = { root, importModule, fs, workspace }`) e devolve
92
+ `{ status, detail, fix }`. Nunca lança: o runner o envolve em try/catch e converte exceção
93
+ inesperada em `fail` — um check que estoura ao diagnosticar é pior que check nenhum (NFR).
94
+
95
+ **CLI** — `tools:doctor` mantém nome e entrada no registry (ADR-0020). Muda o contrato de saída:
96
+
97
+ | Situação | Antes | Depois |
98
+ |---|---|---|
99
+ | Tudo são | `exit 0` | `exit 0` |
100
+ | Ferramenta opcional ausente | `exit 0` | `exit 0` *(ADR-0018 preservado)* |
101
+ | Índice defasado / workspace ausente | — | `exit 0` + aviso |
102
+ | **Núcleo quebrado** | `exit 0` | **`exit 1`** + correção |
103
+
104
+ ## 5. Decisões e alternativas
105
+
106
+ **D1: Checks como dados, não como funções que imprimem.** Permite três superfícies com uma lógica
107
+ só. Alternativa rejeitada: cada superfície chama helpers e formata do seu jeito — é literalmente o
108
+ que temos hoje, e é a causa da divergência entre o que o doctor diz e o que o hook diz.
109
+
110
+ **D2: Probes classificam a causa; o runner nunca colapsa em booleano.** `ERR_DLOPEN_FAILED` →
111
+ `npm rebuild better-sqlite3`. `ERR_MODULE_NOT_FOUND` → `npm install`. Banco ausente →
112
+ `npm run sync:universal`. Alternativa rejeitada: manter `catch → null` e só melhorar o texto da
113
+ mensagem — daria uma prescrição *genérica*, e o problema de hoje foi precisamente uma prescrição
114
+ genérica aplicada a um caso específico.
115
+
116
+ **D3: `scope: repo | runtime`.** `runtime-deps` e `mcp-json` são checks de **regressão do
117
+ repositório** — não fazem sentido numa instalação `npm i -g forjajs`, onde não há `devDependencies`
118
+ instaladas nem `.mcp.json` versionado. Rodá-los fora do repo produziria falso positivo crítico no
119
+ ambiente do usuário final. Detecção: presença de `.git` + `package.json` com `name: forjajs`.
120
+
121
+ **D4: Só `critical` trava.** `workspace` ausente e `node-engines` abaixo do declarado entram como
122
+ `warn`, não `fail` — o framework funciona sem workspace (só `project:new` não). Um gate que reprova
123
+ o que não impede trabalho é um gate que se aprende a ignorar (risco nº 1 da spec).
124
+
125
+ **D5: Injeção de dependência no probe (`env`).** Testar ABI quebrada exigiria mockar o loader de
126
+ módulos do Node. Com `env.importModule` injetável, o teste passa uma função que lança
127
+ `ERR_DLOPEN_FAILED` e verifica a prescrição — sem mock de módulo, sem corromper `node_modules`.
128
+
129
+ **D6: Doctor diagnostica, não conserta.** Sem `--fix`. Rodar `npm rebuild` sem consentimento é a
130
+ classe de risco oposta à que estamos consertando (spec §5, fora de escopo).
131
+
132
+ D1, D3 e a mudança de contrato de exit code são estruturais → **ADR-0023**
133
+ (`memory/90-decisions/0023-doctor-como-gate-do-nucleo.md`), referenciando ADR-0018 (que ele estende)
134
+ e ADR-0021 (a classe de falha que ele fecha).
135
+
136
+ ## 6. Dependências
137
+
138
+ - **Specs**: nenhuma. Fecha a classe do ADR-0021; não depende de spec aberta.
139
+ - **Pacotes npm**: **nenhum novo.** Tudo com `node:fs`, `node:path` e o `better-sqlite3` que já é
140
+ `dependency`. Adicionar dependência a um módulo cujo propósito é funcionar quando as dependências
141
+ quebram seria autodestrutivo.
142
+ - **Migrações**: nenhuma. Nada de schema, nada de dado.
143
+
144
+ ## 7. Rollout
145
+
146
+ - [ ] Feature flag necessária? **Não.** A mudança é aditiva, exceto pelo exit code — que só passa a
147
+ falhar em ambiente que **já está** quebrado.
148
+ - [ ] Migração de dados existentes? **Não.**
149
+ - [x] Doc/persona impactada? `CLAUDE.md` (tabela de comandos) e `docs/` onde `tools:doctor` é
150
+ descrito como "raio-x de ferramentas". Persona **qa/governança** ganha gate novo.
151
+ - [ ] **Ordem de merge**: `lib/core/health.mjs` + testes primeiro (nada consome ainda), depois as
152
+ superfícies. O hook por último — é o de maior risco e o único que roda sempre.
153
+ - [ ] Validar com `npm run tools:doctor` num Node de major diferente (o cenário de hoje) **antes**
154
+ de fechar. Um doctor de ABI que nunca viu um ABI quebrado não está testado, está escrito.
155
+
156
+ ## 8. Sinais de fracasso (kill criteria)
157
+
158
+ - **O hook fica lento ou instável.** Ele roda em toda sessão e não pode derrubá-la (ADR-0021). Se
159
+ `runChecks({ scope: 'runtime' })` não couber com folga no timeout de 5s, o hook volta a ter
160
+ caminho próprio (mínimo, ainda consumindo a lib) em vez de arrastarmos o custo para toda sessão.
161
+ - **`runtime-deps` vira ruído.** Se o parser estático de imports gerar falso positivo crítico mais
162
+ de uma vez, ele é rebaixado a `warn` — a spec já prevê isso no risco, e um crítico que mente é
163
+ pior que um warning honesto.
164
+ - **O operador passa a rodar `tools:doctor` já sabendo o resultado.** Se o gate vira ritual, erramos
165
+ a calibragem de severidade e voltamos a D4.
@@ -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.