@mastra/factory 0.29.0-alpha.3 → 0.29.0-alpha.5

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 (399) hide show
  1. package/README.md +123 -64
  2. package/dist/boards/board-events.d.ts +89 -9
  3. package/dist/boards/board-events.d.ts.map +1 -1
  4. package/dist/boards/board-events.js +176 -13
  5. package/dist/boards/board-events.js.map +1 -1
  6. package/dist/boards/board-writes.d.ts.map +1 -1
  7. package/dist/boards/board-writes.js +14 -1
  8. package/dist/boards/board-writes.js.map +1 -1
  9. package/dist/boards/busy-card.d.ts +11 -0
  10. package/dist/boards/busy-card.d.ts.map +1 -0
  11. package/dist/boards/busy-card.js +15 -0
  12. package/dist/boards/busy-card.js.map +1 -0
  13. package/dist/boards/card-facts.d.ts.map +1 -1
  14. package/dist/boards/card-facts.js +18 -4
  15. package/dist/boards/card-facts.js.map +1 -1
  16. package/dist/boards/index.d.ts +2 -1
  17. package/dist/boards/index.d.ts.map +1 -1
  18. package/dist/boards/index.js +3 -2
  19. package/dist/boards/intake-dry-run.d.ts +109 -0
  20. package/dist/boards/intake-dry-run.d.ts.map +1 -0
  21. package/dist/boards/intake-dry-run.js +158 -0
  22. package/dist/boards/intake-dry-run.js.map +1 -0
  23. package/dist/boards/intake-lookup.d.ts +32 -0
  24. package/dist/boards/intake-lookup.d.ts.map +1 -0
  25. package/dist/boards/intake-lookup.js +12 -0
  26. package/dist/boards/intake-lookup.js.map +1 -0
  27. package/dist/boards/intake-order.d.ts +32 -0
  28. package/dist/boards/intake-order.d.ts.map +1 -0
  29. package/dist/boards/intake-order.js +60 -0
  30. package/dist/boards/intake-order.js.map +1 -0
  31. package/dist/boards/intake-routing.d.ts +246 -35
  32. package/dist/boards/intake-routing.d.ts.map +1 -1
  33. package/dist/boards/intake-routing.js +437 -52
  34. package/dist/boards/intake-routing.js.map +1 -1
  35. package/dist/boards/reroute.d.ts +7 -3
  36. package/dist/boards/reroute.d.ts.map +1 -1
  37. package/dist/boards/reroute.js +21 -4
  38. package/dist/boards/reroute.js.map +1 -1
  39. package/dist/boards/semantics.d.ts +8 -28
  40. package/dist/boards/semantics.d.ts.map +1 -1
  41. package/dist/boards/semantics.js +7 -39
  42. package/dist/boards/semantics.js.map +1 -1
  43. package/dist/boards/work-routes.d.ts +31 -11
  44. package/dist/boards/work-routes.d.ts.map +1 -1
  45. package/dist/boards/work-routes.js +104 -20
  46. package/dist/boards/work-routes.js.map +1 -1
  47. package/dist/factory.d.ts +27 -1
  48. package/dist/factory.d.ts.map +1 -1
  49. package/dist/factory.js +32 -18
  50. package/dist/factory.js.map +1 -1
  51. package/dist/index.d.ts +0 -1
  52. package/dist/index.d.ts.map +1 -1
  53. package/dist/index.js +1 -2
  54. package/dist/integrations/base.d.ts +9 -0
  55. package/dist/integrations/base.d.ts.map +1 -1
  56. package/dist/integrations/dependabot/rules.d.ts.map +1 -1
  57. package/dist/integrations/dependabot/rules.js +2 -6
  58. package/dist/integrations/dependabot/rules.js.map +1 -1
  59. package/dist/integrations/github/commits.d.ts +0 -21
  60. package/dist/integrations/github/commits.d.ts.map +1 -1
  61. package/dist/integrations/github/commits.js +1 -24
  62. package/dist/integrations/github/commits.js.map +1 -1
  63. package/dist/integrations/github/default-rules.d.ts +22 -1
  64. package/dist/integrations/github/default-rules.d.ts.map +1 -1
  65. package/dist/integrations/github/default-rules.js +23 -5
  66. package/dist/integrations/github/default-rules.js.map +1 -1
  67. package/dist/integrations/github/intake-lookup.d.ts +16 -0
  68. package/dist/integrations/github/intake-lookup.d.ts.map +1 -0
  69. package/dist/integrations/github/intake-lookup.js +76 -0
  70. package/dist/integrations/github/intake-lookup.js.map +1 -0
  71. package/dist/integrations/github/integration.d.ts +20 -6
  72. package/dist/integrations/github/integration.d.ts.map +1 -1
  73. package/dist/integrations/github/integration.js +23 -12
  74. package/dist/integrations/github/integration.js.map +1 -1
  75. package/dist/integrations/github/review-status-reporter.js +1 -1
  76. package/dist/integrations/github/routes.d.ts +1 -11
  77. package/dist/integrations/github/routes.d.ts.map +1 -1
  78. package/dist/integrations/github/routes.js +20 -517
  79. package/dist/integrations/github/routes.js.map +1 -1
  80. package/dist/integrations/github/rules.d.ts +12 -1
  81. package/dist/integrations/github/rules.d.ts.map +1 -1
  82. package/dist/integrations/github/rules.js +275 -38
  83. package/dist/integrations/github/rules.js.map +1 -1
  84. package/dist/integrations/github/sandbox.d.ts.map +1 -1
  85. package/dist/integrations/github/sandbox.js +30 -4
  86. package/dist/integrations/github/sandbox.js.map +1 -1
  87. package/dist/integrations/gitlab/default-rules.d.ts.map +1 -1
  88. package/dist/integrations/gitlab/default-rules.js +19 -3
  89. package/dist/integrations/gitlab/default-rules.js.map +1 -1
  90. package/dist/integrations/gitlab/discovery.d.ts +1 -1
  91. package/dist/integrations/gitlab/discovery.js +1 -1
  92. package/dist/integrations/gitlab/discovery.js.map +1 -1
  93. package/dist/integrations/gitlab/intake-lookup.d.ts +17 -0
  94. package/dist/integrations/gitlab/intake-lookup.d.ts.map +1 -0
  95. package/dist/integrations/gitlab/intake-lookup.js +85 -0
  96. package/dist/integrations/gitlab/intake-lookup.js.map +1 -0
  97. package/dist/integrations/gitlab/integration.d.ts +5 -0
  98. package/dist/integrations/gitlab/integration.d.ts.map +1 -1
  99. package/dist/integrations/gitlab/integration.js +21 -2
  100. package/dist/integrations/gitlab/integration.js.map +1 -1
  101. package/dist/integrations/gitlab/routes.d.ts +0 -2
  102. package/dist/integrations/gitlab/routes.d.ts.map +1 -1
  103. package/dist/integrations/gitlab/routes.js +49 -165
  104. package/dist/integrations/gitlab/routes.js.map +1 -1
  105. package/dist/integrations/gitlab/rules.d.ts +20 -0
  106. package/dist/integrations/gitlab/rules.d.ts.map +1 -1
  107. package/dist/integrations/gitlab/rules.js +128 -19
  108. package/dist/integrations/gitlab/rules.js.map +1 -1
  109. package/dist/integrations/incidentio/routes.d.ts +5 -5
  110. package/dist/integrations/incidentio/routes.d.ts.map +1 -1
  111. package/dist/integrations/incidentio/routes.js +3 -59
  112. package/dist/integrations/incidentio/routes.js.map +1 -1
  113. package/dist/integrations/incidentio/rules.d.ts.map +1 -1
  114. package/dist/integrations/incidentio/rules.js +15 -9
  115. package/dist/integrations/incidentio/rules.js.map +1 -1
  116. package/dist/integrations/jira/issue-reconciler.d.ts +1 -1
  117. package/dist/integrations/jira/issue-reconciler.d.ts.map +1 -1
  118. package/dist/integrations/jira/issue-reconciler.js.map +1 -1
  119. package/dist/integrations/jira/routes.d.ts +2 -2
  120. package/dist/integrations/jira/routes.d.ts.map +1 -1
  121. package/dist/integrations/jira/routes.js +0 -68
  122. package/dist/integrations/jira/routes.js.map +1 -1
  123. package/dist/integrations/jira/rules.d.ts.map +1 -1
  124. package/dist/integrations/jira/rules.js +13 -7
  125. package/dist/integrations/jira/rules.js.map +1 -1
  126. package/dist/integrations/linear/routes.d.ts +2 -2
  127. package/dist/integrations/linear/routes.d.ts.map +1 -1
  128. package/dist/integrations/linear/routes.js +0 -83
  129. package/dist/integrations/linear/routes.js.map +1 -1
  130. package/dist/integrations/linear/rules.d.ts.map +1 -1
  131. package/dist/integrations/linear/rules.js +14 -7
  132. package/dist/integrations/linear/rules.js.map +1 -1
  133. package/dist/integrations/platform/github/event-worker.js +9 -1
  134. package/dist/integrations/platform/github/event-worker.js.map +1 -1
  135. package/dist/integrations/platform/github/integration.d.ts +6 -6
  136. package/dist/integrations/platform/github/integration.d.ts.map +1 -1
  137. package/dist/integrations/platform/github/integration.js +23 -6
  138. package/dist/integrations/platform/github/integration.js.map +1 -1
  139. package/dist/integrations/platform/jira/routes.d.ts +2 -2
  140. package/dist/integrations/platform/jira/routes.d.ts.map +1 -1
  141. package/dist/integrations/platform/jira/routes.js +0 -69
  142. package/dist/integrations/platform/jira/routes.js.map +1 -1
  143. package/dist/integrations/pull-request-head.d.ts +1 -1
  144. package/dist/integrations/pull-request-head.d.ts.map +1 -1
  145. package/dist/integrations/pull-request-head.js +5 -0
  146. package/dist/integrations/pull-request-head.js.map +1 -1
  147. package/dist/integrations/vanta/rules.d.ts.map +1 -1
  148. package/dist/integrations/vanta/rules.js +2 -6
  149. package/dist/integrations/vanta/rules.js.map +1 -1
  150. package/dist/packages/_internals/workspace/dist/index.js.map +1 -1
  151. package/dist/routes/automation-runs.d.ts +0 -2
  152. package/dist/routes/automation-runs.d.ts.map +1 -1
  153. package/dist/routes/automation-runs.js +2 -6
  154. package/dist/routes/automation-runs.js.map +1 -1
  155. package/dist/routes/board-snapshot.d.ts +8 -1
  156. package/dist/routes/board-snapshot.d.ts.map +1 -1
  157. package/dist/routes/board-snapshot.js +33 -7
  158. package/dist/routes/board-snapshot.js.map +1 -1
  159. package/dist/routes/boards.js.map +1 -1
  160. package/dist/routes/config.d.ts +6 -0
  161. package/dist/routes/config.d.ts.map +1 -1
  162. package/dist/routes/config.js +5 -2
  163. package/dist/routes/config.js.map +1 -1
  164. package/dist/routes/contracts.d.ts +1258 -5
  165. package/dist/routes/contracts.d.ts.map +1 -1
  166. package/dist/routes/contracts.js +588 -17
  167. package/dist/routes/contracts.js.map +1 -1
  168. package/dist/routes/fs.d.ts +10 -0
  169. package/dist/routes/fs.d.ts.map +1 -1
  170. package/dist/routes/fs.js +184 -11
  171. package/dist/routes/fs.js.map +1 -1
  172. package/dist/routes/intake-check.d.ts +92 -0
  173. package/dist/routes/intake-check.d.ts.map +1 -0
  174. package/dist/routes/intake-check.js +322 -0
  175. package/dist/routes/intake-check.js.map +1 -0
  176. package/dist/routes/intake-routes.d.ts +10 -2
  177. package/dist/routes/intake-routes.d.ts.map +1 -1
  178. package/dist/routes/intake-routes.js +292 -11
  179. package/dist/routes/intake-routes.js.map +1 -1
  180. package/dist/routes/mastra-gateway.d.ts.map +1 -1
  181. package/dist/routes/mastra-gateway.js +3 -2
  182. package/dist/routes/mastra-gateway.js.map +1 -1
  183. package/dist/routes/project-sessions.d.ts +49 -0
  184. package/dist/routes/project-sessions.d.ts.map +1 -0
  185. package/dist/routes/project-sessions.js +93 -0
  186. package/dist/routes/project-sessions.js.map +1 -0
  187. package/dist/routes/projects.d.ts.map +1 -1
  188. package/dist/routes/projects.js +4 -17
  189. package/dist/routes/projects.js.map +1 -1
  190. package/dist/routes/run-queue.d.ts +6 -6
  191. package/dist/routes/run-queue.d.ts.map +1 -1
  192. package/dist/routes/run-queue.js +28 -8
  193. package/dist/routes/run-queue.js.map +1 -1
  194. package/dist/routes/session-rows.d.ts +30 -0
  195. package/dist/routes/session-rows.d.ts.map +1 -0
  196. package/dist/routes/session-rows.js +98 -0
  197. package/dist/routes/session-rows.js.map +1 -0
  198. package/dist/routes/source-control-sessions.d.ts +4 -8
  199. package/dist/routes/source-control-sessions.d.ts.map +1 -1
  200. package/dist/routes/source-control-sessions.js +8 -106
  201. package/dist/routes/source-control-sessions.js.map +1 -1
  202. package/dist/routes/surface.d.ts +13 -3
  203. package/dist/routes/surface.d.ts.map +1 -1
  204. package/dist/routes/surface.js +25 -38
  205. package/dist/routes/surface.js.map +1 -1
  206. package/dist/routes/work-item-starters.d.ts +1 -0
  207. package/dist/routes/work-item-starters.d.ts.map +1 -1
  208. package/dist/routes/work-item-starters.js +14 -2
  209. package/dist/routes/work-item-starters.js.map +1 -1
  210. package/dist/routes/work-items.d.ts +13 -0
  211. package/dist/routes/work-items.d.ts.map +1 -1
  212. package/dist/routes/work-items.js +87 -34
  213. package/dist/routes/work-items.js.map +1 -1
  214. package/dist/rules/dispatch-errors.js +1 -1
  215. package/dist/rules/dispatch-errors.js.map +1 -1
  216. package/dist/rules/dispatcher.d.ts +39 -7
  217. package/dist/rules/dispatcher.d.ts.map +1 -1
  218. package/dist/rules/dispatcher.js +362 -127
  219. package/dist/rules/dispatcher.js.map +1 -1
  220. package/dist/rules/event-rules.d.ts +69 -1
  221. package/dist/rules/event-rules.d.ts.map +1 -1
  222. package/dist/rules/event-rules.js +151 -5
  223. package/dist/rules/event-rules.js.map +1 -1
  224. package/dist/rules/processor.d.ts.map +1 -1
  225. package/dist/rules/processor.js +1 -6
  226. package/dist/rules/processor.js.map +1 -1
  227. package/dist/rules/review-source-tool.js +1 -1
  228. package/dist/rules/rule-group.d.ts +18 -1
  229. package/dist/rules/rule-group.d.ts.map +1 -1
  230. package/dist/rules/rule-group.js +52 -8
  231. package/dist/rules/rule-group.js.map +1 -1
  232. package/dist/rules/run-bearing.d.ts +8 -0
  233. package/dist/rules/run-bearing.d.ts.map +1 -0
  234. package/dist/rules/run-bearing.js +11 -0
  235. package/dist/rules/run-bearing.js.map +1 -0
  236. package/dist/rules/start-coordinator.d.ts +2 -3
  237. package/dist/rules/start-coordinator.d.ts.map +1 -1
  238. package/dist/rules/start-coordinator.js +27 -35
  239. package/dist/rules/start-coordinator.js.map +1 -1
  240. package/dist/rules/tools.js +2 -1
  241. package/dist/rules/tools.js.map +1 -1
  242. package/dist/rules/transition-service.d.ts +16 -0
  243. package/dist/rules/transition-service.d.ts.map +1 -1
  244. package/dist/rules/transition-service.js +34 -12
  245. package/dist/rules/transition-service.js.map +1 -1
  246. package/dist/rules/types.d.ts +18 -5
  247. package/dist/rules/types.d.ts.map +1 -1
  248. package/dist/rules/types.js +2 -1
  249. package/dist/rules/types.js.map +1 -1
  250. package/dist/rules/update-fold.d.ts +32 -0
  251. package/dist/rules/update-fold.d.ts.map +1 -0
  252. package/dist/rules/update-fold.js +60 -0
  253. package/dist/rules/update-fold.js.map +1 -0
  254. package/dist/rules/validation.d.ts.map +1 -1
  255. package/dist/rules/validation.js +54 -6
  256. package/dist/rules/validation.js.map +1 -1
  257. package/dist/session/resource-migration.d.ts.map +1 -1
  258. package/dist/session/resource-migration.js +2 -3
  259. package/dist/session/resource-migration.js.map +1 -1
  260. package/dist/session/run-audit.d.ts +9 -0
  261. package/dist/session/run-audit.d.ts.map +1 -1
  262. package/dist/session/run-audit.js +9 -1
  263. package/dist/session/run-audit.js.map +1 -1
  264. package/dist/session/self-review-gate.d.ts +26 -2
  265. package/dist/session/self-review-gate.d.ts.map +1 -1
  266. package/dist/session/self-review-gate.js +60 -10
  267. package/dist/session/self-review-gate.js.map +1 -1
  268. package/dist/session/session-row-query.d.ts +25 -0
  269. package/dist/session/session-row-query.d.ts.map +1 -0
  270. package/dist/session/session-row-query.js +47 -0
  271. package/dist/session/session-row-query.js.map +1 -0
  272. package/dist/session/session-row-status.d.ts +16 -0
  273. package/dist/session/session-row-status.d.ts.map +1 -0
  274. package/dist/session/session-row-status.js +14 -0
  275. package/dist/session/session-row-status.js.map +1 -0
  276. package/dist/session/session-row-view.d.ts +14 -0
  277. package/dist/session/session-row-view.d.ts.map +1 -0
  278. package/dist/session/session-row-view.js +125 -0
  279. package/dist/session/session-row-view.js.map +1 -0
  280. package/dist/session/session-rows.d.ts +46 -0
  281. package/dist/session/session-rows.d.ts.map +1 -0
  282. package/dist/session/session-rows.js +232 -0
  283. package/dist/session/session-rows.js.map +1 -0
  284. package/dist/session/session-threads.d.ts.map +1 -1
  285. package/dist/session/session-threads.js +1 -0
  286. package/dist/session/session-threads.js.map +1 -1
  287. package/dist/session/source-control-tools.d.ts +14 -7
  288. package/dist/session/source-control-tools.d.ts.map +1 -1
  289. package/dist/session/source-control-tools.js +10 -2
  290. package/dist/session/source-control-tools.js.map +1 -1
  291. package/dist/session/work-item-repository.d.ts +44 -0
  292. package/dist/session/work-item-repository.d.ts.map +1 -1
  293. package/dist/session/work-item-repository.js +80 -1
  294. package/dist/session/work-item-repository.js.map +1 -1
  295. package/dist/session/work-item-state-processor.d.ts.map +1 -1
  296. package/dist/session/work-item-state-processor.js +44 -8
  297. package/dist/session/work-item-state-processor.js.map +1 -1
  298. package/dist/storage/domains/audit/actions.d.ts +2 -1
  299. package/dist/storage/domains/audit/actions.d.ts.map +1 -1
  300. package/dist/storage/domains/audit/actions.js +3 -1
  301. package/dist/storage/domains/audit/actions.js.map +1 -1
  302. package/dist/storage/domains/boards/base.d.ts +162 -14
  303. package/dist/storage/domains/boards/base.d.ts.map +1 -1
  304. package/dist/storage/domains/boards/base.js +415 -41
  305. package/dist/storage/domains/boards/base.js.map +1 -1
  306. package/dist/storage/domains/boards/schemas.d.ts +6 -0
  307. package/dist/storage/domains/boards/schemas.d.ts.map +1 -1
  308. package/dist/storage/domains/boards/schemas.js +93 -3
  309. package/dist/storage/domains/boards/schemas.js.map +1 -1
  310. package/dist/storage/domains/intake/base.d.ts +11 -10
  311. package/dist/storage/domains/intake/base.d.ts.map +1 -1
  312. package/dist/storage/domains/intake/base.js +30 -65
  313. package/dist/storage/domains/intake/base.js.map +1 -1
  314. package/dist/storage/domains/integrations/base.d.ts +0 -2
  315. package/dist/storage/domains/integrations/base.d.ts.map +1 -1
  316. package/dist/storage/domains/integrations/base.js +0 -6
  317. package/dist/storage/domains/integrations/base.js.map +1 -1
  318. package/dist/storage/domains/projects/base.d.ts.map +1 -1
  319. package/dist/storage/domains/projects/base.js +19 -22
  320. package/dist/storage/domains/projects/base.js.map +1 -1
  321. package/dist/storage/domains/source-control/base.d.ts +0 -10
  322. package/dist/storage/domains/source-control/base.d.ts.map +1 -1
  323. package/dist/storage/domains/source-control/base.js +6 -21
  324. package/dist/storage/domains/source-control/base.js.map +1 -1
  325. package/dist/storage/domains/source-control/inmemory.d.ts +1 -1
  326. package/dist/storage/domains/source-control/inmemory.d.ts.map +1 -1
  327. package/dist/storage/domains/source-control/inmemory.js +1 -6
  328. package/dist/storage/domains/source-control/inmemory.js.map +1 -1
  329. package/dist/storage/domains/work-items/base.d.ts +49 -53
  330. package/dist/storage/domains/work-items/base.d.ts.map +1 -1
  331. package/dist/storage/domains/work-items/base.js +152 -156
  332. package/dist/storage/domains/work-items/base.js.map +1 -1
  333. package/dist/storage/domains/work-items/cards.d.ts +3 -2
  334. package/dist/storage/domains/work-items/cards.d.ts.map +1 -1
  335. package/dist/storage/domains/work-items/cards.js +4 -2
  336. package/dist/storage/domains/work-items/cards.js.map +1 -1
  337. package/dist/storage/domains/work-items/work-item-schema.d.ts +12 -3
  338. package/dist/storage/domains/work-items/work-item-schema.d.ts.map +1 -1
  339. package/dist/storage/domains/work-items/work-item-schema.js +12 -3
  340. package/dist/storage/domains/work-items/work-item-schema.js.map +1 -1
  341. package/dist/storage/legacy-collections.d.ts +9 -0
  342. package/dist/storage/legacy-collections.d.ts.map +1 -0
  343. package/dist/storage/legacy-collections.js +17 -0
  344. package/dist/storage/legacy-collections.js.map +1 -0
  345. package/dist/storage/probed-list.d.ts +11 -0
  346. package/dist/storage/probed-list.d.ts.map +1 -0
  347. package/dist/storage/probed-list.js +52 -0
  348. package/dist/storage/probed-list.js.map +1 -0
  349. package/dist/tools/audit-events-tool.d.ts +2 -2
  350. package/dist/tools/read-tools.d.ts +0 -3
  351. package/dist/tools/read-tools.d.ts.map +1 -1
  352. package/dist/tools/read-tools.js +4 -42
  353. package/dist/tools/read-tools.js.map +1 -1
  354. package/dist/tools/session-tools.d.ts.map +1 -1
  355. package/dist/tools/session-tools.js +5 -9
  356. package/dist/tools/session-tools.js.map +1 -1
  357. package/dist/tools/work-item-tools.d.ts +3 -0
  358. package/dist/tools/work-item-tools.d.ts.map +1 -1
  359. package/dist/tools/work-item-tools.js +8 -4
  360. package/dist/tools/work-item-tools.js.map +1 -1
  361. package/dist/work-item-branch.d.ts +4 -0
  362. package/dist/work-item-branch.d.ts.map +1 -1
  363. package/dist/work-item-branch.js +7 -1
  364. package/dist/work-item-branch.js.map +1 -1
  365. package/dist/work-items/card-context-sessions.d.ts +50 -0
  366. package/dist/work-items/card-context-sessions.d.ts.map +1 -0
  367. package/dist/work-items/card-context-sessions.js +84 -0
  368. package/dist/work-items/card-context-sessions.js.map +1 -0
  369. package/dist/work-items/change-requests.d.ts +87 -0
  370. package/dist/work-items/change-requests.d.ts.map +1 -0
  371. package/dist/work-items/change-requests.js +134 -0
  372. package/dist/work-items/change-requests.js.map +1 -0
  373. package/dist/work-items/create-work-item.d.ts +7 -2
  374. package/dist/work-items/create-work-item.d.ts.map +1 -1
  375. package/dist/work-items/create-work-item.js +44 -13
  376. package/dist/work-items/create-work-item.js.map +1 -1
  377. package/dist/work-items/list-related-cards.d.ts.map +1 -1
  378. package/dist/work-items/list-related-cards.js +1 -1
  379. package/dist/work-items/list-related-cards.js.map +1 -1
  380. package/dist/work-items/providers/github.d.ts.map +1 -1
  381. package/dist/work-items/providers/github.js +1 -0
  382. package/dist/work-items/providers/github.js.map +1 -1
  383. package/dist/workspace.d.ts.map +1 -1
  384. package/dist/workspace.js +1 -3
  385. package/dist/workspace.js.map +1 -1
  386. package/factory-skills/configure-factory-rules/SKILL.md +2 -2
  387. package/factory-skills/factory-build/SKILL.md +1 -1
  388. package/factory-skills/factory-plan/SKILL.md +5 -3
  389. package/factory-skills/factory-self-review/SKILL.md +2 -0
  390. package/factory-skills/factory-triage/SKILL.md +1 -1
  391. package/package.json +10 -10
  392. package/dist/session/filesystem-capture.d.ts +0 -50
  393. package/dist/session/filesystem-capture.d.ts.map +0 -1
  394. package/dist/session/filesystem-capture.js +0 -229
  395. package/dist/session/filesystem-capture.js.map +0 -1
  396. package/dist/storage/domains/filesystem/base.d.ts +0 -30
  397. package/dist/storage/domains/filesystem/base.d.ts.map +0 -1
  398. package/dist/storage/domains/filesystem/base.js +0 -78
  399. package/dist/storage/domains/filesystem/base.js.map +0 -1
