forjajs 2.0.4 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (798) hide show
  1. package/.claude/agents/context-engineer.md +25 -25
  2. package/.claude/agents/governance.md +55 -55
  3. package/.claude/agents/marketing.md +24 -24
  4. package/.claude/agents/orchestrator.md +31 -31
  5. package/.claude/agents/product.md +26 -26
  6. package/.claude/agents/release-auditor.md +50 -50
  7. package/.claude/agents/sdd-architect.md +34 -34
  8. package/.claude/settings.json +76 -76
  9. package/.claude/skills/new-adr/SKILL.md +61 -61
  10. package/.claude/skills/new-command/SKILL.md +67 -67
  11. package/.gemini-instructions.md +87 -87
  12. package/.github/copilot-instructions.md +87 -87
  13. package/.memoryrc.json +104 -104
  14. package/.openai-instructions.md +87 -87
  15. package/AGENTS.md +133 -133
  16. package/CHANGELOG.md +619 -555
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +64 -60
  19. package/LICENSE +21 -21
  20. package/README.md +404 -343
  21. package/README.pt-BR.md +374 -345
  22. package/boilerplates/01-api-rest/README.md +336 -336
  23. package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
  24. package/boilerplates/02-saas-starter/.env.example +25 -25
  25. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
  26. package/boilerplates/02-saas-starter/INFO.md +252 -252
  27. package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
  28. package/boilerplates/02-saas-starter/README.md +305 -305
  29. package/boilerplates/02-saas-starter/START-HERE.md +259 -259
  30. package/boilerplates/02-saas-starter/backend/package.json +87 -87
  31. package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
  32. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
  33. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
  34. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
  35. package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
  36. package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
  37. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
  38. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
  39. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
  40. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
  41. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
  42. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
  43. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
  44. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
  45. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
  46. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
  47. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
  48. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
  49. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
  50. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
  51. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
  52. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
  53. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
  54. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
  55. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
  56. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
  57. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
  58. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
  59. package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
  60. package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
  61. package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
  62. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
  63. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
  64. package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
  65. package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
  66. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
  67. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
  68. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
  69. package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
  70. package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
  71. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
  72. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
  73. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
  74. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
  75. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
  76. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
  77. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
  78. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
  79. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
  80. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
  81. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
  82. package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
  83. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
  84. package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
  85. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
  86. package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
  87. package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
  88. package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
  89. package/boilerplates/03-ecommerce-starter/README.md +465 -465
  90. package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
  91. package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
  92. package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
  93. package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
  94. package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
  95. package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
  96. package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
  97. package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
  98. package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
  99. package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
  100. package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
  101. package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
  102. package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
  103. package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
  104. package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
  105. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
  106. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
  107. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
  108. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
  109. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
  110. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
  111. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
  112. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
  113. package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
  114. package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
  115. package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
  116. package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
  117. package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
  118. package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
  119. package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
  120. package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
  121. package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
  122. package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
  123. package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
  124. package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
  125. package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
  126. package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
  127. package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
  128. package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
  129. package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
  130. package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
  131. package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
  132. package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
  133. package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
  134. package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
  135. package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
  136. package/boilerplates/04-microservices-starter/.env.example +43 -43
  137. package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
  138. package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
  139. package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
  140. package/boilerplates/04-microservices-starter/INDEX.md +377 -377
  141. package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
  142. package/boilerplates/04-microservices-starter/README.md +466 -466
  143. package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
  144. package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
  145. package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
  146. package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
  147. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
  148. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
  149. package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
  150. package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
  151. package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
  152. package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
  153. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
  154. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
  155. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
  156. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
  157. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
  158. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
  159. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
  160. package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
  161. package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
  162. package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
  163. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
  164. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
  165. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
  166. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
  167. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
  168. package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
  169. package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
  170. package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
  171. package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
  172. package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
  173. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
  174. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
  175. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
  176. package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
  177. package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
  178. package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
  179. package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
  180. package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
  181. package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
  182. package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
  183. package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
  184. package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
  185. package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
  186. package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
  187. package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
  188. package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
  189. package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
  190. package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
  191. package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
  192. package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
  193. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
  194. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
  195. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
  196. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
  197. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
  198. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
  199. package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
  200. package/boilerplates/04-microservices-starter/package.json +21 -21
  201. package/boilerplates/05-monorepo-starter/.env.example +1 -1
  202. package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
  203. package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
  204. package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
  205. package/boilerplates/05-monorepo-starter/README.md +318 -318
  206. package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
  207. package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
  208. package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
  209. package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
  210. package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
  211. package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
  212. package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
  213. package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
  214. package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
  215. package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
  216. package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
  217. package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
  218. package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
  219. package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
  220. package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
  221. package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
  222. package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
  223. package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
  224. package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
  225. package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
  226. package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
  227. package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
  228. package/boilerplates/05-monorepo-starter/package.json +30 -30
  229. package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
  230. package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
  231. package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
  232. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
  233. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
  234. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
  235. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
  236. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
  237. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
  238. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
  239. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
  240. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
  241. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
  242. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
  243. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
  244. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
  245. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
  246. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
  247. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
  248. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
  249. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
  250. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
  251. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
  252. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
  253. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
  254. package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
  255. package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
  256. package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
  257. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
  258. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
  259. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
  260. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
  261. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
  262. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
  263. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
  264. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
  265. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
  266. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
  267. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
  268. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
  269. package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
  270. package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
  271. package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
  272. package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
  273. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
  274. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
  275. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
  276. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
  277. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
  278. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
  279. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
  280. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
  281. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
  282. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
  283. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
  284. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
  285. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
  286. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
  287. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
  288. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
  289. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
  290. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
  291. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
  292. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
  293. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
  294. package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
  295. package/boilerplates/05-monorepo-starter/turbo.json +35 -35
  296. package/boilerplates/06-clean-arch/README.md +48 -48
  297. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
  298. package/boilerplates/06-clean-arch/backend/package.json +43 -43
  299. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
  300. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
  301. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
  302. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
  303. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
  304. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
  305. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
  306. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
  307. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
  308. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
  309. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
  310. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
  311. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
  312. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
  313. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
  314. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
  315. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
  316. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
  317. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
  318. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
  319. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
  320. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
  321. package/boilerplates/README.md +427 -427
  322. package/design-md/BRIEF-TEMPLATE.md +47 -47
  323. package/design-md/INDEX.md +35 -35
  324. package/design-md/MATRIX.md +24 -24
  325. package/design-md/PLAYBOOK.md +35 -35
  326. package/design-md/examples/agent-console-brief.md +48 -48
  327. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  328. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  329. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  330. package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
  331. package/dist/apps/server/src/forja-nest.module.js +9 -4
  332. package/dist/apps/server/src/main.js +10 -1
  333. package/dist/bin/create-memory-nest-kit.js +17 -17
  334. package/dist/bin/init-project.js +38 -38
  335. package/dist/lib/audit.js +7 -7
  336. package/dist/lib/code-context.js +6 -0
  337. package/dist/lib/context-builder.js +32 -32
  338. package/dist/lib/core/architecture-gate.d.ts +20 -0
  339. package/dist/lib/core/architecture-gate.js +60 -0
  340. package/dist/lib/core/drift-gate.d.ts +18 -0
  341. package/dist/lib/core/drift-gate.js +55 -0
  342. package/dist/lib/core/gates.d.ts +9 -2
  343. package/dist/lib/core/gates.js +13 -2
  344. package/dist/lib/core/health.js +15 -0
  345. package/dist/lib/core/incident-search.d.ts +19 -0
  346. package/dist/lib/core/incident-search.js +32 -0
  347. package/dist/lib/core/model-pricing.d.ts +31 -0
  348. package/dist/lib/core/model-pricing.js +74 -0
  349. package/dist/lib/core/registry.d.ts +194 -0
  350. package/dist/lib/core/registry.js +194 -0
  351. package/dist/lib/core/release.d.ts +194 -0
  352. package/dist/lib/core/risk-collect.d.ts +19 -0
  353. package/dist/lib/core/risk-collect.js +173 -0
  354. package/dist/lib/drift-sentinel.d.ts +59 -0
  355. package/dist/lib/drift-sentinel.js +126 -0
  356. package/dist/lib/generators/memory-generator.js +691 -691
  357. package/dist/lib/generators/nest-generator.js +412 -398
  358. package/dist/lib/generators/readme-generator.js +180 -180
  359. package/dist/lib/governance-report.js +39 -39
  360. package/dist/lib/workspace.js +29 -29
  361. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  362. package/dist/packages/adapter-git/src/index.js +11 -6
  363. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  364. package/dist/packages/adapter-nest/src/index.js +26 -1
  365. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  366. package/dist/packages/adapter-sqlite/src/index.js +61 -12
  367. package/dist/packages/contracts/src/index.d.ts +33 -0
  368. package/dist/packages/contracts/src/index.js +13 -0
  369. package/dist/packages/core/src/index.d.ts +12 -0
  370. package/dist/packages/core/src/index.js +29 -0
  371. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  372. package/dist/packages/engineering/architecture/src/index.js +131 -0
  373. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  374. package/dist/packages/engineering/evidence/src/index.js +31 -0
  375. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  376. package/dist/packages/engineering/identity/src/index.js +88 -0
  377. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  378. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  379. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  380. package/dist/packages/engineering/provenance/src/index.js +21 -0
  381. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  382. package/dist/packages/engineering/risk/src/index.js +120 -0
  383. package/dist/packages/graph/src/index.d.ts +23 -1
  384. package/dist/packages/graph/src/index.js +88 -15
  385. package/dist/packages/llm/src/index.js +27 -4
  386. package/dist/packages/mcp/src/index.js +27 -8
  387. package/dist/packages/orchestration/src/index.d.ts +11 -1
  388. package/dist/packages/orchestration/src/index.js +34 -7
  389. package/dist/packages/policy/src/index.d.ts +40 -0
  390. package/dist/packages/policy/src/index.js +39 -4
  391. package/dist/packages/runtime/src/index.js +3 -0
  392. package/dist/packages/sandbox/src/index.d.ts +47 -0
  393. package/dist/packages/sandbox/src/index.js +59 -0
  394. package/dist/packages/validator/src/index.d.ts +8 -0
  395. package/dist/packages/validator/src/index.js +21 -6
  396. package/dist/scripts/adr.d.ts +17 -0
  397. package/dist/scripts/adr.js +152 -0
  398. package/dist/scripts/agent-harness.js +72 -64
  399. package/dist/scripts/agent-router.js +20 -20
  400. package/dist/scripts/agent.d.ts +27 -0
  401. package/dist/scripts/agent.js +249 -0
  402. package/dist/scripts/architecture.d.ts +16 -0
  403. package/dist/scripts/architecture.js +186 -0
  404. package/dist/scripts/build-smart-context.js +22 -22
  405. package/dist/scripts/compress-memory.js +8 -8
  406. package/dist/scripts/context-ops.js +29 -29
  407. package/dist/scripts/cost-economy.d.ts +2 -0
  408. package/dist/scripts/cost-economy.js +79 -0
  409. package/dist/scripts/demo-autonomy.js +13 -6
  410. package/dist/scripts/dev.js +13 -13
  411. package/dist/scripts/drift-check.d.ts +17 -0
  412. package/dist/scripts/drift-check.js +63 -0
  413. package/dist/scripts/engineer.d.ts +20 -0
  414. package/dist/scripts/engineer.js +208 -0
  415. package/dist/scripts/evidence.d.ts +12 -0
  416. package/dist/scripts/evidence.js +55 -0
  417. package/dist/scripts/extract-global-knowledge.js +5 -5
  418. package/dist/scripts/gates.d.ts +6 -2
  419. package/dist/scripts/gates.js +14 -4
  420. package/dist/scripts/generate-dashboard.js +11 -11
  421. package/dist/scripts/incident.d.ts +19 -0
  422. package/dist/scripts/incident.js +103 -0
  423. package/dist/scripts/llm-fit.js +32 -3
  424. package/dist/scripts/memory-schema.js +48 -48
  425. package/dist/scripts/provenance.d.ts +14 -0
  426. package/dist/scripts/provenance.js +114 -0
  427. package/dist/scripts/query-universal-memory.js +13 -13
  428. package/dist/scripts/risk.d.ts +15 -0
  429. package/dist/scripts/risk.js +81 -0
  430. package/dist/scripts/simulate.d.ts +20 -0
  431. package/dist/scripts/simulate.js +150 -0
  432. package/dist/scripts/sprint-manager.js +39 -39
  433. package/dist/scripts/sync-universal-memory.js +44 -44
  434. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  435. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  436. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  437. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  438. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  439. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  440. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  441. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  442. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  443. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  444. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  445. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  446. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  447. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  448. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  449. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  450. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  451. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  452. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  453. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  454. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  455. package/docs/agent-harnesses.md +149 -149
  456. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  457. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  458. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  459. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  460. package/docs/archive/FASE2-SUMMARY.md +263 -263
  461. package/docs/archive/FASE3-PROGRESS.md +355 -355
  462. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  463. package/docs/archive/INDICE-MASTER.md +282 -282
  464. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  465. package/docs/archive/README-REFINAMENTO.md +293 -293
  466. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  467. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  468. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  469. package/docs/archive/START-HERE.md +319 -319
  470. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  471. package/docs/archive/examples/v1/AGENTS.md +10 -10
  472. package/docs/archive/examples/v1/README.md +36 -36
  473. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  474. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  475. package/docs/archive/examples/v1/backend/package.json +42 -42
  476. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  477. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  478. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  479. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  480. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  481. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  482. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  483. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  484. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  485. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  486. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  487. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  488. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  489. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  490. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  491. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  492. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  493. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  494. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  495. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  496. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  497. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  498. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  499. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  500. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  501. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  502. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  503. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  504. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  505. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  506. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  507. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  508. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  509. package/docs/archive/examples/v2/AGENTS.md +16 -16
  510. package/docs/archive/examples/v2/README.md +35 -35
  511. package/docs/archive/examples/v2/agents/README.md +3 -3
  512. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  513. package/docs/archive/examples/v2/agents/dba.md +4 -4
  514. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  515. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  516. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  517. package/docs/archive/examples/v2/agents/security.md +4 -4
  518. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  519. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  520. package/docs/archive/examples/v2/backend/package.json +42 -42
  521. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  522. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  523. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  524. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  525. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  526. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  527. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  528. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  529. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  530. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  531. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  532. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  533. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  534. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  535. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  536. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  537. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  538. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  539. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  540. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  541. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  542. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  543. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  544. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  545. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  546. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  547. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  548. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  549. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  550. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  551. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  552. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  553. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  554. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  555. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  556. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  557. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  558. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  559. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  560. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  561. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  562. package/docs/archive/examples/v2/memory/README.md +8 -8
  563. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  564. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  565. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  566. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  567. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  568. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  569. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  570. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  571. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  572. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  573. package/docs/capacidades-externas.md +86 -86
  574. package/docs/cli-first-operacao.md +74 -74
  575. package/docs/dev-workflow.md +421 -421
  576. package/docs/examples.md +546 -546
  577. package/docs/fluxo.md +103 -103
  578. package/docs/glossary.md +453 -453
  579. package/docs/init-project.md +457 -457
  580. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  581. package/docs/personas/architect/README.md +333 -333
  582. package/docs/personas/developer/README.md +371 -371
  583. package/docs/personas/executive/README.md +172 -172
  584. package/docs/personas/qa/README.md +350 -350
  585. package/docs/processo-projeto.md +138 -138
  586. package/docs/publishing.md +377 -377
  587. package/docs/quick-reference.md +409 -409
  588. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  589. package/docs/structure.md +360 -360
  590. package/docs/token-optimization.md +502 -502
  591. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  592. package/memory/00-global/mission.md +15 -15
  593. package/memory/00-global/shared-knowledge.md +8 -8
  594. package/memory/00-global/standards.md +47 -47
  595. package/memory/10-product/personas.md +21 -21
  596. package/memory/10-product/vision.md +27 -27
  597. package/memory/30-projects/README.md +15 -15
  598. package/memory/40-delivery/backlog.md +15 -15
  599. package/memory/40-delivery/current-sprint.md +20 -20
  600. package/memory/50-orchestration/gsd-harness.md +55 -55
  601. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  602. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  603. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  604. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  605. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  606. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  607. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  608. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  609. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  610. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  611. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  612. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  613. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  614. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  615. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  616. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  617. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  618. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  619. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  620. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  621. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  622. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  623. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  624. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  625. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  626. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  627. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  628. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  629. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  630. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  631. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  632. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  633. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  634. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  635. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  636. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  637. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  638. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  639. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  640. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  641. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  642. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  643. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  644. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  645. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  646. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  647. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  648. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  649. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  650. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  651. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  652. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  653. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  654. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  655. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  656. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  657. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  658. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  659. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  660. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  661. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  662. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  663. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  664. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  665. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  666. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  667. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  668. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  669. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  670. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  671. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  672. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  673. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  674. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  675. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  676. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  677. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  678. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  679. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  680. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  681. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  682. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  683. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  684. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  685. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  686. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  687. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  688. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  689. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  690. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  691. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  692. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  693. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  694. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  695. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  696. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  697. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  698. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  699. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  700. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  701. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  702. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  703. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  704. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  705. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  706. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  707. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  708. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  709. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  710. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  711. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  712. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  713. package/memory/90-decisions/_template.md +28 -28
  714. package/package.json +157 -157
  715. package/prompts/context-engineer-agent.md +19 -19
  716. package/prompts/governance-agent.md +16 -16
  717. package/prompts/marketing-agent.md +13 -13
  718. package/prompts/orchestrator-agent.md +18 -18
  719. package/prompts/product-agent.md +13 -13
  720. package/prompts/sdd-architect-agent.md +20 -20
  721. package/specs/README.md +70 -70
  722. package/specs/_templates/plan.md +43 -43
  723. package/specs/_templates/spec.md +43 -43
  724. package/specs/_templates/tasks.md +32 -32
  725. package/specs/agent-identity-reputation/plan.md +133 -0
  726. package/specs/agent-identity-reputation/spec.md +125 -0
  727. package/specs/agent-identity-reputation/tasks.md +51 -0
  728. package/specs/agent-runtime-monitoring/plan.md +78 -0
  729. package/specs/agent-runtime-monitoring/spec.md +92 -0
  730. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  731. package/specs/ai-code-provenance/plan.md +71 -0
  732. package/specs/ai-code-provenance/spec.md +97 -0
  733. package/specs/ai-code-provenance/tasks.md +39 -0
  734. package/specs/architecture-constitution/plan.md +110 -0
  735. package/specs/architecture-constitution/spec.md +114 -0
  736. package/specs/architecture-constitution/tasks.md +58 -0
  737. package/specs/change-risk-engine/plan.md +130 -0
  738. package/specs/change-risk-engine/spec.md +119 -0
  739. package/specs/change-risk-engine/tasks.md +72 -0
  740. package/specs/clean-arch-boilerplate/plan.md +137 -137
  741. package/specs/clean-arch-boilerplate/spec.md +121 -121
  742. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  743. package/specs/cli-first-operacao/plan.md +53 -53
  744. package/specs/cli-first-operacao/spec.md +53 -53
  745. package/specs/cli-first-operacao/tasks.md +53 -53
  746. package/specs/code-context/spec.md +56 -56
  747. package/specs/coerencia-do-sistema/plan.md +155 -155
  748. package/specs/coerencia-do-sistema/spec.md +123 -123
  749. package/specs/coerencia-do-sistema/tasks.md +115 -115
  750. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  751. package/specs/dev-token-assets-db/plan.md +71 -71
  752. package/specs/dev-token-assets-db/spec.md +58 -58
  753. package/specs/dev-token-assets-db/tasks.md +58 -58
  754. package/specs/doctor-do-nucleo/plan.md +165 -165
  755. package/specs/doctor-do-nucleo/spec.md +139 -139
  756. package/specs/doctor-do-nucleo/tasks.md +172 -172
  757. package/specs/drift-sentinel/spec.md +117 -0
  758. package/specs/engineer-facade-extension/plan.md +71 -0
  759. package/specs/engineer-facade-extension/spec.md +98 -0
  760. package/specs/engineer-facade-extension/tasks.md +36 -0
  761. package/specs/engineering-evidence-ledger/plan.md +121 -0
  762. package/specs/engineering-evidence-ledger/spec.md +90 -0
  763. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  764. package/specs/engineering-graph-extensions/plan.md +92 -0
  765. package/specs/engineering-graph-extensions/spec.md +101 -0
  766. package/specs/engineering-graph-extensions/tasks.md +60 -0
  767. package/specs/engineering-intelligence/spec.md +177 -0
  768. package/specs/forja-core/spec.md +71 -71
  769. package/specs/gates/spec.md +63 -63
  770. package/specs/governanca-visivel/plan.md +122 -122
  771. package/specs/governanca-visivel/spec.md +112 -112
  772. package/specs/governanca-visivel/tasks.md +60 -60
  773. package/specs/harness-codegraph/spec.md +71 -71
  774. package/specs/learning-loop-incidents/plan.md +59 -0
  775. package/specs/learning-loop-incidents/spec.md +93 -0
  776. package/specs/learning-loop-incidents/tasks.md +36 -0
  777. package/specs/memory-audit/spec.md +54 -54
  778. package/specs/orchestrate/spec.md +108 -108
  779. package/specs/orchestration-coherent/spec.md +95 -95
  780. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  781. package/specs/predictive-change-simulation/plan.md +109 -0
  782. package/specs/predictive-change-simulation/spec.md +107 -0
  783. package/specs/predictive-change-simulation/tasks.md +41 -0
  784. package/specs/project-smoke/spec.md +96 -96
  785. package/specs/project-upgrade/spec.md +58 -58
  786. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  787. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  788. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  789. package/specs/release-auditor-health/spec.md +23 -23
  790. package/specs/release-gate/plan.md +174 -174
  791. package/specs/release-gate/spec.md +122 -122
  792. package/specs/release-gate/tasks.md +183 -183
  793. package/specs/smart-agent-routing/plan.md +55 -0
  794. package/specs/smart-agent-routing/spec.md +85 -0
  795. package/specs/smart-agent-routing/tasks.md +26 -0
  796. package/specs/ts-migration/plan.md +200 -200
  797. package/specs/ts-migration/spec.md +119 -119
  798. package/specs/ts-migration/tasks.md +110 -110
