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,155 +1,155 @@
1
- # Plan: coerencia-do-sistema
2
-
3
- - **Spec**: ./spec.md
4
- - **Status**: done
5
- - **Criado em**: 2026-07-15
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
- Três checks novos no catálogo de `health.mjs`, no molde dos que já existem (`runtime-deps`,
12
- `mcp-json`): `scope: repo`, guardados por `isFrameworkRepo(env)`, cada um nomeando arquivo, linha e
13
- correção. **Nenhuma máquina nova** — o runner de `checks.mjs` já roda tudo isso.
14
-
15
- O que é genuinamente novo é a **leitura da documentação como dado**. Hoje o `health.mjs` lê código
16
- (imports, `package.json`, `.mcp.json`); agora precisa ler os `.md` e extrair duas coisas: comandos
17
- citados e links relativos. Isso vira `lib/core/doc-graph.mjs` — um scanner puro, sem opinião sobre
18
- severidade, testável isoladamente. Os três checks são finos: chamam o scanner e comparam com a
19
- verdade (o registry, o sistema de arquivos).
20
-
21
- O ponto que decide se a spec vale a pena é o **AC-2**: a allowlist de comandos do projeto gerado
22
- tem que ser *derivada*, não escrita. Confirmei em campo que dá: parsear o bloco `"scripts"` dos
23
- `lib/generators/*.js` produz exatamente `start:dev`, `test:cov`, `memory:db:*` etc. — os 7 falsos
24
- positivos que a auditoria manual pegou. Lista manual mente com o tempo; a derivada acompanha o
25
- gerador sozinha.
26
-
27
- ## 2. Módulos afetados
28
-
29
- | Caminho | Mudança | Risco |
30
- |---|---|---|
31
- | `lib/core/doc-graph.mjs` | **criar** — scanner puro: cita comandos, coleta links, deriva allowlist | M |
32
- | `lib/core/health.mjs` | editar — 3 checks novos no `CHECKS[]` | B |
33
- | `test/doc-graph.test.js` | **criar** — o scanner, isolado | B |
34
- | `test/health.test.js` | editar — os 3 checks nos dois estados, incluindo o falso positivo do AC-2 | B |
35
- | `docs/token-optimization.md` etc. | corrigir o que o check acusar (já limpo na v1.1.4, mas o gate é quem confirma) | B |
36
- | `README`/`docs` | documentar `memory:extract` (AC-10) | B |
37
- | `memory/90-decisions/0025-*.md` | **criar** — ADR | B |
38
-
39
- Risco no `doc-graph.mjs`, não no `health.mjs`: os checks são triviais; a dificuldade toda é o
40
- scanner não gerar falso positivo. Um `docs-commands` que acusa demais reprova a documentação
41
- inteira e é desligado no primeiro dia — pior que não existir.
42
-
43
- ## 3. Diagrama de fluxo
44
-
45
- ```
46
- tools:doctor (scope: repo)
47
- │
48
- ▼
49
- ┌──────────────── lib/core/doc-graph.mjs ────────────────┐
50
- │ scanDocs(env) → [{ file, line, command }] │ citações forja/npm run
51
- │ scanLinks(env) → [{ file, line, target }] │ links markdown relativos
52
- │ projectCommands(env) → Set<string> │ derivada de lib/generators/
53
- └────────────────────────────────────────────────────────┘
54
- │ │ │
55
- ▼ ▼ ▼
56
- docs-commands docs-links commands-documented
57
- (critical) (warn) (warn)
58
- citado ∈ registry target existe registry ⊆ citados
59
- ∪ projectCommands nos .md
60
- │ │ │
61
- └──────────── Result[] { file, line, detail, fix } ──────────┘
62
- ```
63
-
64
- ## 4. Contratos (API/CLI/Schema)
65
-
66
- ```js
67
- // lib/core/doc-graph.mjs — leitura pura, sem juízo de severidade
68
-
69
- /** Superfícies de instrução escaneadas. docs/archive, boilerplates e specs ficam de fora (§5 D3). */
70
- export const DOC_SURFACES; // ['docs', 'prompts', '.claude/agents', 'AGENTS.md', 'CLAUDE.md', 'README.md', 'README.en.md', 'DOC-MAP.md']
71
-
72
- /** Comandos citados como `forja x:y` ou `npm run x:y` em bloco de código. { file, line, command } */
73
- export function scanCommands(env);
74
-
75
- /** Links markdown relativos (não http, âncora ignorada). { file, line, target } */
76
- export function scanLinks(env);
77
-
78
- /** Allowlist DERIVADA: keys do bloco "scripts" dos geradores. Nunca uma lista literal. */
79
- export function projectCommands(env); // -> Set<string>
80
- ```
81
-
82
- **Regex de comando** — casa `(?:forja |npm run )` seguido de um token **com ao menos um `:`**
83
- (`spec:new`, `code:impact`). O `:` é o discriminador: todo comando do registry o tem, e nenhuma
84
- prosa (`"forja does X"`) o casa por acidente. Só dentro de bloco/span de código — prosa livre.
85
-
86
- **Contrato dos checks** (severidade honesta, AC-6):
87
-
88
- | Check | Severity | Reprova quando | Fix prescrito |
89
- |---|---|---|---|
90
- | `docs-commands` | critical | comando citado ∉ registry ∪ `projectCommands` | "renomeie para `<x>` ou remova a citação em `file:line`" |
91
- | `commands-documented` | warn | comando do registry citado em nenhum `.md` | "documente `<cmd>` em algum `.md` (ou remova do registry)" |
92
- | `docs-links` | warn | link relativo aponta para inexistente | "crie o alvo ou corrija o link em `file:line`" |
93
-
94
- ## 5. Decisões e alternativas
95
-
96
- **D1: Scanner puro separado dos checks.** `doc-graph.mjs` lê e devolve dados; os checks julgam.
97
- Permite testar o parsing (a parte difícil) sem montar o ambiente do doctor, e permite que um quarto
98
- consumidor use o mesmo scan amanhã. Alternativa rejeitada: lógica de parsing embutida em cada check
99
- — foi assim que o `runtime-deps` e o `release.mjs` acabaram com dois parsers de import quase iguais.
100
-
101
- **D2: Allowlist derivada dos geradores (AC-2).** A prova de fogo da spec. `projectCommands(env)`
102
- parseia o bloco `"scripts"` dos `lib/generators/*.js`. Alternativa rejeitada: lista literal no
103
- código — é a armadilha do `.gitignore` da SPEC-009, onde a allow-list manual engoliu uma spec em
104
- silêncio. Uma lista que não acompanha o gerador vira mentira no primeiro comando novo do boilerplate.
105
-
106
- **D3: Escopo do scan — instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
107
- `.claude/agents/` e os `.md` de raiz. **Fora**: `docs/archive/` (legado, off-limits), `boilerplates/`
108
- (é conteúdo do projeto gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/90-*`
109
- (registro histórico: uma spec ou ADR pode legitimamente citar um comando proposto ou já removido).
110
- O gate protege o que instrui o agente *agora*, não o que registrou o passado.
111
-
112
- **D4: `:` como discriminador de comando.** Em vez de tentar entender a gramática do CLI, exijo o
113
- `:`. Simples, e cobre 42/42 do registry. Um comando futuro sem `:` escaparia — mas hoje nenhum
114
- existe, e inventar parser de gramática para um caso inexistente é criar o problema que não temos.
115
-
116
- **D5: `docs-commands` é o único crítico.** Comando fantasma faz o agente agir errado — trava.
117
- Comando não-documentado e link quebrado atrapalham mas não param ninguém: `warn`. Reprovar release
118
- por um link quebrado num doc é como o `deps-unused` seria se fosse crítico — ensina o time a ignorar
119
- o gate.
120
-
121
- **D6: `memory:extract` — decisão adiada para as tasks.** É o único órfão real. Documentar ou remover
122
- é chamada de quem conhece o uso dele; o plano não força a mão. O que o plano garante é que, depois,
123
- o `commands-documented` não deixa nascer um órfão novo.
124
-
125
- D1, D2 e D3 são estruturais → **ADR-0025**, referenciando ADR-0023/0024 (mesma família de gate,
126
- terceira fronteira: a instrução) e ADR-0021 (a classe "erra sem avisar").
127
-
128
- ## 6. Dependências
129
-
130
- - **Specs**: SPEC-009 (`health.mjs`/`checks.mjs` são a base). Já `done`.
131
- - **Pacotes npm**: **nenhum novo.** `node:fs` e regex. Parsear markdown com um lexer completo seria
132
- peso morto — precisamos de citações em code-span e links, não de um AST de CommonMark.
133
- - **Migrações**: nenhuma.
134
-
135
- ## 7. Rollout
136
-
137
- - [ ] **Ordem**: `doc-graph.mjs` + seus testes primeiro (nada o consome ainda) → os 3 checks →
138
- rodar o doctor e **corrigir o que ele acusar** → CI já pega de graça (o doctor já é step, ADR-0024).
139
- - [x] Doc/persona: governança ganha mais um critério; nenhuma persona muda de fluxo.
140
- - [ ] **Validar o AC-2 de verdade**: adicionar um `"foo:bar"` temporário aos scripts de um gerador e
141
- confirmar que `docs-commands` **não** passa a exigir `foo:bar` na doc. Se exigir, a derivação
142
- não está pegando o gerador certo.
143
- - [ ] O primeiro `npm run tools:doctor` depois disto é o teste real: ele deve passar (a doc já foi
144
- limpa na v1.1.4), provando que o gate concorda com a correção manual — não inventa trabalho.
145
-
146
- ## 8. Sinais de fracasso (kill criteria)
147
-
148
- - **`docs-commands` gera um falso positivo crítico.** Se acontecer uma vez com comando legítimo, ele
149
- é rebaixado a `warn` até o scanner ser corrigido — um crítico que mente é pior que um warning
150
- honesto, e aqui ele bloquearia o CI de todo mundo.
151
- - **O scanner fica caro.** Se ler os `.md` todos passar de ~1s, o scan vira lazy/cacheado por mtime —
152
- mas os checks são `scope: repo`, fora do `SessionStart`, então a folga é grande.
153
- - **A regra vira desincentivo a documentar.** Se alguém parar de escrever doc para não "brigar com o
154
- gate", erramos: o gate só cobre citação de *comando*, e isso precisa estar claro na mensagem de
155
- erro (que aponta a linha e diz "renomeie ou remova a citação", nunca "não escreva").
1
+ # Plan: coerencia-do-sistema
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: done
5
+ - **Criado em**: 2026-07-15
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
+ Três checks novos no catálogo de `health.mjs`, no molde dos que já existem (`runtime-deps`,
12
+ `mcp-json`): `scope: repo`, guardados por `isFrameworkRepo(env)`, cada um nomeando arquivo, linha e
13
+ correção. **Nenhuma máquina nova** — o runner de `checks.mjs` já roda tudo isso.
14
+
15
+ O que é genuinamente novo é a **leitura da documentação como dado**. Hoje o `health.mjs` lê código
16
+ (imports, `package.json`, `.mcp.json`); agora precisa ler os `.md` e extrair duas coisas: comandos
17
+ citados e links relativos. Isso vira `lib/core/doc-graph.mjs` — um scanner puro, sem opinião sobre
18
+ severidade, testável isoladamente. Os três checks são finos: chamam o scanner e comparam com a
19
+ verdade (o registry, o sistema de arquivos).
20
+
21
+ O ponto que decide se a spec vale a pena é o **AC-2**: a allowlist de comandos do projeto gerado
22
+ tem que ser *derivada*, não escrita. Confirmei em campo que dá: parsear o bloco `"scripts"` dos
23
+ `lib/generators/*.js` produz exatamente `start:dev`, `test:cov`, `memory:db:*` etc. — os 7 falsos
24
+ positivos que a auditoria manual pegou. Lista manual mente com o tempo; a derivada acompanha o
25
+ gerador sozinha.
26
+
27
+ ## 2. Módulos afetados
28
+
29
+ | Caminho | Mudança | Risco |
30
+ |---|---|---|
31
+ | `lib/core/doc-graph.mjs` | **criar** — scanner puro: cita comandos, coleta links, deriva allowlist | M |
32
+ | `lib/core/health.mjs` | editar — 3 checks novos no `CHECKS[]` | B |
33
+ | `test/doc-graph.test.js` | **criar** — o scanner, isolado | B |
34
+ | `test/health.test.js` | editar — os 3 checks nos dois estados, incluindo o falso positivo do AC-2 | B |
35
+ | `docs/token-optimization.md` etc. | corrigir o que o check acusar (já limpo na v1.1.4, mas o gate é quem confirma) | B |
36
+ | `README`/`docs` | documentar `memory:extract` (AC-10) | B |
37
+ | `memory/90-decisions/0025-*.md` | **criar** — ADR | B |
38
+
39
+ Risco no `doc-graph.mjs`, não no `health.mjs`: os checks são triviais; a dificuldade toda é o
40
+ scanner não gerar falso positivo. Um `docs-commands` que acusa demais reprova a documentação
41
+ inteira e é desligado no primeiro dia — pior que não existir.
42
+
43
+ ## 3. Diagrama de fluxo
44
+
45
+ ```
46
+ tools:doctor (scope: repo)
47
+ │
48
+ ▼
49
+ ┌──────────────── lib/core/doc-graph.mjs ────────────────┐
50
+ │ scanDocs(env) → [{ file, line, command }] │ citações forja/npm run
51
+ │ scanLinks(env) → [{ file, line, target }] │ links markdown relativos
52
+ │ projectCommands(env) → Set<string> │ derivada de lib/generators/
53
+ └────────────────────────────────────────────────────────┘
54
+ │ │ │
55
+ ▼ ▼ ▼
56
+ docs-commands docs-links commands-documented
57
+ (critical) (warn) (warn)
58
+ citado ∈ registry target existe registry ⊆ citados
59
+ ∪ projectCommands nos .md
60
+ │ │ │
61
+ └──────────── Result[] { file, line, detail, fix } ──────────┘
62
+ ```
63
+
64
+ ## 4. Contratos (API/CLI/Schema)
65
+
66
+ ```js
67
+ // lib/core/doc-graph.mjs — leitura pura, sem juízo de severidade
68
+
69
+ /** Superfícies de instrução escaneadas. docs/archive, boilerplates e specs ficam de fora (§5 D3). */
70
+ export const DOC_SURFACES; // ['docs', 'prompts', '.claude/agents', 'AGENTS.md', 'CLAUDE.md', 'README.md', 'README.en.md', 'DOC-MAP.md']
71
+
72
+ /** Comandos citados como `forja x:y` ou `npm run x:y` em bloco de código. { file, line, command } */
73
+ export function scanCommands(env);
74
+
75
+ /** Links markdown relativos (não http, âncora ignorada). { file, line, target } */
76
+ export function scanLinks(env);
77
+
78
+ /** Allowlist DERIVADA: keys do bloco "scripts" dos geradores. Nunca uma lista literal. */
79
+ export function projectCommands(env); // -> Set<string>
80
+ ```
81
+
82
+ **Regex de comando** — casa `(?:forja |npm run )` seguido de um token **com ao menos um `:`**
83
+ (`spec:new`, `code:impact`). O `:` é o discriminador: todo comando do registry o tem, e nenhuma
84
+ prosa (`"forja does X"`) o casa por acidente. Só dentro de bloco/span de código — prosa livre.
85
+
86
+ **Contrato dos checks** (severidade honesta, AC-6):
87
+
88
+ | Check | Severity | Reprova quando | Fix prescrito |
89
+ |---|---|---|---|
90
+ | `docs-commands` | critical | comando citado ∉ registry ∪ `projectCommands` | "renomeie para `<x>` ou remova a citação em `file:line`" |
91
+ | `commands-documented` | warn | comando do registry citado em nenhum `.md` | "documente `<cmd>` em algum `.md` (ou remova do registry)" |
92
+ | `docs-links` | warn | link relativo aponta para inexistente | "crie o alvo ou corrija o link em `file:line`" |
93
+
94
+ ## 5. Decisões e alternativas
95
+
96
+ **D1: Scanner puro separado dos checks.** `doc-graph.mjs` lê e devolve dados; os checks julgam.
97
+ Permite testar o parsing (a parte difícil) sem montar o ambiente do doctor, e permite que um quarto
98
+ consumidor use o mesmo scan amanhã. Alternativa rejeitada: lógica de parsing embutida em cada check
99
+ — foi assim que o `runtime-deps` e o `release.mjs` acabaram com dois parsers de import quase iguais.
100
+
101
+ **D2: Allowlist derivada dos geradores (AC-2).** A prova de fogo da spec. `projectCommands(env)`
102
+ parseia o bloco `"scripts"` dos `lib/generators/*.js`. Alternativa rejeitada: lista literal no
103
+ código — é a armadilha do `.gitignore` da SPEC-009, onde a allow-list manual engoliu uma spec em
104
+ silêncio. Uma lista que não acompanha o gerador vira mentira no primeiro comando novo do boilerplate.
105
+
106
+ **D3: Escopo do scan — instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
107
+ `.claude/agents/` e os `.md` de raiz. **Fora**: `docs/archive/` (legado, off-limits), `boilerplates/`
108
+ (é conteúdo do projeto gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/90-*`
109
+ (registro histórico: uma spec ou ADR pode legitimamente citar um comando proposto ou já removido).
110
+ O gate protege o que instrui o agente *agora*, não o que registrou o passado.
111
+
112
+ **D4: `:` como discriminador de comando.** Em vez de tentar entender a gramática do CLI, exijo o
113
+ `:`. Simples, e cobre 42/42 do registry. Um comando futuro sem `:` escaparia — mas hoje nenhum
114
+ existe, e inventar parser de gramática para um caso inexistente é criar o problema que não temos.
115
+
116
+ **D5: `docs-commands` é o único crítico.** Comando fantasma faz o agente agir errado — trava.
117
+ Comando não-documentado e link quebrado atrapalham mas não param ninguém: `warn`. Reprovar release
118
+ por um link quebrado num doc é como o `deps-unused` seria se fosse crítico — ensina o time a ignorar
119
+ o gate.
120
+
121
+ **D6: `memory:extract` — decisão adiada para as tasks.** É o único órfão real. Documentar ou remover
122
+ é chamada de quem conhece o uso dele; o plano não força a mão. O que o plano garante é que, depois,
123
+ o `commands-documented` não deixa nascer um órfão novo.
124
+
125
+ D1, D2 e D3 são estruturais → **ADR-0025**, referenciando ADR-0023/0024 (mesma família de gate,
126
+ terceira fronteira: a instrução) e ADR-0021 (a classe "erra sem avisar").
127
+
128
+ ## 6. Dependências
129
+
130
+ - **Specs**: SPEC-009 (`health.mjs`/`checks.mjs` são a base). Já `done`.
131
+ - **Pacotes npm**: **nenhum novo.** `node:fs` e regex. Parsear markdown com um lexer completo seria
132
+ peso morto — precisamos de citações em code-span e links, não de um AST de CommonMark.
133
+ - **Migrações**: nenhuma.
134
+
135
+ ## 7. Rollout
136
+
137
+ - [ ] **Ordem**: `doc-graph.mjs` + seus testes primeiro (nada o consome ainda) → os 3 checks →
138
+ rodar o doctor e **corrigir o que ele acusar** → CI já pega de graça (o doctor já é step, ADR-0024).
139
+ - [x] Doc/persona: governança ganha mais um critério; nenhuma persona muda de fluxo.
140
+ - [ ] **Validar o AC-2 de verdade**: adicionar um `"foo:bar"` temporário aos scripts de um gerador e
141
+ confirmar que `docs-commands` **não** passa a exigir `foo:bar` na doc. Se exigir, a derivação
142
+ não está pegando o gerador certo.
143
+ - [ ] O primeiro `npm run tools:doctor` depois disto é o teste real: ele deve passar (a doc já foi
144
+ limpa na v1.1.4), provando que o gate concorda com a correção manual — não inventa trabalho.
145
+
146
+ ## 8. Sinais de fracasso (kill criteria)
147
+
148
+ - **`docs-commands` gera um falso positivo crítico.** Se acontecer uma vez com comando legítimo, ele
149
+ é rebaixado a `warn` até o scanner ser corrigido — um crítico que mente é pior que um warning
150
+ honesto, e aqui ele bloquearia o CI de todo mundo.
151
+ - **O scanner fica caro.** Se ler os `.md` todos passar de ~1s, o scan vira lazy/cacheado por mtime —
152
+ mas os checks são `scope: repo`, fora do `SessionStart`, então a folga é grande.
153
+ - **A regra vira desincentivo a documentar.** Se alguém parar de escrever doc para não "brigar com o
154
+ gate", erramos: o gate só cobre citação de *comando*, e isso precisa estar claro na mensagem de
155
+ erro (que aponta a linha e diz "renomeie ou remova a citação", nunca "não escreva").
@@ -1,123 +1,123 @@
1
- # Spec: coerencia-do-sistema
2
-
3
- - **ID**: SPEC-011
4
- - **Status**: done
5
- - **Owner**: apk
6
- - **Criado em**: 2026-07-14
7
- - **Sprint alvo**: S?
8
- - **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
9
-
10
- ## 1. Problema
11
-
12
- **Nenhum step do sistema pode ser obscuro.** O Forja é operado por agentes que leem a documentação
13
- e executam o que ela manda. Quando a doc e o código divergem, o agente não erra por burrice — erra
14
- por obediência.
15
-
16
- Em 2026-07-14, uma auditoria manual encontrou:
17
-
18
- | O que | Onde | Consequência |
19
- |---|---|---|
20
- | `context:build`, `memory:db:reindex`, `memory:db:stats`, `cache:clear` — **quatro comandos que não existem em lugar nenhum** | `docs/token-optimization.md` | É o documento que ensina a **economia de tokens** (ADR-0009), o mecanismo central do framework. Um agente obediente executa comandos fantasma |
21
- | Link para `docs/DEPLOYMENT.md`, que nunca existiu | idem | — |
22
- | `tools:doctor` descrito como *"saber quais gates opcionais estão disponíveis"* | `.claude/agents/governance.md`, `prompts/governance-agent.md` | É a definição de **antes** do ADR-0023. O papel que reprova merges não sabia que o gate reprova |
23
- | `release:check` desconhecido pelo Governance | idem | Criamos o gate do tarball e não contamos a quem deveria usá-lo |
24
- | 2 comandos do registry **nunca mencionados** em doc, prompt, agente ou ADR | `workspace:project:check`, `memory:extract` | Existem e ninguém sabe para quê. Capacidade obscura é capacidade morta |
25
-
26
- Nada disso quebrou um teste. Nada apareceu no `git status`. É a classe que o ADR-0021 nomeia —
27
- *erra sem avisar* — aplicada à **camada de instrução**: o sistema descreve a si mesmo de forma
28
- incorreta, e quem age sobre essa descrição produz trabalho errado com aparência de trabalho certo.
29
-
30
- Os ADRs 0023 e 0024 fecharam essa classe no núcleo e no tarball. Falta a fronteira onde ela é mais
31
- barata de introduzir e mais cara de perceber: **a palavra escrita.** Toda vez que um comando é
32
- renomeado, um gate muda de contrato ou uma capacidade nasce, a documentação pode silenciosamente
33
- passar a mentir — e hoje nada percebe.
34
-
35
- ## 2. Proposta de valor
36
-
37
- **O sistema é obrigado a explicar a si mesmo, e a explicação é verificada.** Comando citado existe;
38
- comando que existe é citado; gate que reprova diz como corrigir. Divergência entre o que o Forja
39
- faz e o que ele diz que faz passa a reprovar o gate — em vez de virar armadilha para o próximo
40
- agente.
41
-
42
- ## 3. User stories
43
-
44
- - **Como** agente lendo a documentação, **quero** que todo comando citado exista de verdade,
45
- **para que** eu não execute um fantasma e conclua que o ambiente está quebrado.
46
- - **Como** operador, **quero** que toda capacidade do registry esteja explicada em algum lugar,
47
- **para que** eu não descubra por acaso que o framework já fazia o que fui construir à mão.
48
- - **Como** governança, **quero** que a mudança de contrato de um gate **quebre** a doc que o
49
- descreve errado, **para que** o `tools:doctor` não fique mais um dia sendo apresentado como
50
- "inventário de ferramentas opcionais" depois de virar gate.
51
- - **Como** quem mantém o framework, **quero** que renomear um comando seja um ato **detectável**,
52
- **para que** a renomeação não deixe um rastro de documentação morta.
53
-
54
- ## 4. Critérios de aceite (Definition of Done)
55
-
56
- - [x] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
57
- `forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
58
- `README.md` existe no registry (ADR-0020).
59
- - [x] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
60
- afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
61
- dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
62
- `.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
63
- - [x] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
64
- mencionado em pelo menos um `.md` versionado. Hoje 1 de 42 não é (`memory:extract`) — a
65
- reescrita canônica do README na v1.1.5 já documentou `workspace:project:check`.
66
- - [x] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
67
- versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
68
- - [x] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
69
- doctor na matriz (ADR-0024).
70
- - [x] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
71
- agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
72
- gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
73
- - [x] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
74
- está errado" sem dizer onde é só mais um step obscuro.
75
- - [x] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
76
- - [x] AC-9: ADR-0025 registrando a decisão.
77
- - [x] AC-10: O comando órfão restante (`memory:extract`) é documentado — ou removido do registry,
78
- se não servir mais. Capacidade obscura é capacidade morta.
79
-
80
- ## 5. Escopo
81
-
82
- **Dentro**:
83
- - `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
84
- - `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
85
- - Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
86
- - Documentar o comando órfão restante (`memory:extract`), ou removê-lo.
87
- - ADR-0025 + testes.
88
-
89
- **Fora** (explícito):
90
- - **Lint de prosa** (estilo, ortografia, tamanho de linha). Isto é `markdownlint`, já previsto no
91
- ADR-0018 como ferramenta opcional. Aqui só verificamos o que é **verificável contra o código**.
92
- - Validar links **externos** (http). Rede no gate é flakiness garantida.
93
- - Gerar documentação automaticamente a partir do registry. Doc gerada por máquina não explica o
94
- *porquê*, e o porquê é a parte que importa — o gate cobra que exista, não escreve por você.
95
- - Traduzir os docs em inglês (`token-optimization.md` está em inglês; outros em português). É dívida
96
- real, mas é outra spec.
97
-
98
- ## 6. NFRs / restrições
99
-
100
- - **Performance**: os três checks são `scope: repo` e só leem `.md` — ficam fora do `SessionStart`
101
- (que roda `scope: runtime`). O doctor completo continua < 2s.
102
- - **Zero falso positivo crítico**: o AC-2 é a prova de fogo. A auditoria manual acusou 11 comandos,
103
- e 7 eram legítimos. Um `docs-commands` ingênuo teria "corrigido" a documentação de onboarding
104
- inteira — pior que não ter check nenhum.
105
- - **Compatibilidade**: aditivo. Nenhum comando existente muda de contrato.
106
-
107
- ## 7. Riscos e mitigação
108
-
109
- | Risco | Probabilidade | Impacto | Mitigação |
110
- |---|---|---|---|
111
- | Falso positivo com comandos do projeto gerado | **A** | A | AC-2: allowlist **derivada** dos geradores, nunca manual. Já observado: 7 de 11 |
112
- | Regex casa comando dentro de bloco de exemplo hipotético | M | M | Só `npm run x` / `forja x` em bloco de código. Prosa não conta |
113
- | `commands-documented` vira ruído a cada comando novo | M | B | É `warn`. E documentar comando novo é o comportamento desejado |
114
- | O gate engessa a doc e desestimula escrever | B | M | Ele só cobra referências a **código**; prosa é livre |
115
-
116
- ## 8. Métricas de sucesso
117
-
118
- - **Zero** comandos fantasma na documentação, verificado a cada CI — em vez de a cada auditoria
119
- manual que alguém lembrar de fazer.
120
- - Renomear um comando passa a **quebrar o CI** enquanto a doc não acompanhar. Hoje renomear é grátis
121
- e a doc apodrece calada.
122
- - Os 42 comandos do registry passam a ter, cada um, ao menos um lugar onde o sistema explica o que
123
- ele faz. Nenhum step obscuro.
1
+ # Spec: coerencia-do-sistema
2
+
3
+ - **ID**: SPEC-011
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-14
7
+ - **Sprint alvo**: S?
8
+ - **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
9
+
10
+ ## 1. Problema
11
+
12
+ **Nenhum step do sistema pode ser obscuro.** O Forja é operado por agentes que leem a documentação
13
+ e executam o que ela manda. Quando a doc e o código divergem, o agente não erra por burrice — erra
14
+ por obediência.
15
+
16
+ Em 2026-07-14, uma auditoria manual encontrou:
17
+
18
+ | O que | Onde | Consequência |
19
+ |---|---|---|
20
+ | `context:build`, `memory:db:reindex`, `memory:db:stats`, `cache:clear` — **quatro comandos que não existem em lugar nenhum** | `docs/token-optimization.md` | É o documento que ensina a **economia de tokens** (ADR-0009), o mecanismo central do framework. Um agente obediente executa comandos fantasma |
21
+ | Link para `docs/DEPLOYMENT.md`, que nunca existiu | idem | — |
22
+ | `tools:doctor` descrito como *"saber quais gates opcionais estão disponíveis"* | `.claude/agents/governance.md`, `prompts/governance-agent.md` | É a definição de **antes** do ADR-0023. O papel que reprova merges não sabia que o gate reprova |
23
+ | `release:check` desconhecido pelo Governance | idem | Criamos o gate do tarball e não contamos a quem deveria usá-lo |
24
+ | 2 comandos do registry **nunca mencionados** em doc, prompt, agente ou ADR | `workspace:project:check`, `memory:extract` | Existem e ninguém sabe para quê. Capacidade obscura é capacidade morta |
25
+
26
+ Nada disso quebrou um teste. Nada apareceu no `git status`. É a classe que o ADR-0021 nomeia —
27
+ *erra sem avisar* — aplicada à **camada de instrução**: o sistema descreve a si mesmo de forma
28
+ incorreta, e quem age sobre essa descrição produz trabalho errado com aparência de trabalho certo.
29
+
30
+ Os ADRs 0023 e 0024 fecharam essa classe no núcleo e no tarball. Falta a fronteira onde ela é mais
31
+ barata de introduzir e mais cara de perceber: **a palavra escrita.** Toda vez que um comando é
32
+ renomeado, um gate muda de contrato ou uma capacidade nasce, a documentação pode silenciosamente
33
+ passar a mentir — e hoje nada percebe.
34
+
35
+ ## 2. Proposta de valor
36
+
37
+ **O sistema é obrigado a explicar a si mesmo, e a explicação é verificada.** Comando citado existe;
38
+ comando que existe é citado; gate que reprova diz como corrigir. Divergência entre o que o Forja
39
+ faz e o que ele diz que faz passa a reprovar o gate — em vez de virar armadilha para o próximo
40
+ agente.
41
+
42
+ ## 3. User stories
43
+
44
+ - **Como** agente lendo a documentação, **quero** que todo comando citado exista de verdade,
45
+ **para que** eu não execute um fantasma e conclua que o ambiente está quebrado.
46
+ - **Como** operador, **quero** que toda capacidade do registry esteja explicada em algum lugar,
47
+ **para que** eu não descubra por acaso que o framework já fazia o que fui construir à mão.
48
+ - **Como** governança, **quero** que a mudança de contrato de um gate **quebre** a doc que o
49
+ descreve errado, **para que** o `tools:doctor` não fique mais um dia sendo apresentado como
50
+ "inventário de ferramentas opcionais" depois de virar gate.
51
+ - **Como** quem mantém o framework, **quero** que renomear um comando seja um ato **detectável**,
52
+ **para que** a renomeação não deixe um rastro de documentação morta.
53
+
54
+ ## 4. Critérios de aceite (Definition of Done)
55
+
56
+ - [x] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
57
+ `forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
58
+ `README.md` existe no registry (ADR-0020).
59
+ - [x] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
60
+ afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
61
+ dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
62
+ `.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
63
+ - [x] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
64
+ mencionado em pelo menos um `.md` versionado. Hoje 1 de 42 não é (`memory:extract`) — a
65
+ reescrita canônica do README na v1.1.5 já documentou `workspace:project:check`.
66
+ - [x] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
67
+ versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
68
+ - [x] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
69
+ doctor na matriz (ADR-0024).
70
+ - [x] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
71
+ agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
72
+ gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
73
+ - [x] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
74
+ está errado" sem dizer onde é só mais um step obscuro.
75
+ - [x] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
76
+ - [x] AC-9: ADR-0025 registrando a decisão.
77
+ - [x] AC-10: O comando órfão restante (`memory:extract`) é documentado — ou removido do registry,
78
+ se não servir mais. Capacidade obscura é capacidade morta.
79
+
80
+ ## 5. Escopo
81
+
82
+ **Dentro**:
83
+ - `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
84
+ - `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
85
+ - Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
86
+ - Documentar o comando órfão restante (`memory:extract`), ou removê-lo.
87
+ - ADR-0025 + testes.
88
+
89
+ **Fora** (explícito):
90
+ - **Lint de prosa** (estilo, ortografia, tamanho de linha). Isto é `markdownlint`, já previsto no
91
+ ADR-0018 como ferramenta opcional. Aqui só verificamos o que é **verificável contra o código**.
92
+ - Validar links **externos** (http). Rede no gate é flakiness garantida.
93
+ - Gerar documentação automaticamente a partir do registry. Doc gerada por máquina não explica o
94
+ *porquê*, e o porquê é a parte que importa — o gate cobra que exista, não escreve por você.
95
+ - Traduzir os docs em inglês (`token-optimization.md` está em inglês; outros em português). É dívida
96
+ real, mas é outra spec.
97
+
98
+ ## 6. NFRs / restrições
99
+
100
+ - **Performance**: os três checks são `scope: repo` e só leem `.md` — ficam fora do `SessionStart`
101
+ (que roda `scope: runtime`). O doctor completo continua < 2s.
102
+ - **Zero falso positivo crítico**: o AC-2 é a prova de fogo. A auditoria manual acusou 11 comandos,
103
+ e 7 eram legítimos. Um `docs-commands` ingênuo teria "corrigido" a documentação de onboarding
104
+ inteira — pior que não ter check nenhum.
105
+ - **Compatibilidade**: aditivo. Nenhum comando existente muda de contrato.
106
+
107
+ ## 7. Riscos e mitigação
108
+
109
+ | Risco | Probabilidade | Impacto | Mitigação |
110
+ |---|---|---|---|
111
+ | Falso positivo com comandos do projeto gerado | **A** | A | AC-2: allowlist **derivada** dos geradores, nunca manual. Já observado: 7 de 11 |
112
+ | Regex casa comando dentro de bloco de exemplo hipotético | M | M | Só `npm run x` / `forja x` em bloco de código. Prosa não conta |
113
+ | `commands-documented` vira ruído a cada comando novo | M | B | É `warn`. E documentar comando novo é o comportamento desejado |
114
+ | O gate engessa a doc e desestimula escrever | B | M | Ele só cobra referências a **código**; prosa é livre |
115
+
116
+ ## 8. Métricas de sucesso
117
+
118
+ - **Zero** comandos fantasma na documentação, verificado a cada CI — em vez de a cada auditoria
119
+ manual que alguém lembrar de fazer.
120
+ - Renomear um comando passa a **quebrar o CI** enquanto a doc não acompanhar. Hoje renomear é grátis
121
+ e a doc apodrece calada.
122
+ - Os 42 comandos do registry passam a ter, cada um, ao menos um lugar onde o sistema explica o que
123
+ ele faz. Nenhum step obscuro.