package/README.md CHANGED
@@ -66,6 +66,8 @@ Two reads answer questions about a project's cards without listing them. `GET /w
66
66
 
67
67
  Two more reads serve a board without sending every card. `GET /web/factory/projects/:id/boards/:boardKey/phases` returns one entry per phase of the board in `phases`, in the board's order: `phase` is its id, `total` counts the cards in it, and `cards` names the first of them as `{ id, version }`. `version` names the card's body: it is another value whenever anything in the body is, including a change that leaves `changedAt` as it was. `limit` sets how many each phase names (50 unless given, 200 at most), `window=<phase>:<count>` (repeatable) names more cards of one phase, and `item=<card id>` asks for one card wherever it lies: the answer names it in `item` as `{ id, version, places }`, where `places` gives each phase the view lists it under and its `position` there (how many cards the phase lists before it), and `cards=true` sends its body. No phase names more cards for it, so the answer is the same size for the oldest card of a phase as for the newest. `places` is empty when the search or filters leave the card out, and `item` is absent when the board does not hold the card. `sort` is `recent` (latest entry into the phase first, the default), `recent-mine` (the cards the signed-in user last moved into the phase first), `created-newest` or `created-oldest`. `q` keeps the cards whose title, key, number or source id contains every word in it; `label`, `source`, `linearProject`, `teammate`, `author`, `assignee`, `reviewer` and `worked` (all repeatable) keep the cards matching every field given. `boardTotal` counts the board's cards whatever the search and filters, `matchingTotal` the cards matching them, a card in two phases once. `related` names the cards related to a named card that no phase names, the first `limit` of each card's, and `relatedTotal` counts them all, and `runningSessionIds` and `parkedSessionIds` cover the named cards. Pass `cards=true` to also receive the body of every named card in `workItems`, each with its `version`; without it, read the cards whose `version` differs from the copy you kept with `GET /web/factory/projects/:id/work-items?workItemId=<id>`, which sends each card with its `version` too. A card in none of the board's phases is counted in the first one. A malformed parameter is a 400 `invalid_phases_query`; a board the project doesn't have is a 404; a `window` for a phase the board doesn't have is ignored. `GET /web/factory/projects/:id/work-items/filter-options` returns what a board can be filtered by, over every card of the project: `labels`, sorted; `people`, each person a source names as author, assignee or requested reviewer, as `{ id, name, source }`; and `actorIds`, the Factory users who filed, moved or started a card. Both answers carry an `ETag`; send it back as `If-None-Match` and an unchanged answer is a 304.