@@ -6,6 +6,16 @@ export class GraphError extends Error {
6
6
  this.name = 'GraphError';
7
7
  }
8
8
  }
9
+ /**
10
+ * Evidence sources allowed to claim `status: 'verified'` directly. Without this, any caller —
11
+ * including an LLM/agent whose output feeds `addEvidence`/`upsertEdge` — could write
12
+ * `status: 'verified'` on a bare assertion and GraphLoop would store it as indistinguishable
13
+ * from a fact derived by the deterministic extractor or a real sandboxed execution. Anything
14
+ * outside this allowlist is clamped to `'inferred'` (see `addEvidence`/`upsertEdge`) instead of
15
+ * being rejected, so the graph stays usable for genuinely uncertain input — it just can't be
16
+ * mislabeled as verified.
17
+ */
18
+ const DEFAULT_TRUSTED_EVIDENCE_SOURCES = ['deterministic-extractor', 'sandbox', 'forja.graph', 'forja.cli'];
9
19
  export class InMemoryGraphStore {
10
20
  nodes = new Map();
11
21
  edges = new Map();
@@ -24,17 +34,28 @@ export class InMemoryGraphStore {
24
34
  }
25
35
  export class GraphLoop {
26
36
  store;
27
- constructor(store = new InMemoryGraphStore()) {
37
+ trustedEvidenceSources;
38
+ constructor(store = new InMemoryGraphStore(), options = {}) {
28
39
  this.store = store;
40
+ this.trustedEvidenceSources = options.trustedEvidenceSources ?? DEFAULT_TRUSTED_EVIDENCE_SOURCES;
41
+ }
42
+ isTrustedSource(source) {
43
+ return this.trustedEvidenceSources.some((prefix) => source === prefix || source.startsWith(`${prefix}.`));
29
44
  }
30
45
  addEvidence(item) {
31
- this.store.saveEvidence(item);
46
+ const stored = item.status === 'verified' && !this.isTrustedSource(item.source) ? { ...item, status: 'inferred' } : item;
47
+ this.store.saveEvidence(stored);
32
48
  }
33
49
  upsertNode(spec) {
34
50
  if (spec.id.trim().length === 0 || spec.type.trim().length === 0 || spec.label.trim().length === 0)
35
51
  throw new GraphError('Graph node id, type and label are required');
36
52
  const current = this.store.getNode(spec.id);
37
- const node = { ...this.auditFields(current?.correlationId ?? `node:${spec.id}`), ...spec };
53
+ // `documentStatus` specifically survives an update that doesn't mention it: a document that
54
+ // only references this node in passing (e.g. "see ADR-0020") doesn't know that ADR's real
55
+ // status, and re-indexing it after the ADR's own file shouldn't erase what the ADR's own file
56
+ // already established — see extractDeterministicRelations' "Self-status" comment.
57
+ const documentStatus = spec.documentStatus ?? current?.documentStatus;
58
+ const node = { ...this.auditFields(current?.correlationId ?? `node:${spec.id}`), ...spec, ...(documentStatus === undefined ? {} : { documentStatus }) };
38
59
  this.store.saveNode(node);
39
60
  return node;
40
61
  }
@@ -43,14 +64,21 @@ export class GraphLoop {
43
64
  throw new GraphError('Graph edge endpoints must exist');
44
65
  if (spec.evidenceIds.length === 0)
45
66
  throw new GraphError('Graph edge requires at least one evidence id');
46
- for (const id of spec.evidenceIds)
47
- if (this.store.getEvidence(id) === undefined)
67
+ const referencedEvidence = [];
68
+ for (const id of spec.evidenceIds) {
69
+ const item = this.store.getEvidence(id);
70
+ if (item === undefined)
48
71
  throw new GraphError(`Graph edge evidence not found: ${id}`);
72
+ referencedEvidence.push(item);
73
+ }
49
74
  if (!Number.isFinite(spec.confidence) || spec.confidence < 0 || spec.confidence > 1)
50
75
  throw new GraphError('Graph edge confidence must be between 0 and 1');
76
+ // An edge can't be more verified than the evidence it rests on — otherwise 'verified' becomes
77
+ // a label the edge asserts about itself, exactly the self-declared-truth gap this guards.
78
+ const status = spec.status === 'verified' && !referencedEvidence.every((item) => item.status === 'verified') ? 'inferred' : spec.status;
51
79
  const key = this.edgeKey(spec);
52
80
  const current = this.store.getEdge(key);
53
- const edge = { ...this.auditFields(current?.correlationId ?? `edge:${key}`), ...spec, id: current?.id ?? spec.id ?? randomUUID() };
81
+ const edge = { ...this.auditFields(current?.correlationId ?? `edge:${key}`), ...spec, status, id: current?.id ?? spec.id ?? randomUUID() };
54
82
  this.store.saveEdge(key, edge);
55
83
  return edge;
56
84
  }
@@ -66,6 +94,15 @@ export class GraphLoop {
66
94
  this.store.saveSourceChecksum(mutation.sourceKey, mutation.sourceChecksum);
67
95
  return { nodes: mutation.nodes.length, edges: mutation.edges.length, skipped: false };
68
96
  }
97
+ /**
98
+ * Agrupa `fn` numa transação do `store`, se ele suportar uma (`GraphStore.transaction`,
99
+ * opcional). `GraphIndexer.sync` usa isto pra envolver o loop inteiro de `apply()` — uma
100
+ * transação pra todos os documentos, não uma implícita por `INSERT`. Sem suporte do store
101
+ * (ex. `InMemoryGraphStore`), só roda `fn()` normalmente.
102
+ */
103
+ transaction(fn) {
104
+ return this.store.transaction ? this.store.transaction(fn) : fn();
105
+ }
69
106
  query(query = {}) {
70
107
  return [...this.store.listNodes()]
71
108
  .filter((node) => query.type === undefined || node.type === query.type)
@@ -193,16 +230,21 @@ export class GraphIndexer {
193
230
  let skipped = 0;
194
231
  let nodes = 0;
195
232
  let edges = 0;
196
- for (const document of documents) {
197
- const result = this.graph.apply(extractDeterministicRelations(document));
198
- if (result.skipped)
199
- skipped += 1;
200
- else {
201
- indexed += 1;
202
- nodes += result.nodes;
203
- edges += result.edges;
233
+ // `GraphLoop.transaction` (achado real de performance): sem isto, cada apply() de cada
234
+ // documento fazia seus INSERTs num commit implícito próprio — dezenas de milhares de fsyncs
235
+ // pra um repositório de ~1000 arquivos. Uma transação pro sync inteiro, não uma por linha.
236
+ this.graph.transaction(() => {
237
+ for (const document of documents) {
238
+ const result = this.graph.apply(extractDeterministicRelations(document));
239
+ if (result.skipped)
240
+ skipped += 1;
241
+ else {
242
+ indexed += 1;
243
+ nodes += result.nodes;
244
+ edges += result.edges;
245
+ }
204
246
  }
205
- }
247
+ });
206
248
  return { documents: documents.length, indexed, skipped, nodes, edges, durationMs: Date.now() - started, files: documents.map((document) => document.locator) };
207
249
  }
208
250
  }
@@ -238,6 +280,9 @@ export function extractDeterministicRelations(document) {
238
280
  const adrMatches = line.match(/\bADR-\d{4}\b/g) ?? [];
239
281
  for (const adr of adrMatches)
240
282
  addRelation(adr, 'DERIVED_FROM', index + 1, 'ADR');
283
+ const specMatches = line.match(/\bSPEC-\d{3,4}\b/g) ?? [];
284
+ for (const spec of specMatches)
285
+ addRelation(spec, 'DERIVED_FROM', index + 1, 'SPEC');
241
286
  const taskMatch = line.match(/^\s*-\s*\[[ xX]\]\s+(.+)$/);
242
287
  if (taskMatch?.[1] !== undefined)
243
288
  addRelation(taskMatch[1], 'CONTAINS', index + 1, 'Task');
@@ -254,6 +299,34 @@ export function extractDeterministicRelations(document) {
254
299
  addRelation(name, 'CALLS', index + 1, 'Symbol');
255
300
  }
256
301
  });
302
+ // Self-status: when `document` IS an ADR or a spec.md (not just mentioning one in passing),
303
+ // attach the document's own `- **Status**: <value>` line to the ADR/SPEC node it represents —
304
+ // via the `nodes` map, not a direct `upsertNode` call, since this function stays pure/stateless
305
+ // (packages/graph SPEC-032 §5). A later `apply()` of some OTHER document that only references
306
+ // this same ADR/SPEC in passing won't know its status and won't include `documentStatus` in its
307
+ // own spec — `GraphLoop.upsertNode` preserves the previous value in that case rather than wiping
308
+ // it, so processing order across the corpus can't flip a real status back to unknown.
309
+ const adrSelfMatch = /^memory\/90-decisions\/(\d{4})-/.exec(document.locator);
310
+ const specSelfMatch = /^specs\/[^/]+\/spec\.md$/.test(document.locator);
311
+ if (adrSelfMatch || specSelfMatch) {
312
+ const statusMatch = /^-\s*\*\*Status\*\*:\s*(\S[^\n]*?)\s*$/m.exec(document.content);
313
+ const documentStatus = statusMatch?.[1];
314
+ if (documentStatus !== undefined) {
315
+ const label = adrSelfMatch ? `ADR-${adrSelfMatch[1]}` : /^-\s*\*\*ID\*\*:\s*(SPEC-\d{3,4})\s*$/m.exec(document.content)?.[1];
316
+ const type = adrSelfMatch ? 'ADR' : 'SPEC';
317
+ if (label !== undefined) {
318
+ // `addRelation` keys a node by `${relationType}:${label}` (e.g. `DERIVED_FROM:ADR-0041`),
319
+ // not `${nodeType}:${label}` — an existing quirk of this function, not something to change
320
+ // here. Reuse whatever id the self-reference already produced (present whenever the
321
+ // document's own text repeats its own ADR/SPEC id, which it always does per the template)
322
+ // instead of guessing that scheme, so this stays correct even if the keying convention
323
+ // changes later.
324
+ const existingEntry = [...nodes.entries()].find(([, node]) => node.type === type && node.label === label);
325
+ const targetId = existingEntry?.[0] ?? stableId(`DERIVED_FROM:${label}`);
326
+ nodes.set(targetId, { id: targetId, type, label, status: 'verified', documentStatus, ...(existingEntry?.[1].validFrom !== undefined ? { validFrom: existingEntry[1].validFrom } : {}) });
327
+ }
328
+ }
329
+ }
257
330
  if (document.locator.endsWith('package.json')) {
258
331
  try {
259
332
  const manifest = JSON.parse(document.content);
@@ -38,6 +38,8 @@ export function buildLlmExecution(profile, prompt) {
38
38
  return { executable: profile.command, args: [...base, 'copilot', 'suggest', '-t', 'shell', prompt] };
39
39
  return { executable: profile.command, args: [...base, prompt] };
40
40
  }
41
+ /** Grace period after SIGTERM before a timed-out LLM subprocess (and anything it spawned) gets SIGKILLed. */
42
+ const SIGTERM_GRACE_MS = 3_000;
41
43
  export async function runLlm(execution, cwd, timeoutMs = 120_000) {
42
44
  const started = Date.now();
43
45
  return new Promise((resolve) => {
@@ -50,14 +52,35 @@ export async function runLlm(execution, cwd, timeoutMs = 120_000) {
50
52
  settled = true;
51
53
  resolve({ ...result, durationMs: Date.now() - started });
52
54
  };
53
- const child = spawn(execution.executable, execution.args, { cwd, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
55
+ // detached so the child leads its own process group: a negative pid targets the whole group,
56
+ // reaching grandchildren the CLI tool itself spawned (not just the immediate child).
57
+ const child = spawn(execution.executable, execution.args, { cwd, shell: false, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
54
58
  child.stdout.setEncoding('utf8');
55
59
  child.stderr.setEncoding('utf8');
56
60
  child.stdout.on('data', (chunk) => { stdout += chunk; });
57
61
  child.stderr.on('data', (chunk) => { stderr += chunk; });
58
- const timer = setTimeout(() => { child.kill(); finish({ exitCode: 124, stdout, stderr, errorCode: 'TIMEOUT' }); }, timeoutMs);
59
- child.on('error', (error) => { clearTimeout(timer); finish({ exitCode: 127, stdout, stderr: `${stderr}${error.message}`, errorCode: 'SPAWN_FAILED' }); });
60
- child.on('close', (code) => { clearTimeout(timer); finish({ exitCode: code ?? 1, stdout, stderr, ...(code === 0 ? {} : { errorCode: 'COMMAND_FAILED' }) }); });
62
+ const killGroup = (signal) => {
63
+ if (child.pid === undefined)
64
+ return;
65
+ try {
66
+ process.kill(-child.pid, signal);
67
+ }
68
+ catch {
69
+ // no process group (platform didn't support detached, or it's already gone) — fall back to the child alone
70
+ try {
71
+ child.kill(signal);
72
+ }
73
+ catch { /* already dead */ }
74
+ }
75
+ };
76
+ let killTimer;
77
+ const timer = setTimeout(() => {
78
+ killGroup('SIGTERM');
79
+ killTimer = setTimeout(() => killGroup('SIGKILL'), SIGTERM_GRACE_MS);
80
+ finish({ exitCode: 124, stdout, stderr, errorCode: 'TIMEOUT' });
81
+ }, timeoutMs);
82
+ child.on('error', (error) => { clearTimeout(timer); clearTimeout(killTimer); finish({ exitCode: 127, stdout, stderr: `${stderr}${error.message}`, errorCode: 'SPAWN_FAILED' }); });
83
+ child.on('close', (code) => { clearTimeout(timer); clearTimeout(killTimer); finish({ exitCode: code ?? 1, stdout, stderr, ...(code === 0 ? {} : { errorCode: 'COMMAND_FAILED' }) }); });
61
84
  });
62
85
  }
63
86
  export function recommendProfile(profiles, observations, role, taskType, privacy) {
@@ -83,15 +83,34 @@ export class McpServer {
83
83
  case 'forja_capabilities_list': return this.dependencies.registry.list({ agent: this.dependencies.agent, policy: this.dependencies.policy });
84
84
  case 'forja_capability_describe': return this.dependencies.registry.describe(this.string(input, 'capabilityId'), { agent: this.dependencies.agent, policy: this.dependencies.policy });
85
85
  case 'forja_capability_execute': return this.executeCapability(input);
86
- case 'forja_context_build': return this.requireContext().build(this.contextRequest(input));
87
- case 'forja_memory_query': return this.requireMemory().query(this.string(input, 'objective'));
88
- case 'forja_graph_query': return this.requireGraph().query(this.graphQuery(input));
89
- case 'forja_code_impact': return this.requireGraph().impact(this.entity(input, 'origin'), this.number(input, 'depth', 2), this.direction(input));
90
- case 'forja_task_next': return this.requireTasks().next(this.entity(input, 'sprintId'));
86
+ // read-only queries: low-risk read gate — same authorize() surface as forja_handoff_create, scoped down
87
+ case 'forja_context_build':
88
+ this.authorize('forja_context_build', 'read', 'low', []);
89
+ return this.requireContext().build(this.contextRequest(input));
90
+ case 'forja_memory_query':
91
+ this.authorize('forja_memory_query', 'read', 'low', []);
92
+ return this.requireMemory().query(this.string(input, 'objective'));
93
+ case 'forja_graph_query':
94
+ this.authorize('forja_graph_query', 'read', 'low', []);
95
+ return this.requireGraph().query(this.graphQuery(input));
96
+ case 'forja_code_impact':
97
+ this.authorize('forja_code_impact', 'read', 'low', []);
98
+ return this.requireGraph().impact(this.entity(input, 'origin'), this.number(input, 'depth', 2), this.direction(input));
99
+ case 'forja_task_next':
100
+ this.authorize('forja_task_next', 'read', 'low', []);
101
+ return this.requireTasks().next(this.entity(input, 'sprintId'));
91
102
  case 'forja_handoff_create': return this.createHandoff(input);
92
- case 'forja_spec_check': return this.requireSpecChecker().check(input);
93
- case 'forja_test_run': return this.requireTestRunner().run(input);
94
- case 'forja_execution_validate': return this.requireExecutionValidator().validate(input);
103
+ // spec_check/test_run/execution_validate call adapters directly (not through CapabilityRegistry.execute,
104
+ // which has its own policy gate), so this authorize() is their only checkpoint at the MCP surface.
105
+ case 'forja_spec_check':
106
+ this.authorize('forja_spec_check', 'validate', 'low', []);
107
+ return this.requireSpecChecker().check(input);
108
+ case 'forja_test_run':
109
+ this.authorize('forja_test_run', 'execute', 'medium', []);
110
+ return this.requireTestRunner().run(input);
111
+ case 'forja_execution_validate':
112
+ this.authorize('forja_execution_validate', 'validate', 'low', []);
113
+ return this.requireExecutionValidator().validate(input);
95
114
  default:
96
115
  if (name.startsWith('forja_capability_'))
97
116
  return this.executeDynamicCapability(name, input);
@@ -84,6 +84,13 @@ export declare class SprintEngine {
84
84
  attachTask(sprintId: EntityId, taskId: EntityId): Promise<Sprint>;
85
85
  complete(id: EntityId, validator: CompletionValidator): Promise<Sprint>;
86
86
  private transition;
87
+ /**
88
+ * Read-modify-write without this is a lost-update race: two concurrent callers can both read
89
+ * the same `sprint`, compute different `updated` values, and the second `saveSprint` silently
90
+ * clobbers the first. Re-checking `updatedAt` immediately before writing narrows that window to
91
+ * the store's own read/write latency instead of this method's full async body.
92
+ */
93
+ private saveSprintGuarded;
87
94
  private requireSprint;
88
95
  private record;
89
96
  private updated;
@@ -106,6 +113,8 @@ export declare class TaskEngine {
106
113
  start(id: EntityId): Promise<Task>;
107
114
  block(id: EntityId): Promise<Task>;
108
115
  complete(id: EntityId, validator: CompletionValidator): Promise<Task>;
116
+ /** See SprintEngine.saveSprintGuarded — same lost-update race, same narrowing mitigation. */
117
+ private saveTaskGuarded;
109
118
  private require;
110
119
  private updated;
111
120
  private clean;
@@ -116,7 +125,8 @@ export declare class HandoffEngine {
116
125
  private readonly graph?;
117
126
  private readonly maxItems;
118
127
  private readonly maxItemLength;
119
- constructor(store: OrchestrationStore, graph?: GraphRecorder, maxItems?: number, maxItemLength?: number);
128
+ private readonly maxHandoffsPerCorrelation;
129
+ constructor(store: OrchestrationStore, graph?: GraphRecorder, maxItems?: number, maxItemLength?: number, maxHandoffsPerCorrelation?: number);
120
130
  create(input: CreateHandoffInput): Promise<Handoff>;
121
131
  private compact;
122
132
  }
@@ -50,7 +50,7 @@ export class SprintEngine {
50
50
  if (sprint.taskIds.includes(taskId))
51
51
  return sprint;
52
52
  const updated = this.updated(sprint, { taskIds: [...sprint.taskIds, taskId] });
53
- await this.store.saveSprint(updated);
53
+ await this.saveSprintGuarded(sprint, updated);
54
54
  await this.record('sprint', updated.id, [taskId], updated.evidenceIds);
55
55
  return updated;
56
56
  }
@@ -65,7 +65,7 @@ export class SprintEngine {
65
65
  if (result.status !== 'accepted')
66
66
  throw new OrchestrationError(`Sprint validation did not accept completion: ${result.status}`);
67
67
  const updated = this.updated(sprint, { status: 'completed', evidenceIds: this.unique([...sprint.evidenceIds, ...this.evidenceFrom(result)]) });
68
- await this.store.saveSprint(updated);
68
+ await this.saveSprintGuarded(sprint, updated);
69
69
  await this.record('sprint', updated.id, updated.taskIds, updated.evidenceIds);
70
70
  return updated;
71
71
  }
@@ -74,10 +74,22 @@ export class SprintEngine {
74
74
  if (!allowed.includes(sprint.status))
75
75
  throw new OrchestrationError(`Invalid sprint transition from ${sprint.status} to ${status}`);
76
76
  const updated = this.updated(sprint, { status });
77
- await this.store.saveSprint(updated);
77
+ await this.saveSprintGuarded(sprint, updated);
78
78
  await this.record('sprint', updated.id, updated.taskIds, updated.evidenceIds);
79
79
  return updated;
80
80
  }
81
+ /**
82
+ * Read-modify-write without this is a lost-update race: two concurrent callers can both read
83
+ * the same `sprint`, compute different `updated` values, and the second `saveSprint` silently
84
+ * clobbers the first. Re-checking `updatedAt` immediately before writing narrows that window to
85
+ * the store's own read/write latency instead of this method's full async body.
86
+ */
87
+ async saveSprintGuarded(before, after) {
88
+ const current = await this.store.getSprint(before.id);
89
+ if (current === undefined || current.updatedAt !== before.updatedAt)
90
+ throw new OrchestrationError(`Sprint was modified concurrently: ${before.id}`);
91
+ await this.store.saveSprint(after);
92
+ }
81
93
  async requireSprint(id) { const value = await this.store.getSprint(id); if (!value)
82
94
  throw new OrchestrationError(`Sprint not found: ${id}`); return value; }
83
95
  async record(kind, id, relatedIds, evidenceIds) { if (this.graph)
@@ -126,11 +138,11 @@ export class TaskEngine {
126
138
  if (task.status !== 'todo' && task.status !== 'blocked')
127
139
  throw new OrchestrationError(`Invalid task start from ${task.status}`);
128
140
  const updated = this.updated(task, { status: 'in_progress' });
129
- await this.store.saveTask(updated);
141
+ await this.saveTaskGuarded(task, updated);
130
142
  return updated;
131
143
  }
132
144
  async block(id) { const task = await this.require(id); if (task.status !== 'in_progress')
133
- throw new OrchestrationError('Only an in-progress task can be blocked'); const updated = this.updated(task, { status: 'blocked' }); await this.store.saveTask(updated); return updated; }
145
+ throw new OrchestrationError('Only an in-progress task can be blocked'); const updated = this.updated(task, { status: 'blocked' }); await this.saveTaskGuarded(task, updated); return updated; }
134
146
  async complete(id, validator) {
135
147
  const task = await this.require(id);
136
148
  if (task.status !== 'in_progress')
@@ -140,11 +152,18 @@ export class TaskEngine {
140
152
  throw new OrchestrationError(`Task validation did not accept completion: ${result.status}`);
141
153
  const evidenceIds = this.unique([...task.evidenceIds, ...result.checks.flatMap((check) => check.evidenceIds)]);
142
154
  const updated = this.updated(task, { status: 'done', evidenceIds });
143
- await this.store.saveTask(updated);
155
+ await this.saveTaskGuarded(task, updated);
144
156
  if (this.graph)
145
157
  await this.graph.record({ kind: 'task', id: updated.id, relatedIds: [updated.sprintId, ...updated.dependencyIds], evidenceIds });
146
158
  return updated;
147
159
  }
160
+ /** See SprintEngine.saveSprintGuarded — same lost-update race, same narrowing mitigation. */
161
+ async saveTaskGuarded(before, after) {
162
+ const current = await this.store.getTask(before.id);
163
+ if (current === undefined || current.updatedAt !== before.updatedAt)
164
+ throw new OrchestrationError(`Task was modified concurrently: ${before.id}`);
165
+ await this.store.saveTask(after);
166
+ }
148
167
  async require(id) { const value = await this.store.getTask(id); if (!value)
149
168
  throw new OrchestrationError(`Task not found: ${id}`); return value; }
150
169
  updated(value, changes) { return { ...value, ...changes, updatedAt: new Date().toISOString() }; }
@@ -156,7 +175,8 @@ export class HandoffEngine {
156
175
  graph;
157
176
  maxItems;
158
177
  maxItemLength;
159
- constructor(store, graph, maxItems = 20, maxItemLength = 500) { this.store = store; this.graph = graph; this.maxItems = maxItems; this.maxItemLength = maxItemLength; }
178
+ maxHandoffsPerCorrelation;
179
+ constructor(store, graph, maxItems = 20, maxItemLength = 500, maxHandoffsPerCorrelation = 200) { this.store = store; this.graph = graph; this.maxItems = maxItems; this.maxItemLength = maxItemLength; this.maxHandoffsPerCorrelation = maxHandoffsPerCorrelation; }
160
180
  async create(input) {
161
181
  for (const [name, value] of Object.entries({ from: input.from, to: input.to, intent: input.intent, objective: input.objective, nextAgent: input.nextAgent }))
162
182
  if (value.trim().length === 0)
@@ -166,6 +186,13 @@ export class HandoffEngine {
166
186
  if (input.evidenceIds.length === 0)
167
187
  throw new OrchestrationError('Handoff requires evidence references');
168
188
  const fields = { schemaVersion: CONTRACT_VERSION, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), correlationId: input.correlationId ?? `handoff:${input.intent}` };
189
+ // Nothing else bounds how many handoffs a single run can chain through (A→B→A→B→… has no
190
+ // structural cycle marker to detect), so this is the circuit breaker: past this count for one
191
+ // correlationId, something is looping without a human/gate in the loop, and it should fail
192
+ // loudly rather than accumulate audit records forever.
193
+ const priorForRun = (await this.store.listHandoffs()).filter((handoff) => handoff.correlationId === fields.correlationId).length;
194
+ if (priorForRun >= this.maxHandoffsPerCorrelation)
195
+ throw new OrchestrationError(`Handoff chain exceeded ${this.maxHandoffsPerCorrelation} handoffs for correlationId ${fields.correlationId} — likely an unbounded loop`);
169
196
  const value = { ...fields, id: randomUUID(), from: input.from.trim(), to: input.to.trim(), intent: input.intent.trim(), objective: input.objective.trim(), completedWork: this.compact(input.completedWork), decisions: this.compact(input.decisions), constraints: this.compact(input.constraints), pending: this.compact(input.pending), evidenceIds: [...new Set(input.evidenceIds)], acceptance: this.compact(input.acceptance), blockers: this.compact(input.blockers), nextAgent: input.nextAgent.trim() };
170
197
  await this.store.saveHandoff(value);
171
198
  if (this.graph)
@@ -9,12 +9,32 @@ export interface PolicyScope {
9
9
  readonly risks?: readonly RiskLevel[];
10
10
  readonly categories?: readonly PolicyCategory[];
11
11
  readonly pathPrefixes?: readonly string[];
12
+ /**
13
+ * Faixa opcional de `ChangeRiskAssessment.score` (0-100, SPEC-034) que a regra se aplica a.
14
+ * `PolicyRequest.riskScore` é um `number` puro, não o assessment inteiro — este pacote nunca
15
+ * importa `@forja/engineering-risk` (AC-5); quem calcula o score chama `RiskEngine.assess()`
16
+ * antes de montar o `PolicyRequest`.
17
+ */
18
+ readonly riskScoreRange?: readonly [number, number];
19
+ /**
20
+ * Faixa opcional de `AnomalyAssessment.score` (0-100, SPEC-040) que a regra se aplica a. Mesmo
21
+ * padrão exato de `riskScoreRange`: `PolicyRequest.anomalyScore` é um `number` puro, não o
22
+ * assessment inteiro — este pacote nunca importa `@forja/engineering-monitoring`; quem calcula o
23
+ * score chama `detectAnomaly()` antes de montar o `PolicyRequest`.
24
+ */
25
+ readonly anomalyScoreRange?: readonly [number, number];
12
26
  }
13
27
  export interface PolicyLimits {
14
28
  readonly maxTokens?: number;
15
29
  readonly maxFiles?: number;
16
30
  readonly maxDurationMs?: number;
17
31
  readonly maxRetries?: number;
32
+ /**
33
+ * Real dollar ceiling per execution (SPEC-029). Enforced the same way as maxFiles/maxTokens, in
34
+ * `CapabilityRegistry.checkLimits` — see that method for why this is a `checkLimits` concern and
35
+ * not part of rule matching. Optional so every existing rule keeps working unchanged.
36
+ */
37
+ readonly maxCostUsd?: number;
18
38
  }
19
39
  export interface PolicyRule {
20
40
  readonly id: string;
@@ -34,6 +54,14 @@ export interface ApprovalDetails {
34
54
  export interface PolicyRequest {
35
55
  readonly definition: CapabilityDefinition;
36
56
  readonly agent: AgentIdentity;
57
+ /**
58
+ * Identifies the run/action this decision belongs to. Required for approvals to actually
59
+ * resolve: without a stable key, every retry of the same step looks like a brand-new request
60
+ * and `authorize()` can never see that a human already approved it. Callers that omit this
61
+ * fall back to `agent.id`, which only works correctly for an agent with a single in-flight
62
+ * approval at a time.
63
+ */
64
+ readonly correlationId?: string;
37
65
  readonly projectId?: string;
38
66
  readonly environment: string;
39
67
  readonly categories: readonly string[];
@@ -41,6 +69,10 @@ export interface PolicyRequest {
41
69
  readonly budget?: TokenBudget;
42
70
  readonly now: ISO8601;
43
71
  readonly approval?: ApprovalDetails;
72
+ /** Score 0-100 de um `ChangeRiskAssessment` já calculado (SPEC-034) — ver `PolicyScope.riskScoreRange`. */
73
+ readonly riskScore?: number;
74
+ /** Score 0-100 de um `AnomalyAssessment` já calculado (SPEC-040) — ver `PolicyScope.anomalyScoreRange`. */
75
+ readonly anomalyScore?: number;
44
76
  }
45
77
  export interface ApprovalDecision {
46
78
  readonly decision: 'approved' | 'rejected';
@@ -66,6 +98,8 @@ export declare class ApprovalLedger {
66
98
  list(): readonly ApprovalRequest[];
67
99
  decide(id: EntityId, decision: ApprovalDecision): ApprovalRequest;
68
100
  expire(now: ISO8601): readonly ApprovalRequest[];
101
+ /** Most recent approval request recorded for this correlationId, if any. */
102
+ findByCorrelationId(correlationId: string): ApprovalRequest | undefined;
69
103
  get(id: EntityId): ApprovalRequest;
70
104
  }
71
105
  export declare class PolicyEngine {
@@ -79,6 +113,12 @@ export declare class PolicyEngine {
79
113
  });
80
114
  authorize(request: PolicyRequest): PolicyDecision;
81
115
  get approvals(): ApprovalLedger;
116
+ /**
117
+ * Resolves approval state for `request` instead of unconditionally demanding a fresh one.
118
+ * Keyed by `request.correlationId` (falling back to the agent id) so that resuming/retrying
119
+ * the same run recognizes a decision a human already made, rather than re-issuing an
120
+ * unresolvable `REQUIRE_APPROVAL` on every attempt — see ADR/finding on approval resume.
121
+ */
82
122
  private withApproval;
83
123
  private matches;
84
124
  private validateRules;
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from 'node:crypto';
2
- import { CONTRACT_VERSION, } from "../../contracts/src/index.js";
2
+ import { CONTRACT_VERSION, isPathWithinRoot, } from "../../contracts/src/index.js";
3
3
  export class PolicyError extends Error {
4
4
  constructor(message) {
5
5
  super(message);
@@ -61,6 +61,11 @@ export class ApprovalLedger {
61
61
  }
62
62
  return expired;
63
63
  }
64
+ /** Most recent approval request recorded for this correlationId, if any. */
65
+ findByCorrelationId(correlationId) {
66
+ const matches = this.list().filter((request) => request.correlationId === correlationId);
67
+ return matches.at(-1);
68
+ }
64
69
  get(id) {
65
70
  const request = this.requests.get(id);
66
71
  if (request === undefined && this.store !== undefined) {
@@ -90,7 +95,10 @@ export class PolicyEngine {
90
95
  const decision = match === undefined
91
96
  ? { effect: 'DENY', reason: 'No matching policy rule', policyId: 'default-deny' }
92
97
  : { effect: match.effect, reason: match.reason, policyId: match.id, ...(match.limits === undefined ? {} : { limits: this.asNumericLimits(match.limits) }) };
93
- if (this.approvalRequiredRisks.includes(request.definition.risk) && decision.effect === 'ALLOW') {
98
+ // ALLOW_WITH_LIMITS still grants execution — a critical-risk capability must not skip
99
+ // approval just because a rule chose to bound it with limits instead of an unconditional ALLOW.
100
+ const isGranting = decision.effect === 'ALLOW' || decision.effect === 'ALLOW_WITH_LIMITS';
101
+ if (this.approvalRequiredRisks.includes(request.definition.risk) && isGranting) {
94
102
  return this.withApproval(request, decision, 'Risk requires explicit approval');
95
103
  }
96
104
  if (decision.effect === 'REQUIRE_APPROVAL')
@@ -100,10 +108,33 @@ export class PolicyEngine {
100
108
  get approvals() {
101
109
  return this.approvalLedger;
102
110
  }
111
+ /**
112
+ * Resolves approval state for `request` instead of unconditionally demanding a fresh one.
113
+ * Keyed by `request.correlationId` (falling back to the agent id) so that resuming/retrying
114
+ * the same run recognizes a decision a human already made, rather than re-issuing an
115
+ * unresolvable `REQUIRE_APPROVAL` on every attempt — see ADR/finding on approval resume.
116
+ */
103
117
  withApproval(request, decision, reason) {
118
+ const correlationId = request.correlationId ?? request.agent.id;
119
+ const existing = this.approvalLedger.findByCorrelationId(correlationId);
120
+ if (existing !== undefined) {
121
+ if (existing.decision === 'approved') {
122
+ // `decision.effect` may already be ALLOW/ALLOW_WITH_LIMITS (gated only by the risk-level
123
+ // approval requirement) — keep it as-is. But when the *rule itself* is REQUIRE_APPROVAL,
124
+ // that's a gate, not a final verdict: once approved, it must resolve to a grant, or every
125
+ // retry would see the same rule match and stay stuck at REQUIRE_APPROVAL forever.
126
+ const effect = decision.effect === 'ALLOW' || decision.effect === 'ALLOW_WITH_LIMITS' ? decision.effect : decision.limits === undefined ? 'ALLOW' : 'ALLOW_WITH_LIMITS';
127
+ return { ...decision, effect, reason: 'Approval granted', approvalRequestId: existing.id };
128
+ }
129
+ if (existing.decision === 'rejected')
130
+ return { ...decision, effect: 'DENY', reason: `Approval rejected: ${existing.id}`, approvalRequestId: existing.id };
131
+ if (existing.decision === undefined)
132
+ return { ...decision, effect: 'REQUIRE_APPROVAL', reason, approvalRequestId: existing.id };
133
+ // existing.decision === 'expired': falls through to issue a fresh request below.
134
+ }
104
135
  if (request.approval === undefined)
105
136
  return { ...decision, effect: 'REQUIRE_APPROVAL', reason };
106
- const approval = this.approvalLedger.create({ ...request.approval, correlationId: request.agent.id }, request.now);
137
+ const approval = this.approvalLedger.create({ ...request.approval, correlationId }, request.now);
107
138
  return { ...decision, effect: 'REQUIRE_APPROVAL', reason, approvalRequestId: approval.id };
108
139
  }
109
140
  matches(scope, request) {
@@ -121,7 +152,11 @@ export class PolicyEngine {
121
152
  return false;
122
153
  if (scope.categories !== undefined && !scope.categories.some((category) => request.categories.includes(category)))
123
154
  return false;
124
- if (scope.pathPrefixes !== undefined && !request.files.every((file) => scope.pathPrefixes?.some((prefix) => file.startsWith(prefix))))
155
+ if (scope.pathPrefixes !== undefined && !request.files.every((file) => scope.pathPrefixes?.some((prefix) => isPathWithinRoot(prefix, file))))
156
+ return false;
157
+ if (scope.riskScoreRange !== undefined && (request.riskScore === undefined || request.riskScore < scope.riskScoreRange[0] || request.riskScore > scope.riskScoreRange[1]))
158
+ return false;
159
+ if (scope.anomalyScoreRange !== undefined && (request.anomalyScore === undefined || request.anomalyScore < scope.anomalyScoreRange[0] || request.anomalyScore > scope.anomalyScoreRange[1]))
125
160
  return false;
126
161
  return true;
127
162
  }
@@ -123,6 +123,9 @@ export class RuntimeEngine {
123
123
  input: { capabilityId: step.capabilityId, payload: step.payload },
124
124
  agent: run.agent,
125
125
  policy: this.policies.get(runId) ?? (() => { throw new RuntimeError('Runtime policy is missing'); })(),
126
+ // Stable across retries/resume of the same run — without it every attempt looks like a
127
+ // brand-new approval request and a human's decision can never be recognized on retry.
128
+ correlationId: runId,
126
129
  projectId: step.projectId,
127
130
  environment: step.environment,
128
131
  categories: step.categories,
@@ -64,3 +64,50 @@ export declare class SandboxEngine {
64
64
  private checksum;
65
65
  private audit;
66
66
  }
67
+ export interface SandboxedCapabilityOptions<T> {
68
+ readonly sandbox: SandboxEngine;
69
+ readonly runId: RunId;
70
+ /** Directory the isolated worktree/copy is created at — never the live project root. */
71
+ readonly root: string;
72
+ readonly backend?: SandboxSession['backend'];
73
+ readonly correlationId?: string;
74
+ /**
75
+ * Does the actual work: write files under `session.root` (never outside it), and run whatever
76
+ * verification the capability needs via `sandbox.execute(session.id, ...)` on the same instance
77
+ * passed in `options.sandbox`. Its return value is threaded through untouched as `workResult`.
78
+ */
79
+ readonly work: (session: SandboxSession) => T | Promise<T>;
80
+ }
81
+ export type SandboxedCapabilityOutcome = 'promoted' | 'rejected' | 'failed';
82
+ export interface SandboxedCapabilityResult<T> {
83
+ readonly session: SandboxSession;
84
+ readonly outcome: SandboxedCapabilityOutcome;
85
+ readonly workResult?: T;
86
+ readonly validation?: SandboxValidation;
87
+ readonly diff?: SandboxDiff;
88
+ readonly error?: unknown;
89
+ }
90
+ /**
91
+ * The create→prepare→work→validate→diff→promote(-or-reject/rollback)→destroy lifecycle, as a
92
+ * single call instead of hand-rolled per call site. Extracted from `scripts/demo-autonomy.ts`,
93
+ * which proved the pattern for one capability (`fixture.code.write`) — this is that same pattern
94
+ * made reusable, so a future capability that edits real project files has a paved, tested path to
95
+ * real isolation instead of either reinventing this state machine or (as every capability
96
+ * registered in `apps/cli/src/index.ts` does today) skipping isolation entirely because none of
97
+ * them currently write to project source — see docs/security/2026-08-31 audit for why that's
98
+ * currently fine and when it stops being fine: the moment a capability's handler starts writing
99
+ * to arbitrary project files, it needs to go through this, not straight `fs`/`spawnSync` on the
100
+ * live tree.
101
+ *
102
+ * Always destroys the session before returning, on every outcome — a caller never has to remember
103
+ * cleanup. Never throws for a rejected/failed *validation* (that's a normal outcome, reported via
104
+ * the return value); only rethrows if `options.work` itself throws, after best-effort cleanup.
105
+ *
106
+ * `options.work` must call `sandbox.execute(session.id, ...)` (on the same `sandbox` passed in
107
+ * `options.sandbox`) at least once before returning: `SandboxEngine.validate()` requires the
108
+ * session to already be in the `'validating'` state, and only `execute()` puts it there — this
109
+ * mirrors `demo-autonomy.ts`'s own capability handler, which always runs its verification command
110
+ * (`npm test` in the worktree) before considering the edit done. Writing files without ever
111
+ * calling `execute()` is a caller error, not something this helper can validate away.
112
+ */
113
+ export declare function runSandboxedCapability<T>(options: SandboxedCapabilityOptions<T>): Promise<SandboxedCapabilityResult<T>>;