68
68
 
69
+ Two reads serve the sidebar's sessions without sending every session and every card holding one. `GET /web/factory/projects/:id/session-rows` returns the rows of one view of the project's sessions, built on the server: one row per card for a card's sessions (`cardSessionIds` names them all; `children=true` lists the others under the row in `childRows` instead), and one row per session a person or Slack started. Each row carries its `session`, its `status` (`waiting`, `working`, `initializing`, `idle` or `done`), the card it works on, and the card's pull or merge request. `sort` is `activity` (the default), `updated` or `created`; `groupBy` is `none` (the default), `board`, `status` or `owner`; `owner` is `all`, `mine` or `owner:<user id>`; `status` and `updated` (`24h`, `7d` or `30d`) keep the matching rows. `groups` lists the groups holding a matching row, in the order their first row sorts, each with its `key`, its `total` and its first 5 `rows`; `window=<group key>:<count>` (repeatable, 500 at most) lists more of one group. `pin=<session id>` (repeatable) lists sessions before every other one of their group, and `open=<session id>` keeps that session's row listed in its group however deep it lies, with its place in `openIndex`. `total` counts every row, `matching` the rows the filters keep, and `boards` and `owners` name every board and person some row has, whatever the filters. `GET /web/factory/projects/:id/session-activity` returns which sessions are running, waiting on a person's answer or still coming up, and how many cards have a session working or waiting. In both answers `settling` is `true` while a session is still coming up: the answer will change with no event to say so, so ask again. Both carry an `ETag`; send it back as `If-None-Match` and an unchanged answer is a 304. A malformed `session-rows` parameter is a 400 `invalid_session_rows_query`.
70
+
69
71
  #### Migration and dry run
70
72
 
71
73
  Factory keeps the legacy `work_items` table and copies each card into the new tables. Before it starts serving, it copies only open cards. Done and canceled cards are copied in the background afterwards and appear on the board shortly after startup. While that runs, opening a card, or receiving a Linear, Jira, GitHub, GitLab, or incident.io event for it, copies that card on demand, so a reopened issue keeps its original card. Board lists, such as the Done column, fill in as the background copy progresses.
@@ -469,7 +471,7 @@ Unknown integrations, unknown event names, and handler values other than a funct
469
471
 
470
472
  ### Config version
471
473
 
472
- `configVersion` is an operator-maintained deployment label stamped onto transition audit rows, deferred decisions, reconciler audit, and the session kickoff header (`Config: …`). Nothing branches on it; it exists so an audit row can be traced back to the deployment that produced it. It defaults to `factory-config-v1` and must be a non-empty bounded string. The storage column keeps its shipped name, `rule_set_version`.
474
+ `configVersion` is an operator-maintained deployment label. It is recorded in the metadata of transition audit events and in the session kickoff header (`Config: …`), and rule handlers receive it in their context. Nothing branches on it; it exists so an audit event can be traced back to the deployment that produced it. It defaults to `factory-config-v1` and must be a non-empty bounded string.
473
475
 
474
476
  ```typescript
475
477
  new MastraFactory({ storage, configVersion: 'deployment-v2' });
@@ -587,12 +589,12 @@ A new pull request or merge request that belongs to a card already on a board th
587
589
  When Factory first sees a pull request (GitHub `pull_request.opened`) or merge request (GitLab `open`), it looks for a home card in the same Factory project and repository. The home card must be on a board that reviews pull requests, not in one of its terminal phases, and not a pull request's own card. Factory checks, in order:
588
590
 
589
591
  1. **A pull request Factory opened for one of its cards** goes to that card, found by provenance or by the head branch matching the card's session branch. On GitHub the card must own an issue of its own: a GitHub card must be from the same repository, while a card whose issue lives in Jira, Linear or incident.io carries no repository to match against and is taken as it is. On GitLab, any card with an issue of its own (GitLab, Linear, Jira or incident.io). A card from the other forge never takes one (a GitLab card keeps only merge requests), and neither does a manual card, since the pull request would become its only source; its pull request gets a separate card. A card still in Building moves to the board's pull request review phase (on a board with self-review, that phase opens the pull request itself, so it has been skipped). A review request or `@<app> review` still sends it there.
590
- 2. **A pull request that closes an issue** can join that issue's card if a project [intake route](#intake-routes) with a `joinClosedIssue` target says so. Factory reads closing keywords from the pull request body or merge request description: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`, and on GitLab also `implement`, `implements`, `implemented`, `implementing`. The target is `#N`, or `owner/repo#N` (`group/project#N`) naming the same repository. References to other repositories, links, and code spans don't count. If the pull request names several issues, the first one with an eligible card is the one routes see. The default route joins a trusted author's pull request to a card still waiting in Intake with no pull request yet, and moves that card to Review. Once the card has moved on (Triage, Planning or Building), or already carries a pull request, someone else's pull request gets its own card in Review and is reviewed right away. Done and Canceled cards are finished, so a pull request for them gets its own card too.
592
+ 2. **A pull request that closes an issue** links to that issue's card, whoever opened it and on whichever board the card sits, as long as the card isn't finished. Factory reads closing keywords from the pull request body or merge request description: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`, and on GitLab also `implement`, `implements`, `implemented`, `implementing`. The target is `#N`, or `owner/repo#N` (`group/project#N`) naming the same repository. References to other repositories, links, and code spans don't count. If the pull request names several issues, it links to the first one with an unfinished card. Linking itself moves nothing: the card then gets a `pull_request.opened` event, and the card's board's [card-move rules](#status-events-move-existing-cards) decide whether it moves. The default rule, `Trusted pull requests take a waiting issue to Review`, moves a card still waiting in Intake with no pull request yet to Review when the pull request's author is trusted. A card further along stays where it is. Done and Canceled cards are finished, so a pull request for them gets its own card.
591
593
  3. **Anything else** gets its own card, exactly as before.
592
594
 
593
- An untrusted author's pull request never attaches, even when it says `fixes #12` and a route would allow it: it gets its own card in Intake, so an outside author can't take over a trusted card or its sessions. Linking only happens on first sighting: editing the body later doesn't move a pull request onto or off a card, and a replayed delivery doesn't attach it twice. A link made only in GitHub's sidebar isn't visible in the webhook, so that pull request gets its own card. The reconcile sweep doesn't carry the body either, so closing references are only read from live deliveries.
595
+ An outside author's pull request links too, but is recorded on the card as untrusted (`untrustedPullRequests` in the card's metadata), and nothing runs on it until a person picks it: it is never the card's working pull request on its own, its pushes and review requests don't re-review it, and comments on it don't reach the card's sessions. Its opening, reopening, pushes, edits and review requests move the card only by a card-move rule that tests `pullRequest.trusted`: a rule that doesn't, such as an older project's "Pull requests go to Review" or one testing only `source.repository`, skips it. Its merge or close still moves the card like any other. Card-less pull requests are filed by intake as before. To work on it, a person makes it the card's working pull request with `PUT /web/factory/projects/:id/work-items/:workItemId/working-pull-request` (`{ "pullRequest": 17, "expectedRevision": 4 }`); the pull request must be linked to the card and open (`422 pull_request_not_linked`, `422 pull_request_not_open`), and a stale revision answers `409`. Picking it doesn't make its author trusted: `pullRequest.trusted` stays `false`. Linking only happens on first sighting: editing the body later doesn't move a pull request onto or off a card, and a replayed delivery doesn't attach it twice. A link made only in GitHub's sidebar isn't visible in the webhook, so that pull request gets its own card. The reconcile sweep doesn't carry the body either, so closing references are only read from live deliveries.
594
596
 
595
- Any card that enters Work's Review (`pr-review`), or another board's pull request review phase, carrying a pull request starts the reviewer, whatever its own source. On a card with an attached pull request, the pull request's state lives on its own source, and the issue keeps its own; a reopened merge request is open on the card again. `openPullRequestNumber` only names a pull request the card's own sessions opened (its head is one of the card's session branches, or the branch Factory builds the card on). When that pull request closes, it moves to the card's next open one of its own, or clears, never to someone else's, so another person's pull request never switches off the builder's self-review or its own pull request. When a pull request merges, the card moves to Done unless another one is still open, in which case its session is told which one is out. When one closes unmerged, a card in Review with no open pull request left goes back to Intake. The reviewer checks out the pull request on its own branch (`factory/pr-<n>-…`, `factory/gitlab-mr-<n>-…`) in an untrusted checkout, never in the builder's session or branch.
597
+ Any card that enters Work's Review (`pr-review`), or another board's pull request review phase, carrying a pull request starts the reviewer, whatever its own source. On a card with an attached pull request, the pull request's state lives on its own source, and the issue keeps its own; a reopened merge request is open on the card again. The card's working pull request is the one its sessions build on and its reviewer reviews: the one `openPullRequestNumber` names, otherwise the first trusted linked one. One that closed unmerged no longer counts, so the card falls back to its first trusted open pull request, never an outsider's. `openPullRequestNumber` names a pull request the card's own sessions opened, or one a person picked (its head is one of the card's session branches, or the branch Factory builds the card on). When that pull request closes, it moves to the card's next open one of its own, or clears, never to someone else's, so another person's pull request never switches off the builder's self-review or its own pull request. When the working pull request merges, the card moves to Done unless another working one is still open, in which case its session is told which one is out. When one closes unmerged, a card in Review with no open pull request left goes back to Intake. The reviewer checks out the pull request on its own branch (`factory/pr-<n>-…`, `factory/gitlab-mr-<n>-…`) in an untrusted checkout, never in the builder's session or branch.
596
598
 
597
599
  #### The retired Review board
598
600
 
@@ -660,26 +662,27 @@ Boards and phases take `name` and an optional `description`. A phase lists the p
660
662
 
661
663
  - `runner` — `{ agentId?, skill?, context?, instructions?, goal? }`. The runner is the only way a phase starts work: when a card enters the phase, from any source and including a card filed straight into it, Factory starts `skill` in the `context` session. `context` names the session the phase runs in (defaults to `work`); phases that share a context share a session. When the agent moves its own card into another phase of its context, that phase's `skill` still starts: its kickoff is queued onto the agent's run. Moving a card back into the phase it is in (a re-entry, such as a re-review after a push) supersedes the run in flight and resumes the skill. `skill` names a built-in Factory skill or one of your app's skills (see [Skills for custom boards](#skills-for-custom-boards)); a phase without one starts nothing. The kickoff names the card only by its URL (or title, quoted as untrusted data when an outside author wrote it); the agent reads everything else from the [`factory-work-item` signal](#the-factory-work-item-signal). `instructions` (up to 1,000 characters) are added to the kickoff. `agentId` defaults to `code-agent`, the only agent Factory runs today.
662
664
  - `runner.goal` — `{ objective, maxRuns? }`: the run pursues `objective` (up to 2,000 characters) as a Mastra goal. Factory stores it on the session's thread as the run starts, with the session's model as judge, and after each run the judge decides from the objective text and the latest messages whether the work is done, should continue (Factory starts another run, up to `maxRuns`, 1–50) or is waiting for a person. Waiting leaves the goal active and the card in its phase; the next message a person sends resumes it, and a skill asks people with `ask_user`, which parks the run in Factory's attention view. When `maxRuns` runs out, the goal pauses and the card stays: resume it from the session or move the card. When the card leaves the phase, by anyone, Factory marks the goal done. The judge sees only the objective and the latest messages, so state the done and waiting criteria in the objective. Work's Building pursues the approved plan this way, with up to 20 runs.
663
- - `autoStart` and `autoStartWhen` — the phase's runs start without a person's approval, for every card or only for cards matching the rule. To start only trusted authors' cards, add `author.trusted equals true` to `autoStartWhen`; by default, [intake routes](#intake-routes) file GitHub and GitLab cards from outside the write-access circle in Work › Intake, where nothing starts on its own.
665
+ - `autoStart` and `autoStartWhen` — the phase's runs start without a person's approval, for every card or only for cards matching the rule. To start only trusted authors' cards, add `item.trusted equals true` to `autoStartWhen`; by default, [intake routes](#intake-routes) file GitHub and GitLab cards from outside the write-access circle in Work › Intake, where nothing starts on its own.
664
666
  - `exitTool` — a tool name, or `{ id, autoApprove, autoApproveWhen }`, that ends the phase. The phase holds the card until that tool succeeds (for `submit_plan`, with an approved plan) in the session that works the card there: until then an agent or board rule asking to move the card on to another working phase is rejected with `approval_required`. Once it has succeeded during the card's current visit to the phase, the agent moves the card itself with `factory_transition_work_item` (the factory-phase signal tells it so and lists `nextPhases`), or a board tool rule for the exit tool (`tools`) moves it; the tool's success never moves the card by itself. A person can move the card at any time. The phase needs at least one next phase. `autoApprove` and `autoApproveWhen` only decide whether the tool approves itself, for every card or only cards matching the rule, or waits for a person; they are the only way plans are approved without a person. Factory sessions already run tools without asking, so for `submit_plan` this means an auto-approved plan is accepted without a person. Any other exit tool that pauses for a yes or no is approved the same way, and the sessions following the card are told a run waits on them only when a person has to answer. Work's Planning declares `{ id: 'submit_plan', autoApprove: false }`: every plan waits for a person, who approves `submit_plan` in a signed-in chat (or moves the card), and then `factory-plan` moves the card to Building.
665
667
  - `tools` — Factory tools the phase gives the session that works the card in it (the session whose context is the phase's `runner.context`): `factory_record_review_verdict` and `factory_review_source`. Tools follow the card: when it moves to a phase without them, the session loses them on its next turn, and a verdict tool call made after the card moved is refused. Every bound session keeps `factory_transition_work_item`. Work's Review grants both; a self-review phase, on a board that has one, grants only the verdict tool.
666
668
 
667
669
  Rules test a card's facts, read from its work item as the provider reported it:
668
670
 
669
- | Fact | What it is |
670
- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
671
- | `item.labels` | The item's labels. |
672
- | `item.title` | The card's title. |
673
- | `item.author` | Who opened the item. |
674
- | `item.key` | The provider's key: `acme/app#42` (GitHub), `acme/app!7` (GitLab merge request), `ENG-12` (Linear), `OPS-3` (Jira), `INC-7` (incident.io). |
675
- | `item.state` | The provider's state: `open`, `closed` or `merged` on GitHub and GitLab, the workflow state name (`In Progress`) on Linear and Jira. |
676
- | `item.assignees` | Who the item is assigned to, as a list. |
677
- | `item.pullRequest` | The number of the card's open pull or merge request, absent when it has none. |
678
- | `author.trusted` | Whether the author is trusted (see below). |
679
- | `source.kind` | `issue`, `pull_request`, … |
680
- | `source.integration` | The integration that filed it: `github`, `gitlab`, `linear`, `jira`, `incidentio`, … |
681
- | `source.provider` | The provider the work item comes from; the integration for every integration Factory ships. |
682
- | `source.repository` | Where the item lives, compared case-insensitively. GitHub: `owner/repo` (`mastra-ai/mastra`, never the bare `mastra`). GitLab: the full project path, subgroups included (`acme/platform/api`). Linear: the team key (`ENG`). Jira: the project key (`PLAT`). Absent for incident.io items (test `source.provider equals incidentio` instead) and for manual cards, which have no `source.*` facts (test `source.kind not_exists`). |
671
+ | Fact | What it is |
672
+ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
673
+ | `item.labels` | The item's labels. |
674
+ | `item.title` | The card's title. |
675
+ | `item.author` | Who opened the item. |
676
+ | `item.key` | The provider's key: `acme/app#42` (GitHub), `acme/app!7` (GitLab merge request), `ENG-12` (Linear), `OPS-3` (Jira), `INC-7` (incident.io). |
677
+ | `item.state` | The provider's state: `open`, `closed` or `merged` on GitHub and GitLab, the workflow state name (`In Progress`) on Linear and Jira. |
678
+ | `item.assignees` | Who the item is assigned to, as a list. |
679
+ | `item.pullRequest` | The number of the card's open pull or merge request, absent when it has none. |
680
+ | `item.trusted` | Whether the item's author has write access (see below). Rules saved with the old name `author.trusted` read as `item.trusted`. |
681
+ | `pullRequest.trusted` | On a pull request event, whether that pull request's author has write access (or Factory opened it); otherwise, whether the author of the card's working pull request does. Absent when there is neither. |
682
+ | `source.kind` | `issue`, `pull_request`, … |
683
+ | `source.integration` | The integration that filed it: `github`, `gitlab`, `linear`, `jira`, `incidentio`, … |
684
+ | `source.provider` | The provider the work item comes from; the integration for every integration Factory ships. |
685
+ | `source.repository` | Where the item lives, compared case-insensitively. GitHub: `owner/repo` (`mastra-ai/mastra`, never the bare `mastra`). GitLab: the full project path, subgroups included (`acme/platform/api`). Linear: the team key (`ENG`). Jira: the project key (`PLAT`). Absent for incident.io items (test `source.provider equals incidentio` instead) and for manual cards, which have no `source.*` facts (test `source.kind not_exists`). |
683
686
 
684
687
  Strings compare case-insensitively, so `source.repository equals Acme/App` matches `acme/app`. A list fact (`item.labels`, `item.assignees`) is tested by its members: `item.assignees equals ada` matches when Ada is one of the assignees, and an empty list counts as missing, so `item.assignees exists` matches only assigned items. A fact the item doesn't have fails every operator except `not_exists`, `not_equals`, `not_contains` and `not_in`.
685
688
 
@@ -725,11 +728,21 @@ const factory = new MastraFactory({ storage, dispatcher: { maxInFlight: 25 } });
725
728
 
726
729
  The cap counts per process, not per deployment: three replicas with the default run up to 30 at once.
727
730
 
731
+ A reply a person writes on a card's GitHub pull request or issue doesn't wait behind automated runs. Each process keeps 2 more slots for these replies, claims them ahead of automated runs, and lets them borrow a free automated slot once the reserve is full. Change the reserve with `dispatcher.maxInteractiveInFlight`, or `MASTRACODE_DISPATCH_MAX_INTERACTIVE_IN_FLIGHT`; `0` keeps no reserve, though replies are still claimed first:
732
+
733
+ ```ts
734
+ const factory = new MastraFactory({ storage, dispatcher: { maxInFlight: 10, maxInteractiveInFlight: 2 } });
735
+ ```
736
+
737
+ A run counts as a reply only when GitHub reports its sender as a user (not a bot), the sender is a trusted collaborator, Factory didn't write it, it would wake the session, and no rule passed it along from another event. Everything else, including GitLab, Linear, Jira and incident.io activity, waits as an automated run.
738
+
739
+ The caps bound how many slots the dispatcher holds, not how many agents run. With the defaults a process holds up to 12 slots. Pull request activity (`signalActivity`) frees its slot once the session accepts it, so the run it wakes continues outside the cap. Messages you send from the Factory UI or Slack, and approval notices to a following session, go to the session directly and never wait for a slot.
740
+
728
741
  The board shows how many automated runs are waiting, and opens a list of them, oldest first. A waiting card reads `Queued (#3)`. Manual starts take the same slots and are claimed ahead of these runs, but are not listed. `GET /web/factory/projects/:id/run-queue` returns the same data:
729
742
 
730
- - `slots` — this server's `inUse` and `cap`, or `null` when it runs no dispatcher. Other replicas keep their own.
743
+ - `slots` — this server's automated `inUse` and `cap`, with the reply reserve's `interactive.inUse` and `interactive.cap`, or `null` when it runs no dispatcher. A reply that borrowed an automated slot counts in `inUse`. Other replicas keep their own.
731
744
  - `running` and `claimed` — the project's automated runs a server holds a slot for, on any replica. A manual start holding a slot counts in `slots.inUse` but not here, so `running` can be lower than `inUse`.
732
- - `queuedCount` and `queued` — every automated run waiting for a slot, and the oldest 50 with their `position`, card, phase and the skill they will run. A retry still backing off is not waiting yet.
745
+ - `queuedCount` and `queued` — every run waiting for a slot, and up to 50 of them, waiting replies first, then automated runs, each oldest first, with their `lane` (`interactive` for a person's reply, else `automated`), `position` within that lane, card, phase and the skill they will run. `queuedByLane` splits `queuedCount` by lane. A retry still backing off is not waiting yet.
733
746
 
734
747
  ### The `factory-work-item` signal
735
748
 
@@ -888,7 +901,7 @@ Use the host's normal `prepare()`, `new Mastra(...)`, and `finalize()` sequence.
888
901
 
889
902
  Create a card with `POST /web/factory/projects/:id/work-items`, passing `board: 'release'`, a title, and the GitHub issue's `externalSource`. The card starts in `backlog`. Then use `POST /web/factory/projects/:id/work-items/:workItemId/transition` with `board: 'release'`, `stage: 'preparing'`, the returned `expectedRevision`, a unique `requestId`, and a `cause`. Send these requests as an authorized user using the host's authentication. The move starts the preparer. Its bound tool advances to `build`; the publisher's completed check produces a deferred transition to `done`. Terminal entry revokes the binding and releases the sandbox. The Factory UI performs the same operations against installed boards (see below); verify the persisted card's board, phase, and deferred decision status either way.
890
903
 
891
- Tool-result and integration handlers may return `upsertLinkedWorkItem` targeting a different installed board. Linked cards enter that board's declared initial phase before moving to the requested phase. Existing cards cannot be reassigned to another board through either decision type. Targets are validated against their own installed board before acceptance and again before uncommitted deferred effects execute; a phase declared only on another board is not valid. Committed replay retains its recorded result and original `configVersion`.
904
+ Tool-result and integration handlers may return `upsertLinkedWorkItem` targeting a different installed board. Linked cards enter that board's declared initial phase before moving to the requested phase. Existing cards cannot be reassigned to another board through either decision type. Targets are validated against their own installed board before acceptance and again before uncommitted deferred effects execute; a phase declared only on another board is not valid. Committed replay returns its recorded result, even if the installed configuration has changed since.
892
905
 
893
906
  Custom phase signals and persisted tool-result ingestion use the item's installed board. Bound tools re-resolve the live binding, retain revision and topology checks, and reject session reassignment. A custom role named `triage` does not inherit Work's classification requirements. Existing authorization, external-author safeguards, and board-owned policies still apply.
894
907
 
@@ -914,42 +927,25 @@ Label routes (`GET`/`PUT /web/intake/label-routes`) and a binding's `board` were
914
927
 
915
928
  ### Intake routes
916
929
 
917
- Each project has an ordered list of intake routes: the only thing that decides where a new card lands. Admins manage them in Settings › Work Intake › Intake routes or through the API, and anyone in the project can read them. A route names the board events it handles in `on`. A route on `work_item.created`, the default, decides where a new card lands: the first enabled route whose `when` matches the card names its board and phase. A route on `work_item.closed` or `work_item.reopened` decides where an existing card moves when its source closes or reopens (see [Status events](#status-events-move-existing-cards)).
930
+ Each project has an ordered list of intake routes: the only thing that decides where a new card lands. Admins manage them in Settings › Work Intake › Intake routes or through the API, and anyone in the project can read them. A route names the board events it handles in `on`. Events come in two families: `work_item.*` events are about issues, and every pull or merge request event is `pull_request.*`. A route on `work_item.opened` decides where a new issue lands, and a route on `pull_request.opened` where a new pull request with no card lands: the first enabled route whose `when` matches names its board and phase. `pull_request.opened` is also a card move: when a pull request opens for an issue's unfinished card, the card's board's `pull_request.opened` routes decide where that card moves. A route on `work_item.closed`, `work_item.reopened` or `work_item.updated` decides where an existing issue's card moves when the issue closes, reopens or has its labels or assignees changed; the `pull_request.*` routes do the same for a pull request's card (see [Status events](#status-events-move-existing-cards) and [Label and assignee changes](#label-and-assignee-changes-move-existing-cards)). `work_item.created` is the older arrival event: it files new issues and new pull requests with no card alike, and never moves a card. Routes that name it, or name no event (the default for a route created without `on`), keep that meaning, and the API keeps it as written, so editing an older route never narrows it to issues. A `pull_request.opened` route stored by Factory 0.28 or earlier only ever moved cards, and still does: it files no pull request, so it can't take an outside author's pull request ahead of the outside-authors route. The API returns it with `pullRequestOpenedMovesOnly: true` and Settings lists it with its board's card moves. Every edit keeps it that way, `on` included; to file pull requests, add a route.
918
931
 
919
- **The default routes.** Every project starts with twelve routes: four for new cards, one of which files a pull request on its issue's card and the last of which takes everything else; three that move cards when their issue closes or reopens; and five that move cards when a pull request's status changes. The first, `Pull requests that close a waiting issue join its card`:
920
-
921
- ```json
922
- {
923
- "when": {
924
- "operator": "AND",
925
- "conditions": [
926
- { "field": "source.kind", "operator": "equals", "value": "pull_request" },
927
- { "field": "author.trusted", "operator": "equals", "value": true },
928
- { "field": "pullRequest.closesIssue", "operator": "equals", "value": true },
929
- { "field": "closedIssue.phase", "operator": "in", "value": ["intake"] },
930
- { "field": "closedIssue.hasPullRequest", "operator": "equals", "value": false }
931
- ]
932
- },
933
- "target": { "boardKey": "work", "phaseKey": "pr-review", "joinClosedIssue": true }
934
- }
935
- ```
936
-
937
- It adds a trusted author's pull request to the card of the issue it closes while that card is still waiting (see [One card for an issue and its pull requests](#one-card-for-an-issue-and-its-pull-requests)). Edit `closedIssue.phase` to let pull requests join cards further along, or delete the route to give every pull request its own card. The second, `Outside authors wait in Intake`:
932
+ **The default routes.** Every project starts with thirteen routes: four for new cards, the last two of which take every other pull request and issue; three that move cards when their issue closes or reopens; and six that move cards when a pull request's status changes or a pull request links to their issue. Issue routes are on `work_item.opened` and pull request routes on `pull_request.opened`. A project set up before routes named the two families keeps its routes as they were: its routes on `work_item.created` file issues and pull requests alike, and it isn't given `Pull requests from outside authors wait in Intake`, which its outside-authors route already covers. The first, `Outside authors wait in Intake`:
938
933
 
939
934
  ```json
940
935
  {
936
+ "on": ["work_item.opened"],
941
937
  "when": {
942
938
  "operator": "AND",
943
939
  "conditions": [
944
940
  { "field": "source.integration", "operator": "in", "value": ["github", "gitlab"] },
945
- { "field": "author.trusted", "operator": "equals", "value": false }
941
+ { "field": "item.trusted", "operator": "equals", "value": false }
946
942
  ]
947
943
  },
948
944
  "target": { "boardKey": "work", "phaseKey": "intake" }
949
945
  }
950
946
  ```
951
947
 
952
- It files GitHub and GitLab issues and pull requests from authors outside the write-access circle in Work › Intake, ahead of the routes after it. Intake is a resting phase, so nothing starts there on its own. Any session, a person's or an agent's, can move the card on, and that move starts the next phase's run. Pushes to a pull request resting in Intake don't re-review it, and comments and edits on an issue never re-run Triage (see GitHub event rules). Trusted authors' cards, and Linear, Jira and incident.io cards (which carry no trust stamp), land where they did before. The third, `Pull requests go to Review`, sends every other pull request and merge request (`source.kind equals pull_request`) to Work › Review, where the reviewer runs once a person starts it, or on its own when the phase has `autoStart`. Because it comes after the outside-authors route, an outside author's pull request still waits in Intake. A pull request Factory opened for one of its own cards is filed by that card's rule, which no route re-places: it is attached to the authoring card, which goes out for review. Pull requests opened before attaching existed keep their own card.
948
+ It files GitHub and GitLab issues from authors outside the write-access circle in Work › Intake, and the second, `Pull requests from outside authors wait in Intake` (on `pull_request.opened`, with `source.kind equals pull_request` too, so as a card move it never sends an issue's card back), does the same for their pull requests, ahead of the routes after it. Intake is a resting phase, so nothing starts there on its own. Any session, a person's or an agent's, can move the card on, and that move starts the next phase's run. Pushes to a pull request resting in Intake don't re-review it, and comments and edits on an issue never re-run Triage (see GitHub event rules). Trusted authors' cards, and Linear, Jira and incident.io cards (which carry no trust stamp), land where they did before. The third, `Pull requests go to Review`, has no condition and sends every other new pull request and merge request to Work › Review, where the reviewer runs once a person starts it, or on its own when the phase has `autoStart`. Because it comes after the outside-authors route, an outside author's pull request still waits in Intake. A pull request Factory opened for one of its own cards is filed by that card's rule, which no route re-places: it is attached to the authoring card, which goes out for review. Pull requests opened before attaching existed keep their own card.
953
949
 
954
950
  The other three move Work cards when their issue's status changes:
955
951
 
@@ -959,7 +955,7 @@ The other three move Work cards when their issue's status changes:
959
955
  | `Issues closed as not planned go to Canceled` | `["work_item.closed"]` | `event.reason equals canceled` | Work › Canceled |
960
956
  | `Reopened issues go back to Intake` | `["work_item.reopened"]` | none | Work › Intake |
961
957
 
962
- Five more move Work cards when a pull request's status changes. Each agrees with the move Work's default pull request rule already makes, so out of the box nothing changes; retarget one to send those cards elsewhere:
958
+ Six more move Work cards on pull request events. The first five agree with the move Work's default pull request rule already makes, so out of the box nothing changes; retarget one to send those cards elsewhere:
963
959
 
964
960
  | Route | `on` | `when` | Target |
965
961
  | ------------------------------------------------------------- | ----------------------------------- | ------------------------------------- | --------------- |
@@ -968,26 +964,29 @@ Five more move Work cards when a pull request's status changes. Each agrees with
968
964
  | `Issues whose pull request closed unmerged go back to Intake` | `["pull_request.closed"]` | `source.kind not_equals pull_request` | Work › Intake |
969
965
  | `Pushes to a reviewed pull request re-review it` | `["pull_request.synchronized"]` | none | Work › Review |
970
966
  | `Requested reviews go to Review` | `["pull_request.review_requested"]` | none | Work › Review |
967
+ | `Trusted pull requests take a waiting issue to Review` | `["pull_request.opened"]` | see below | Work › Review |
968
+
969
+ The last one handles a pull request that just linked to its issue's card (see [One card for an issue and its pull requests](#one-card-for-an-issue-and-its-pull-requests)). Its `when` requires `pullRequest.trusted`, `pullRequest.closesIssue`, `closedIssue.phase in ["intake"]` and `closedIssue.hasPullRequest equals false`. Edit `closedIssue.phase` to move cards further along too, or delete it to leave linked cards where they are.
971
970
 
972
971
  They replace the close handlers each integration used to apply on its own, so a closed GitHub, GitLab, Linear, Jira or incident.io issue lands where it did before, but you can now edit or disable that move. To stop closes from moving Work cards, disable both close routes. Deleting them does not stop the move: with no route left that handles closes, Work's `sourceClosed` mapping moves closed cards to Done or Canceled again.
973
972
 
974
- The default routes are stored routes like any other: list them, edit them, disable them, reorder them or delete them through the API. Factory adds each one once, the first time the project's routes are read or written, appending it after the project's existing routes, and doesn't add it back after an admin deletes it. The closing-issue route is the exception: it goes first, since its condition only matches trusted authors' pull requests that close an issue. Deleting a default is permanent: recreate it by hand to get it back. A project set up before the pull request, closing-issue or close and reopen routes existed gets them this way too.
973
+ The default routes are stored routes like any other: list them, edit them, disable them, reorder them or delete them through the API. Factory adds each one once, the first time the project's routes are read or written, appending it after the project's existing routes, and doesn't add it back after an admin deletes it. Deleting a default is permanent: recreate it by hand to get it back. A project set up before the pull request or close and reopen routes existed gets them this way too. Routes that joined a pull request to its issue's card (`joinClosedIssue: true`, such as the old default `Pull requests that close a waiting issue join its card`) are switched off once when a project gets the `Trusted pull requests take a waiting issue to Review` rule, and kept so their history stays readable; pull requests now link on their own. A switched-off join route an admin had changed from that default also gets a `rule_retired` entry in the project's intake decision log naming it, since the new rule may not do all it did: add a card-move rule on `pull_request.opened` to move cards the way it did.
975
974
 
976
- **Everything else.** The last default route, `Everything else goes to Work › Intake`, has no condition and sends every new card the routes before it don't take to Work › Intake. Point it at another board to send there every new card the routes above it don't take, or use **Send new cards to** in Settings, which also copies the close, reopen and pull request routes onto that board: a status event only moves a card through routes on the card's own board. Routes above it still apply, so with the defaults, outside authors' items still wait in Work › Intake and pull requests still go to Work › Review; disable or edit those routes to send them elsewhere too. A new route that places new cards goes just ahead of the first enabled route with no condition that takes every new card, whoever added it, so it can match. A route that only handles status events goes at the end. A project with no route left that places a card files it in the default board's first phase.
975
+ **Everything else.** The last default route, `Everything else goes to Work › Intake`, has no condition and sends every new card the routes before it don't take to Work › Intake. Point it at another board to send there every new card the routes above it don't take, or use **Send new cards to** in Settings, which also copies the close, reopen and pull request routes onto that board: a status event only moves a card through routes on the card's own board. Routes above it still apply, so with the defaults, outside authors' items still wait in Work › Intake and pull requests still go to Work › Review; disable or edit those routes to send them elsewhere too. A new route that places new cards goes just ahead of the first enabled route with no condition that takes every new card, whoever added it, so it can match. A route that only handles status events goes at the end. A project with no route left that places a card files it in the default board's first phase. Under the [intake order](#intake-order) evaluator there is no default board: an item no board's rules take is Not routed instead.
977
976
 
978
- **Trust only decides where a card arrives.** Once a card is moved out of Intake, later input on it runs like on any card: a maintainer's push re-reviews an outside author's pull request. A phase that should only auto-start for trusted authors says so in its `autoStartWhen` (`author.trusted equals true`). Runs on untrusted cards still use their own isolated memory.
977
+ **Trust only decides where a card arrives.** Once a card is moved out of Intake, later input on it runs like on any card: a maintainer's push re-reviews an outside author's pull request. A phase that should only auto-start for trusted authors says so in its `autoStartWhen` (`item.trusted equals true`). An outside author's pull request linked to someone else's card is the exception: nothing runs on it until a person makes it the card's working pull request. Runs on untrusted cards still use their own isolated memory.
979
978
 
980
979
  **Route shape.**
981
980
 
982
- | Field | Meaning |
983
- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
984
- | `name` | Up to 120 characters. |
985
- | `enabled` | Defaults to `true`. Disabled routes are skipped. |
986
- | `on` | The board events the route handles: `work_item.created` (the default), `work_item.closed`, `work_item.reopened`, `pull_request.opened`, `pull_request.synchronized`, `pull_request.review_requested`, `pull_request.merged` and `pull_request.closed`. Each at most once. `work_item.commented` and `work_item.edited` are activity, which never moves a card, so a route can't name them. |
987
- | `when` | A rule over the card's facts (the same format as `autoStartWhen`). `null`, the default, matches every card. A route that handles more than `work_item.created` can also test `event.type` and `event.reason`. |
988
- | `target` | Required. `{ boardKey, phaseKey?, joinClosedIssue? }` sets where matching cards land; without `phaseKey` they land in the board's first phase. The board must be installed in the project (code or stored). For a route on `work_item.created`, the phase can't be terminal and must be reachable from the board's first phase; a route that only moves existing cards can target any phase, terminal ones included. With `joinClosedIssue: true`, a pull request is added to the card of the issue it closes instead of getting its own card, and that card moves to `phaseKey` when the board allows the move (otherwise it stays put); the route is skipped when there is no such card on `boardKey`, and its `on` must be `["work_item.created"]` alone. An update that sets `target` replaces the whole target, so repeat `joinClosedIssue: true` to keep a route joining. |
981
+ | Field | Meaning |
982
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
983
+ | `name` | Up to 120 characters. |
984
+ | `enabled` | Defaults to `true`. Disabled routes are skipped. |
985
+ | `on` | The board events the route handles: `work_item.created` (the default: new issues and pull requests), `work_item.opened`, `work_item.reopened`, `work_item.updated`, `work_item.closed`, `pull_request.opened`, `pull_request.reopened`, `pull_request.updated`, `pull_request.synchronized`, `pull_request.review_requested`, `pull_request.merged` and `pull_request.closed`. Each at most once. `work_item.commented` and `work_item.edited` are activity, which never moves a card, so a route can't name them. |
986
+ | `when` | A rule over the card's facts (the same format as `autoStartWhen`). `null`, the default, matches every card. Every route can test `item.hasPullRequest` (an issue with an open pull request attached) and `item.hasIssue` (a pull request that closes or links an issue). A route that handles more than arrivals (`work_item.opened`, `work_item.created`) can also test `event.type`, `event.reason` and `card.phase` (the phase the card is in); a route on `work_item.updated` or `pull_request.updated` can test `event.labels.added`, `event.labels.removed`, `event.assignees.added` and `event.assignees.removed`. `item.key`, `item.title`, `item.state`, `source.integration`, `item.pullRequest`, `closedIssue.phase` and `closedIssue.hasPullRequest` are legacy filters: stored routes using them keep evaluating, but the editor no longer offers them. |
987
+ | `target` | Required. `{ boardKey, phaseKey?, moveToBoardKey? }` sets where matching cards land; without `phaseKey` they land in the board's first phase. The board must be installed in the project (code or stored). For a route that files new cards (`work_item.opened`, `pull_request.opened` or `work_item.created`), the phase can't be terminal and must be reachable from the board's first phase; a route that only moves existing cards can target any phase, terminal ones included. `moveToBoardKey` lets a route on `boardKey` that names none of those events send them to `phaseKey` on another installed board (see [Status events](#status-events-move-existing-cards)). `joinClosedIssue: true` is retired: a new route can't set it (`422 join_retired`), and a stored one can only be switched off. |
989
988
 
990
- Routes are evaluated in `position` order (0 first). Rules can test the [card facts](#phase-runners-automatic-starts-and-exit-tools) phase rules test, `source.repository` and `item.labels` among them. For pull requests, routes can also test `pullRequest.closesIssue` (`true` when the body closes an issue that has a usable card), `closedIssue.phase` and `closedIssue.hasPullRequest` (that card's phase and whether it already carries a pull request). These three are route-only: phase rules can't use them. A route that lets a pull request join a card already in its review phase doesn't start a second review: the review in progress keeps its pull request, and the new one is reviewed on its next push by a trusted author, or on a review request once the current pass has a verdict. That's why the default route requires `closedIssue.hasPullRequest` to be `false`. `author.trusted` is `true` when the card carries an `authorTrusted: true` or `factoryAuthored: true` stamp. GitHub and GitLab stamp `authorTrusted` from the author's repository permission, and a stamp that is missing counts as untrusted.
989
+ Routes are evaluated in `position` order (0 first). Rules can test the [card facts](#phase-runners-automatic-starts-and-exit-tools) phase rules test, `source.repository` and `item.labels` among them. For pull requests, routes can also test `pullRequest.closesIssue` (`true` when the body closes an issue that has a usable card), `closedIssue.phase` and `closedIssue.hasPullRequest` (that card's phase and whether it already carries a pull request). These three are route-only: phase rules can't use them. On the `pull_request.opened` a linked pull request sends its card, `closedIssue.*` describe the card as it was before the pull request linked. A card already in its review phase doesn't start a second review when another pull request links: the review in progress keeps its pull request. That's why the default rule requires `closedIssue.hasPullRequest` to be `false`. `item.trusted` is `true` when the card carries an `authorTrusted: true` or `factoryAuthored: true` stamp. GitHub and GitLab stamp `authorTrusted` from the author's repository permission, and a stamp that is missing counts as untrusted.
991
990
 
992
991
  **Placement.** When an integration files a new card, or a card is created without naming a board (the `factory_create_work_item` tool, or `POST /web/factory/projects/:id/work-items` without `board`), the first enabled route that matches the card and whose board can take it decides where the card lands. On the built-in boards, a pull request lands on Work only in Intake or Review and Review takes only cards with a pull request; a route a card can't take is skipped and the next one is tried. If the route's phase no longer exists, or can no longer be reached from the first phase, the card lands in the first phase. A card routed to a later phase enters the first phase and then moves on through the transition service as a system move, recorded in the card's history. The route makes this move, not a person, so it gives no consent to start work; a run the phase asks for still needs a person unless the phase starts on its own (`autoStart`). A board whose transition policy refuses system moves refuses the route, and the card is not filed. The board and phase an integration's rule names don't count: every integration files a new card in the default board's first phase, and the routes take it from there. If no route places it, it stays there. The default board is Work; a project without a Work board (one an app gave only its own boards with `upsertBoard`) uses its first board in catalog order instead, so its arrivals are still filed and placed by its routes. A project with no boards at all files nothing, and refuses cards created without a board, until a board is installed.
993
992
 
@@ -999,9 +998,47 @@ A card a route placed records the route's id in its `intakeRouteId` metadata and
999
998
 
1000
999
  A pull request routed to a board with a [pull request loop](#the-pull-request-loop-on-any-board) is reviewed there; on a board without one, review requests and pushes do nothing to its card.
1001
1000
 
1001
+ #### Intake order
1002
+
1003
+ Each board owns its intake rules: a rule places cards on its own board only, and each board has at most 100. A project also keeps an **intake order**, separate from the sidebar order: the order its boards are asked to take a new item. Under the intake order evaluator, intake asks each board in that order, and inside a board its rules top to bottom; the first enabled rule that matches and whose phase can take the card decides. Nothing names a board to fall back to. An item no board takes is **Not routed**: no card is filed, and the item is kept with the reason so an admin can fix a rule and route it again. A card created without a board that no board takes is refused with `intake_board_required` (422), so the person picks the board; `factory_create_work_item` takes that board as `board`. While the intake rules can't be read (stored boards unavailable), arrivals wait and retry, and a card created without a board is refused the same way.
1004
+
1005
+ Each project has its own evaluator. A project created since this release is stamped with `intake-order` as it is created, in the same write. A project from before it has no setting and keeps `route-list`, the evaluator described above (one list across all boards, then the default board's first phase), until an admin switches it with `PUT .../intake-order` and `{ "evaluator": "intake-order" }` (audited as `factory.intake_order.evaluator_updated`). `MastraFactory({ intake: { evaluator } })` or `FACTORY_INTAKE_EVALUATOR` (`intake-order` or `route-list`) forces one evaluator on every project, whatever its setting; the option wins over the variable. Set the same on every replica. A project uses `route-list` only when its setting was read and is empty: while the setting can't be read (stored boards unavailable), its arrivals wait and retry, a card created without a board is refused with `intake_board_required`, and Route again is refused, unless `route-list` is forced. During a rolling deploy, a replica still on an older release ignores the setting and decides every project by `route-list`, so a new project's items can be routed by the route list until every replica runs this release; a project created on such a replica gets no setting and stays on `route-list` until switched.
1006
+
1007
+ Until an admin sets it, a project's intake order is derived from the route list: boards by the position of their first enabled rule that places new cards, then boards with no such rule, in sidebar order. A project whose rules for each board sit together routes exactly as before. A project whose rules interleave boards can route differently. While the order is derived, every rule write (create, edit, delete, reorder, or deleting a board with rules) derives it again. Setting the order with `PUT .../intake-order` fixes it: rule writes no longer change it. A board created later goes into the order just above the first board whose rules end in an enabled rule with no condition (a catch-all), or last when no board has one. Deleting a board deletes its rules, each with a `factory.intake_route.deleted` audit entry carrying `cause: "board_deleted"`, and drops it from the order.
1008
+
1009
+ | Request | What it does |
1010
+ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1011
+ | `GET /web/factory/projects/:id/intake-routes?boardKey=…` | One board's rules, in their order. |
1012
+ | `POST /web/factory/projects/:id/intake-routes/reorder` | With `boardKey`, `ids` names every rule of that board; they swap among the places that board's rules hold, and other boards' rules stay put. Admin only. |
1013
+ | `PATCH /web/factory/projects/:id/intake-routes/:routeId` | Under the intake order evaluator, a `target.boardKey` other than the rule's own board is refused with `intake_route_board_fixed` (422). |
1014
+ | `GET /web/factory/projects/:id/intake-order` | The boards in intake order, whether the order is `derived` or `explicit`, the evaluator in use with `evaluatorSource` (`option`, `env`, `project`, or `legacy` for a project with no setting) and the project's own `projectEvaluator`, and a comparison of both evaluators over the project's newest 200 items against that order (`compared`, `differing`, `notRouted`), worked out on every read. |
1015
+ | `PUT /web/factory/projects/:id/intake-order` | `{ boardKeys }`, every board once, refused with `intake_order_set_mismatch` (409) otherwise. Admin only; audited as `factory.intake_order.updated`. |
1016
+ | `GET /web/factory/projects/:id/intake/not-routed` | Items no board took and nobody has filed since, oldest first, with the reason. Paged: `limit` (default 50, at most 100) and `cursor`, the `nextCursor` of the page before (null on the last). |
1017
+ | `POST /web/factory/projects/:id/intake/not-routed/:decisionId/route-again` | Runs intake for the item again, by intake order whichever evaluator the replica runs. Refused with `intake_not_routed` (422) while no board's rules take it; otherwise 202, and the dispatcher files it where the rules say. Admin only; audited as `factory.intake.routed_again`. |
1018
+ | `GET /web/factory/projects/:id/intake/skipped` | Each card-move rule that matched but was skipped because its target couldn't take the card, in the last 30 days: `routeId`, `count`, and the newest skip as `latest`. |
1019
+
1020
+ Every arrival's decision (placed or Not routed) is recorded under both evaluators. Once a card is filed for an item, by Route again or by a later delivery a fixed rule takes, its Not routed record is resolved and leaves the list.
1021
+
1022
+ #### Checking intake rules before they file anything
1023
+
1024
+ A rule that never fires, because an earlier board takes everything it would match, can't be spotted by reading the rules. Two requests show it on real items, using the intake order evaluator's own code, so under that evaluator they answer exactly what filing would. They run intake order whichever evaluator files the project, and both responses say which one does in `evaluator`: under `route-list`, filing can land items elsewhere, such as on the default board. Neither files a card, records a decision, writes an audit entry, or writes to a provider.
1025
+
1026
+ | Request | What it does |
1027
+ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1028
+ | `POST /web/factory/projects/:id/intake/dry-run` | Runs the rules over the project's newest 200 items: its cards from a source plus the Not routed items nobody filed since, from their stored facts, without fetching anything. Per board and per rule: the items it takes, the items it matched that an earlier board or rule took (`lost`, by the board that took them), and `filed`, the cards it actually filed in the last 30 days. Also the items no board takes, and per item where it lands and every rule that matched. |
1029
+ | `POST /web/factory/projects/:id/intake/test` | "Where would this go?" for one item: `itemId` (a card's or a Not routed item's id) or `url`. Answers where it lands, or why nothing takes it, and what every rule on every board answered: `took`, `lost` (with the rule that took it), `no_match` (with each failed condition and the item's value for it), `phase_refuses`, or `disabled`. |
1030
+
1031
+ Both take unsaved edits: `boards` replaces the named boards' rules with drafts (other boards run their saved rules) and `order` replaces the intake order. With either, the dry run also reports `changed`, how many items land on a different board or phase than under the saved rules, and each item's `before`. Any member can run the saved rules; unsaved edits need the role that edits rules (organization admin).
1032
+
1033
+ A draft is held to the checks saving it faces: an order that misses or invents a board is refused with `intake_order_set_mismatch` (422), and two rules sharing an `id` with `intake_draft_rule_id_repeated` (422). A `url` already on a card, as its own source or one it holds since (such as a pull request linked to an issue card), reads the card's stored facts. A recent Not routed item's `url` is read again from its provider when it can be, since a label or a reopen takes it in again with the facts it has now; otherwise its stored arrival answers. A rule that files only issues (`work_item.opened`) or only pull requests (`pull_request.opened`) answers `no_match` for the other kind, with the `source.kind` it saw as the failed condition. Any other URL is read once from its provider, and only from a GitHub repository or GitLab project linked to this project, with that link's credentials; a URL for one that isn't linked is refused with `not_linked` (422) before anything is fetched. A fetched pull request is tested as a new arrival; if it closes an issue with a card, or comes from a card's branch, filing joins it to that card instead, which `note` says. Linear, Jira and incident.io items are tested from recent items by `itemId`.
1034
+
1035
+ On a card, the tester also replays card moves. It sends the card's 10 newest status events (`opened`, `updated` with the labels and assignees that changed, `reopened`, `closed`, and the pull request events), plus one `event` sent in the request to try, through the card-move rules on the card's board, replayed against the card's current phase and facts. Pending `updated` events replay as the dispatcher acts on them: a burst is folded into its newest event with the dispatcher's own fold, and one whose labels and assignees end where they started answers `ignored`. An update that already acted replays as it was folded then, not with newer updates folded in. The tester reads the card's 200 newest decisions; an update whose burst may reach back past them answers `unknown` instead of guessing. Each answers `moves` (to which board, phase and rule), `stays`, `rule_default` (no rule handles it, so the integration's own move applies), `ignored` (the event can't move a card in its state, such as reopening one that isn't finished) or `unknown`, and lists what every rule answered: `took`, `lost`, `no_match` with the failed conditions, `skipped` (its target board or phase can't take the card) or `disabled`. The dispatcher moves cards through the same code, so a replay of a pending event answers what the dispatcher will do with it. A URL finds the card holding that item in any form that names it: another tab of a pull request (`/files`, `/diffs`), a query string, `www.` or a different case. Sending an `event` for an item with no card is refused with `intake_event_needs_card` (422).
1036
+
1037
+ Stored facts are what Factory last saw of the item, so a dry run can differ from live data the provider changed since. A pull request's `closedIssue.*` facts come from the issue it closed at the time it arrived and aren't kept, so the dry run reads pull requests without them.
1038
+
1002
1039
  #### Status events move existing cards
1003
1040
 
1004
- Every integration reports issue status changes with the same names: `work_item.created` when an issue is first seen, `work_item.closed` when it closes, and `work_item.reopened` when it reopens (GitHub and GitLab; Linear, Jira and incident.io report opens and closes only). A close carries `event.reason`: `canceled` for GitHub's "not planned" and "duplicate" and for Linear, Jira and incident.io canceled states, `completed` otherwise (GitLab closes are always `completed`).
1041
+ Every integration reports issue status changes with the same names: `work_item.opened` when an issue is first seen, `work_item.closed` when it closes, and `work_item.reopened` when it reopens (GitHub and GitLab; Linear, Jira and incident.io report opens and closes only). A reopened GitHub or GitLab issue, pull request or merge request with no card is filed like a new one. A close carries `event.reason`: `canceled` for GitHub's "not planned" and "duplicate" and for Linear, Jira and incident.io canceled states, `completed` otherwise (GitLab closes are always `completed`).
1005
1042
 
1006
1043
  When one of these arrives for a card that already exists, the first enabled route on the card's board whose `on` names the event and whose `when` matches the card and the event moves the card to the route's phase:
1007
1044
 
@@ -1021,12 +1058,34 @@ Pull request events (GitHub and GitLab) work the same way, with these difference
1021
1058
  - A merge or close moves only an unfinished card. `pull_request.opened`, `pull_request.synchronized` and `pull_request.review_requested` move finished cards too, so a done pull request is re-reviewed on a push as before.
1022
1059
  - When the card's board has routes on the event but none enabled matches the card, the rule's own move still runs: disabling the merge route doesn't strand a merged card in review.
1023
1060
  - Pull request events never drop one another: each concerns its own pull request.
1024
- - Factory sees no pull request reopen, so there is no `pull_request.reopened`.
1061
+ - `pull_request.reopened` (GitHub) moves a card only where a route on its board names it; there is no default move. Like `synchronized`, it moves the card whatever its phase.
1025
1062
 
1026
- Only routes targeting the card's own board apply; a route naming another board is skipped. For issue status events (`work_item.closed` and `work_item.reopened`), a route on the card's board that names the event owns it even when it is disabled or its `when` doesn't match: the card stays put. Pull request events differ, as above: when no enabled route takes the card, the rule's own move still runs. Only on a board where no route names the event does the board's `sourceClosed` mapping apply, so custom boards keep closing as before. To stop closes from moving Work cards, disable both close routes: deleting them hands closes back to Work's `sourceClosed` mapping, which moves the card to Done or Canceled.
1063
+ Only routes on the card's own board apply; a route naming another board is skipped. A route on the card's board with `moveToBoardKey` sends the card to that board's phase, keeping the same card: the old phase's session sandbox stops, the target phase's runner starts, and the old board's `nextPhases` don't matter. The target board must take the card (its phase exists and its lanes take the card), otherwise the route is skipped and the next one is tried; the skip is kept in the project's intake decision log as a `rule_skipped` entry naming the route, the target board and why. A move to another board fires no further routes, so two boards whose rules send cards to each other move a card once per event. For issue status events (`work_item.closed` and `work_item.reopened`), a route on the card's board that names the event owns it even when it is disabled or its `when` doesn't match: the card stays put. Pull request events differ, as above: when no enabled route takes the card, the rule's own move still runs. Only on a board where no route names the event does the board's `sourceClosed` mapping apply, so custom boards keep closing as before. To stop closes from moving Work cards, disable both close routes: deleting them hands closes back to Work's `sourceClosed` mapping, which moves the card to Done or Canceled.
1027
1064
 
1028
1065
  A deployment that answers an event itself keeps routes out of it: a handler or `null` set explicitly on the integration's `rules` for `issueClosed`, `issueReopened`, `issueCommentCreated` and so on, or `null` on the card's board handlers. An override that moves nothing really moves nothing. A board handler that wraps or returns the stock close move is different: that move still goes to the routes, as the stock handler's own would.
1029
1066
 
1067
+ #### Label and assignee changes move existing cards
1068
+
1069
+ `work_item.updated` and `pull_request.updated` fire only when an item's labels or assignees change; title, body and draft edits never do. They carry what changed in `event.labels.added`, `event.labels.removed`, `event.assignees.added` and `event.assignees.removed`, so "move to Ship when `ship` is added" is `event.labels.added contains ship`. An issue's change reports `work_item.updated`; a pull or merge request's reports `pull_request.updated`, whether it has a card of its own or is attached to an issue's card. Don't confuse the board event `pull_request.updated` (a label or assignee change) with the provider rule key `pullRequestUpdated`, which is a push to the pull request and fires the board event `pull_request.synchronized`.
1070
+
1071
+ - An update moves a card whatever its phase, like `synchronized`; use `card.phase` to move only from one phase.
1072
+ - Changes Factory itself makes (the card's own session, through the Factory app) while the card's run is in flight are held and evaluated once when the run ends, as one combined update. "After Triage labels it, move it" works without racing the agent. The dispatcher checks for the run end about every 10 seconds, so a held update lands within about 10 seconds of the run ending.
1073
+ - Changes from people and other sources aren't held for the run: they're evaluated about 5 seconds after the last change, with several changes to one item in that window combined into one update. Like every route move, a move into a phase that isn't terminal still waits for a run in flight to end; a move to a terminal phase goes at once.
1074
+ - A combined update carries the net change: adding `bug` and removing it again is no change, and nothing fires.
1075
+ - An update never cancels a close or reopen, nor is cancelled by one.
1076
+ - A rule moving a card changes the card, not the source, so it never produces an update. Factory's own status labels (`status: needs approval`, `status: auto-triaged`) are bookkeeping in the same way: adding or removing them never counts as a change, whoever does it.
1077
+ - An update to an item with no card runs intake only when intake turned the item away (Not routed). GitHub and GitLab check the item's Not routed record: an open issue or pull request no board took that is later labelled to match a board's rule lands on that board, and its record is resolved. A closed one stays unfiled. Linear, Jira and incident.io already run intake for an item with no card on every sync that sees it change.
1078
+
1079
+ | Provider | `work_item.updated` | `pull_request.updated` | Held for the card's run |
1080
+ | ----------- | ----------------------------------------------------------- | ------------------------------ | --------------------------------------------------------- |
1081
+ | GitHub | issue `labeled`, `unlabeled`, `assigned`, `unassigned` | pull request, own or attached | when the Factory app made the change |
1082
+ | GitLab | issue hook whose `changes` carry labels or assignees | merge request, own or attached | when made as the user Factory's GitLab connection acts as |
1083
+ | Linear | a sync whose labels or assignee differ from the last sync's | no | never: polling can't tell who made the change |
1084
+ | Jira | same as Linear | no | never |
1085
+ | incident.io | same as Linear | no | never |
1086
+
1087
+ Linear, Jira and incident.io diff each sync against the labels and assignee the previous sync recorded on the card. The first sync after upgrading only records them, so existing cards don't all fire at once. Each sync records when the provider last changed the item, in the same write that queues the update, so a sync older than the one recorded, or one racing a newer sync, never rolls the card's labels back or reports a change in reverse. GitLab does the same with each hook's `updated_at`, and a redelivered hook writes nothing.
1088
+
1030
1089
  #### Activity reaches the card's session
1031
1090
 
1032
1091
  A new comment on a card's GitHub or GitLab issue, or an edit to its title or description, tells the session working the card, with pointers only:
@@ -1056,7 +1115,7 @@ A stale `expectedRevision` is refused with `409 revision_mismatch`. Each route r
1056
1115
  curl -X POST "$FACTORY_URL/web/factory/projects/$PROJECT/intake-routes" -H 'content-type: application/json' -d '{
1057
1116
  "name": "Trusted issues to Triage",
1058
1117
  "when": { "operator": "AND", "conditions": [
1059
- { "field": "author.trusted", "operator": "equals", "value": true },
1118
+ { "field": "item.trusted", "operator": "equals", "value": true },
1060
1119
  { "field": "source.kind", "operator": "equals", "value": "issue" }
1061
1120
  ] },
1062
1121
  "target": { "boardKey": "work", "phaseKey": "triage" }
@@ -1154,7 +1213,7 @@ const overrides = { github: { issueCommentCreated: { onEvent: null } } };
1154
1213
  const github = new PlatformGithubIntegration({ rules: { issueCommentCreated: null } });
1155
1214
  ```
1156
1215
 
1157
- Board definitions own lifecycle, topology, phase-semantics, and tool-result rules; nothing is configured globally. `MastraFactory({ configVersion })` supplies the deployment-owned label stamped on audit records and GitHub evaluations; it is not a hash of custom handler code, not ingress identity, and does not change delivery replay semantics. Update `configVersion` when changing handler behavior.
1216
+ Board definitions own lifecycle, topology, phase-semantics, and tool-result rules; nothing is configured globally. `MastraFactory({ configVersion })` supplies the deployment-owned label recorded on transition audit events and passed to GitHub rule handlers; it is not a hash of custom handler code, not ingress identity, and does not change delivery replay semantics. Update `configVersion` when changing handler behavior.
1158
1217
 
1159
1218
  Handlers receive the existing typed GitHub context and return one decision or `undefined`. External titles, bodies, and comments remain untrusted data after webhook authentication. Custom handlers must preserve any required actor-permission checks explicitly.
1160
1219
 
@@ -1299,7 +1358,7 @@ const linear = new PlatformLinearIntegration({ rules: { issueClosed: null } });
1299
1358
 
1300
1359
  Linear event handlers are configured exclusively on the integration. Fetched issues, platform polling, and issue reconciliation use that instance's handlers. Defaults create intake items for observed open issues and close linked non-terminal Work items as Done or Canceled; closed unlinked issues do not create new items. Custom handlers receive the existing typed Linear context and return one decision or `undefined`. Treat issue titles, descriptions, and other external content as untrusted data.
1301
1360
 
1302
- `MastraFactory({ configVersion })` is the deployment-owned label stamped on Linear evaluations and audit records. Update it when handler behavior changes; it is neither ingress identity nor replay state.
1361
+ `MastraFactory({ configVersion })` is the deployment-owned label recorded on transition audit events and passed to Linear rule handlers. Update it when handler behavior changes; it is neither ingress identity nor replay state.
1303
1362
 
1304
1363
  ### GitHub review commands
1305
1364
 
@@ -1339,7 +1398,7 @@ Read tools and `factory_message_origin` are available on every turn. The other t
1339
1398
 
1340
1399
  `factory_switch_session_model` changes the model of a side, work item or review session you own in the same Factory, without recreating it. It refuses a model this server can't run. A running session switches right away; a stopped one uses the model on its next run.
1341
1400
 
1342
- `factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches (a project without Work: its first board's), stores the description that its runs start from, and subscribes the session. Name the `repository` when the Factory links more than one: a run can't start on a card that doesn't say which. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title, the description and the parent item. It can't pre-approve plans: a plan waits for a person unless the board's phase auto-approves it. Both refuse a repository the Factory doesn't link, and a card synced from an issue keeps the issue's repository. Stages, the board and role sessions aren't fields it edits; stages move with `factory_transition_work_item`. A session that moves a card follows it from then on, so it hears from the run the move starts. Subscriptions are stored per work item and session in the `factory_work_item_subscriptions` collection and are removed with the item, so any number of sessions can follow one item.
1401
+ `factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches (a project without Work: its first board's), stores the description that its runs start from, and subscribes the session. Name the `repository` when you know it. A run on a card that names none starts in the environment's first repository, determines from the card which repository it belongs to, and records it on the card with its first push or change request. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title, the description and the parent item. It can't pre-approve plans: a plan waits for a person unless the board's phase auto-approves it. Both refuse a repository the Factory doesn't link, and a card synced from an issue keeps the issue's repository. Stages, the board and role sessions aren't fields it edits; stages move with `factory_transition_work_item`. A session that moves a card follows it from then on, so it hears from the run the move starts. Subscriptions are stored per work item and session in the `factory_work_item_subscriptions` collection and are removed with the item, so any number of sessions can follow one item.
1343
1402
 
1344
1403
  #### Messaging between sessions
1345
1404
 
@@ -1354,7 +1413,7 @@ How a message is delivered depends on its priority. `urgent` always delivers, ev
1354
1413
  `factory_start_session` starts another session for the caller and sends `prompt` as its first message. It has two modes:
1355
1414
 
1356
1415
  - **Side session** (no `workItem`): a standalone session with no work item, for a one-off job. It uses the same repository as the session that started it. Factory stores that session on the new session's row (`origin_session_id`, `origin_thread_id`) and copies the parent's visibility. It runs on the model of the session that started it, or on `model` when one is passed. That model has to be one the session's credentials can run; an unknown or unrunnable model is refused before anything is created. When the parent has no model set, the side session keeps the Factory's default worker model.
1357
- - **Work-item role** (`workItem` and `role`): starts a role the item's board seats, the same way **Start** does in the Factory UI. The card does not move and no autonomy is armed. The tool refuses when the role already has a session, naming it so the agent can message it instead, and refuses an item linked to several repositories. The caller is subscribed to the item, and the run is recorded as `factory.run.started` with the caller as the person who started it.
1416
+ - **Work-item role** (`workItem` and `role`): starts a role the item's board seats, the same way **Start** does in the Factory UI. The card does not move and no autonomy is armed. The tool refuses when the role already has a session, naming it so the agent can message it instead. An item that names no repository among several starts in the environment's first repository, and the run determines from the card which one to work in. The caller is subscribed to the item, and the run is recorded as `factory.run.started` with the caller as the person who started it.
1358
1417
 
1359
1418
  A side session belongs to the caller and runs with the caller's credentials. A work-item role belongs to the caller only in a Factory on the `user` model scope. Where card work runs on the organization's keys (`factory` and `hybrid`), the role's session belongs to the Factory itself, as every phase session there does, whoever started or moved the card: the person is recorded as the one who started it, and their session follows the card so it hears when that run waits on someone and can approve or decline from there. Without an organization model key the start is refused with a message saying to add one. A work-item role keeps the Factory's default worker model. The first message runs with only the session's owner as its user, never the rest of the parent turn's context. The tool needs no approval but, like the other management tools, only appears on turns a signed-in person started.
1360
1419