@mastra/factory 0.28.0-alpha.3 → 0.28.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 (232) hide show
  1. package/README.md +110 -56
  2. package/dist/auth.d.ts.map +1 -1
  3. package/dist/auth.js +7 -1
  4. package/dist/auth.js.map +1 -1
  5. package/dist/boards/board-events.d.ts +1 -1
  6. package/dist/boards/board-events.d.ts.map +1 -1
  7. package/dist/boards/card-facts.d.ts +3 -1
  8. package/dist/boards/card-facts.d.ts.map +1 -1
  9. package/dist/boards/card-facts.js +26 -4
  10. package/dist/boards/card-facts.js.map +1 -1
  11. package/dist/boards/default-board.d.ts +2 -2
  12. package/dist/boards/default-board.js +2 -2
  13. package/dist/boards/default-board.js.map +1 -1
  14. package/dist/boards/define-board.d.ts +1 -1
  15. package/dist/boards/define-board.d.ts.map +1 -1
  16. package/dist/boards/define-board.js.map +1 -1
  17. package/dist/boards/intake-routing.d.ts +3 -5
  18. package/dist/boards/intake-routing.d.ts.map +1 -1
  19. package/dist/boards/intake-routing.js +3 -4
  20. package/dist/boards/intake-routing.js.map +1 -1
  21. package/dist/boards/project-boards.d.ts +18 -1
  22. package/dist/boards/project-boards.d.ts.map +1 -1
  23. package/dist/boards/project-boards.js +40 -3
  24. package/dist/boards/project-boards.js.map +1 -1
  25. package/dist/boards/semantics.d.ts +4 -4
  26. package/dist/boards/semantics.d.ts.map +1 -1
  27. package/dist/boards/semantics.js +8 -10
  28. package/dist/boards/semantics.js.map +1 -1
  29. package/dist/boards/work-migrations.d.ts +24 -1
  30. package/dist/boards/work-migrations.d.ts.map +1 -1
  31. package/dist/boards/work-migrations.js +97 -2
  32. package/dist/boards/work-migrations.js.map +1 -1
  33. package/dist/boards/work-routes.d.ts +6 -1
  34. package/dist/boards/work-routes.d.ts.map +1 -1
  35. package/dist/boards/work-routes.js +20 -6
  36. package/dist/boards/work-routes.js.map +1 -1
  37. package/dist/factory.d.ts +23 -0
  38. package/dist/factory.d.ts.map +1 -1
  39. package/dist/factory.js +62 -59
  40. package/dist/factory.js.map +1 -1
  41. package/dist/feed-events.d.ts +3 -2
  42. package/dist/feed-events.d.ts.map +1 -1
  43. package/dist/feed-events.js +3 -2
  44. package/dist/feed-events.js.map +1 -1
  45. package/dist/index.d.ts +3 -0
  46. package/dist/index.d.ts.map +1 -1
  47. package/dist/index.js +2 -1
  48. package/dist/integrations/github/default-rules.d.ts.map +1 -1
  49. package/dist/integrations/github/default-rules.js +3 -5
  50. package/dist/integrations/github/default-rules.js.map +1 -1
  51. package/dist/integrations/github/rules.d.ts +0 -6
  52. package/dist/integrations/github/rules.d.ts.map +1 -1
  53. package/dist/integrations/github/rules.js +23 -70
  54. package/dist/integrations/github/rules.js.map +1 -1
  55. package/dist/integrations/gitlab/routes.d.ts.map +1 -1
  56. package/dist/integrations/gitlab/routes.js +1 -3
  57. package/dist/integrations/gitlab/routes.js.map +1 -1
  58. package/dist/integrations/gitlab/rules.d.ts.map +1 -1
  59. package/dist/integrations/gitlab/rules.js +4 -9
  60. package/dist/integrations/gitlab/rules.js.map +1 -1
  61. package/dist/integrations/incidentio/agent-tools.js +5 -5
  62. package/dist/integrations/incidentio/agent-tools.js.map +1 -1
  63. package/dist/integrations/incidentio/default-rules.d.ts.map +1 -1
  64. package/dist/integrations/incidentio/default-rules.js.map +1 -1
  65. package/dist/integrations/incidentio/routes.d.ts +2 -2
  66. package/dist/integrations/incidentio/routes.d.ts.map +1 -1
  67. package/dist/integrations/incidentio/routes.js +10 -13
  68. package/dist/integrations/incidentio/routes.js.map +1 -1
  69. package/dist/integrations/incidentio/rules.d.ts +1 -3
  70. package/dist/integrations/incidentio/rules.d.ts.map +1 -1
  71. package/dist/integrations/incidentio/rules.js +1 -3
  72. package/dist/integrations/incidentio/rules.js.map +1 -1
  73. package/dist/integrations/jira/binding-scope.d.ts +5 -6
  74. package/dist/integrations/jira/binding-scope.d.ts.map +1 -1
  75. package/dist/integrations/jira/binding-scope.js +9 -11
  76. package/dist/integrations/jira/binding-scope.js.map +1 -1
  77. package/dist/integrations/jira/default-rules.d.ts.map +1 -1
  78. package/dist/integrations/jira/default-rules.js.map +1 -1
  79. package/dist/integrations/jira/routes.d.ts.map +1 -1
  80. package/dist/integrations/jira/routes.js +3 -5
  81. package/dist/integrations/jira/routes.js.map +1 -1
  82. package/dist/integrations/jira/rules.d.ts +1 -3
  83. package/dist/integrations/jira/rules.d.ts.map +1 -1
  84. package/dist/integrations/jira/rules.js +1 -3
  85. package/dist/integrations/jira/rules.js.map +1 -1
  86. package/dist/integrations/linear/default-rules.d.ts.map +1 -1
  87. package/dist/integrations/linear/default-rules.js.map +1 -1
  88. package/dist/integrations/linear/routes.d.ts.map +1 -1
  89. package/dist/integrations/linear/routes.js +11 -14
  90. package/dist/integrations/linear/routes.js.map +1 -1
  91. package/dist/integrations/linear/rules.d.ts +1 -3
  92. package/dist/integrations/linear/rules.d.ts.map +1 -1
  93. package/dist/integrations/linear/rules.js +1 -3
  94. package/dist/integrations/linear/rules.js.map +1 -1
  95. package/dist/integrations/platform/connect/session-tools.d.ts +5 -0
  96. package/dist/integrations/platform/connect/session-tools.d.ts.map +1 -1
  97. package/dist/integrations/platform/connect/session-tools.js +5 -0
  98. package/dist/integrations/platform/connect/session-tools.js.map +1 -1
  99. package/dist/integrations/platform/jira/routes.d.ts.map +1 -1
  100. package/dist/integrations/platform/jira/routes.js +3 -5
  101. package/dist/integrations/platform/jira/routes.js.map +1 -1
  102. package/dist/integrations/slack/run-error-card.js +1 -0
  103. package/dist/integrations/slack/run-error-card.js.map +1 -1
  104. package/dist/provider-display-name.d.ts.map +1 -1
  105. package/dist/provider-display-name.js +1 -0
  106. package/dist/provider-display-name.js.map +1 -1
  107. package/dist/routes/automation-runs.d.ts +1 -1
  108. package/dist/routes/automation-runs.js.map +1 -1
  109. package/dist/routes/config.d.ts +7 -1
  110. package/dist/routes/config.d.ts.map +1 -1
  111. package/dist/routes/config.js +105 -22
  112. package/dist/routes/config.js.map +1 -1
  113. package/dist/routes/contracts.d.ts +3 -10
  114. package/dist/routes/contracts.d.ts.map +1 -1
  115. package/dist/routes/contracts.js +11 -9
  116. package/dist/routes/contracts.js.map +1 -1
  117. package/dist/routes/intake-routes.d.ts.map +1 -1
  118. package/dist/routes/intake-routes.js +6 -1
  119. package/dist/routes/intake-routes.js.map +1 -1
  120. package/dist/routes/intake.d.ts +0 -23
  121. package/dist/routes/intake.d.ts.map +1 -1
  122. package/dist/routes/intake.js +13 -310
  123. package/dist/routes/intake.js.map +1 -1
  124. package/dist/routes/mastra-gateway.d.ts +19 -0
  125. package/dist/routes/mastra-gateway.d.ts.map +1 -0
  126. package/dist/routes/mastra-gateway.js +120 -0
  127. package/dist/routes/mastra-gateway.js.map +1 -0
  128. package/dist/routes/projects.d.ts.map +1 -1
  129. package/dist/routes/projects.js +1 -1
  130. package/dist/routes/projects.js.map +1 -1
  131. package/dist/routes/provider-credentials.d.ts +6 -1
  132. package/dist/routes/provider-credentials.d.ts.map +1 -1
  133. package/dist/routes/provider-credentials.js +32 -2
  134. package/dist/routes/provider-credentials.js.map +1 -1
  135. package/dist/routes/route.d.ts +6 -0
  136. package/dist/routes/route.d.ts.map +1 -1
  137. package/dist/routes/route.js.map +1 -1
  138. package/dist/routes/surface.d.ts.map +1 -1
  139. package/dist/routes/surface.js +0 -2
  140. package/dist/routes/surface.js.map +1 -1
  141. package/dist/routes/tenant-credentials.d.ts.map +1 -1
  142. package/dist/routes/tenant-credentials.js +5 -1
  143. package/dist/routes/tenant-credentials.js.map +1 -1
  144. package/dist/rules/dispatcher.d.ts +0 -5
  145. package/dist/rules/dispatcher.d.ts.map +1 -1
  146. package/dist/rules/dispatcher.js +18 -22
  147. package/dist/rules/dispatcher.js.map +1 -1
  148. package/dist/rules/rule-group.d.ts +1 -1
  149. package/dist/rules/rule-group.d.ts.map +1 -1
  150. package/dist/rules/rule-group.js +13 -5
  151. package/dist/rules/rule-group.js.map +1 -1
  152. package/dist/rules/transition-service.d.ts +2 -3
  153. package/dist/rules/transition-service.d.ts.map +1 -1
  154. package/dist/rules/transition-service.js +0 -1
  155. package/dist/rules/transition-service.js.map +1 -1
  156. package/dist/rules/types.d.ts +7 -11
  157. package/dist/rules/types.d.ts.map +1 -1
  158. package/dist/rules/types.js.map +1 -1
  159. package/dist/run-error.d.ts +1 -1
  160. package/dist/run-error.d.ts.map +1 -1
  161. package/dist/run-error.js +38 -5
  162. package/dist/run-error.js.map +1 -1
  163. package/dist/session/live-sessions.d.ts +11 -4
  164. package/dist/session/live-sessions.d.ts.map +1 -1
  165. package/dist/session/live-sessions.js +31 -10
  166. package/dist/session/live-sessions.js.map +1 -1
  167. package/dist/session/self-review-gate.d.ts +0 -2
  168. package/dist/session/self-review-gate.d.ts.map +1 -1
  169. package/dist/session/self-review-gate.js +1 -8
  170. package/dist/session/self-review-gate.js.map +1 -1
  171. package/dist/session/source-control-tools.d.ts +39 -13
  172. package/dist/session/source-control-tools.d.ts.map +1 -1
  173. package/dist/session/source-control-tools.js +54 -60
  174. package/dist/session/source-control-tools.js.map +1 -1
  175. package/dist/session/work-item-state-processor.d.ts +1 -4
  176. package/dist/session/work-item-state-processor.d.ts.map +1 -1
  177. package/dist/session/work-item-state-processor.js +5 -18
  178. package/dist/session/work-item-state-processor.js.map +1 -1
  179. package/dist/storage/domains/boards/base.d.ts +30 -8
  180. package/dist/storage/domains/boards/base.d.ts.map +1 -1
  181. package/dist/storage/domains/boards/base.js +43 -25
  182. package/dist/storage/domains/boards/base.js.map +1 -1
  183. package/dist/storage/domains/boards/schemas.js.map +1 -1
  184. package/dist/storage/domains/comments/base.d.ts.map +1 -1
  185. package/dist/storage/domains/comments/base.js +2 -2
  186. package/dist/storage/domains/comments/base.js.map +1 -1
  187. package/dist/storage/domains/comments/routes.d.ts.map +1 -1
  188. package/dist/storage/domains/comments/routes.js +4 -2
  189. package/dist/storage/domains/comments/routes.js.map +1 -1
  190. package/dist/storage/domains/intake/base.d.ts +5 -45
  191. package/dist/storage/domains/intake/base.d.ts.map +1 -1
  192. package/dist/storage/domains/intake/base.js +11 -89
  193. package/dist/storage/domains/intake/base.js.map +1 -1
  194. package/dist/storage/domains/projects/base.d.ts +17 -9
  195. package/dist/storage/domains/projects/base.d.ts.map +1 -1
  196. package/dist/storage/domains/projects/base.js +15 -7
  197. package/dist/storage/domains/projects/base.js.map +1 -1
  198. package/dist/storage/domains/work-items/base.d.ts +13 -11
  199. package/dist/storage/domains/work-items/base.d.ts.map +1 -1
  200. package/dist/storage/domains/work-items/base.js +37 -33
  201. package/dist/storage/domains/work-items/base.js.map +1 -1
  202. package/dist/storage/domains/work-items/board-version.d.ts +6 -2
  203. package/dist/storage/domains/work-items/board-version.d.ts.map +1 -1
  204. package/dist/storage/domains/work-items/board-version.js +20 -9
  205. package/dist/storage/domains/work-items/board-version.js.map +1 -1
  206. package/dist/work-items/providers/base.d.ts +4 -1
  207. package/dist/work-items/providers/base.d.ts.map +1 -1
  208. package/dist/work-items/providers/base.js +6 -1
  209. package/dist/work-items/providers/base.js.map +1 -1
  210. package/dist/work-items/providers/github.d.ts.map +1 -1
  211. package/dist/work-items/providers/github.js +2 -1
  212. package/dist/work-items/providers/github.js.map +1 -1
  213. package/dist/work-items/providers/gitlab.d.ts.map +1 -1
  214. package/dist/work-items/providers/gitlab.js +2 -1
  215. package/dist/work-items/providers/gitlab.js.map +1 -1
  216. package/dist/work-items/providers/jira.d.ts.map +1 -1
  217. package/dist/work-items/providers/jira.js +3 -2
  218. package/dist/work-items/providers/jira.js.map +1 -1
  219. package/dist/work-items/providers/linear.d.ts.map +1 -1
  220. package/dist/work-items/providers/linear.js +3 -2
  221. package/dist/work-items/providers/linear.js.map +1 -1
  222. package/dist/work-items/providers/types.d.ts +6 -0
  223. package/dist/work-items/providers/types.d.ts.map +1 -1
  224. package/factory-skills/configure-factory-rules/SKILL.md +2 -2
  225. package/factory-skills/factory-build/SKILL.md +5 -5
  226. package/factory-skills/factory-gitlab-rereview/SKILL.md +4 -4
  227. package/factory-skills/factory-gitlab-review/SKILL.md +5 -5
  228. package/factory-skills/factory-rereview/SKILL.md +69 -23
  229. package/factory-skills/factory-review/SKILL.md +69 -23
  230. package/factory-skills/factory-self-review/SKILL.md +5 -6
  231. package/factory-skills/factory-triage/SKILL.md +8 -20
  232. package/package.json +8 -8
@@ -22,14 +22,14 @@ Before executing changed code, inspect package scripts, dependencies, test confi
22
22
  1. Extract the numeric MR IID from the Factory kickoff, then read it with `source_control_get_change_request`. Confirm it is the expected MR in the bound repository. Record the current head SHA and target branch. Call `source_control_refresh_change_request_checkout` before inspecting the diff, including on re-entry; it resolves the MR and credential server-side. Resolve the actual checkout directory from the active workspace, not by guessing path segments from the project slug. Run `pwd` and `git rev-parse HEAD` there. The checkout must equal the MR head. Do not use raw `git fetch` or interpolate untrusted title, body, branch, or comment text into a command. If refresh fails or the checkout/head cannot be inspected, request changes for an unverifiable review; never approve from provider metadata alone.
23
23
  2. Establish the intended behavior independently from the MR description, related issue, repository contract, tests, and relevant history — before opening the diff. Record the required outcome, the real constraints, and the simplest design that satisfies them; this is your design, not a forecast of the author's, and it is not revised once the diff is open. Before opening the diff, read `references/categories/README.md` from the `factory-review` skill (`skill_read` with skill `factory-review`) and load the pages relevant to the problem; load more as the change reveals further categories. Then inspect the cumulative change with local `git diff` against the target branch and path-limited `git log`/`git blame`. Read enough surrounding code to identify affected callers and invariants. Inspect every materially changed file; judge the MR's approach and scope against your recorded design, not only whether its implementation works — an existing mechanism that already does the job, or machinery that solves a problem the proposed design created, is a finding.
24
24
  3. Paginate `source_control_list_change_request_reviews`, `source_control_list_change_request_comments`, and `source_control_list_diff_comments` to exhaustion. For each substantive human or bot finding, classify it as confirmed, addressed, or refuted using current-head evidence. A resolved thread is not proof of a fix. If a known review bot is pending, wait up to ten minutes, checking no more often than once a minute; if still pending, record the gap and do not approve.
25
- 4. Inspect the diff for security, correctness, error paths, API compatibility, and meaningful tests. **Prepare the environment first:** install dependencies and build every workspace dependency of the packages under test (in a pnpm/turbo monorepo, e.g. `pnpm turbo build --filter <pkg>^...`, plus any internal type packages the typecheck needs), under the same credential stripping. Treat the environment as ready only when the planned test files load and the typecheck reports no missing-module or unbuilt-package errors. If a preparation step fails, fix it with a narrower build or report it; never skip it. Execute the narrowest relevant verification and typecheck when applicable and safe. A non-code-only change with no application test harness may be verified with exact content, diff-integrity, and current-head checks; do not invent an inapplicable test requirement. Record exact commands, result, and current head SHA. CI status is advisory; a confirmed defect or failed local verification is not. If a direct run is impossible, provide a concrete source-path or recorded-response substitute and explain the limitation. Plan before running: list the tests, typecheck, and lint commands covering each changed package, and any behavior change no existing test covers. Call `source_control_publish_test_check` on the current full head SHA with `status: "in-progress"` and the plan as `summary`, run the plan, then publish the final status on the same head: `success` only when every planned command passed, `failure` when any failed, `neutral` when execution was blocked (static review only), `cancelled` when the head moved. Put per-command results in `summary` and failing test output in `details`. If the provider cannot publish commit checks or publishing is turned off for the project, continue without the check; the test report still carries the results. Run `git status --porcelain` before the tests and again before publishing `success`; if it prints anything, the tree is not the commit under review, so restore it to the head (or publish `neutral` naming the drift) rather than reporting a result for that SHA. GitLab commit statuses keep only a short description, so always put the full test report (plan, per-command results, failing output) in the verdict's Verification block, even when the status published. Then post one MR comment with `source_control_comment_change_request`, separate from the verdict, starting with `## Factory test report` and never with a `Verdict:` line. Structure it in this order. (1) A one-line **Result**: `All checks passed`, `Failed`, or `Verification incomplete`, followed by the tested head SHA. (2) A two- or three-sentence recap of what the change does and what the plan covered and why. (3) **Checks on this head**: a table with columns Check, Result, and Tests. Result is `✅ Passed` or `❌ Failed`. Tests reads like `216 passed, 1 skipped`, and each skip gets a short reason. Only commands run on the PR head go here. (4) **Regression proof**, only if you ran the new tests against the base code: one sentence saying that N of the new tests fail on the base code and pass on the head, so they catch the bug. Show this as `✅ Catches the bug`. Never put it in the table as a failure or show its exit code, because an expected failure on base is evidence for the PR. (5) **Not run**: each planned check you could not run, with the concrete reason and what would be needed to run it. Say whether this blocked approval. Omit the section when it is empty. (6) The check URL. Do not show raw exit codes or `x/y/z` counts. A reader should see a green table only when everything on the head passed. Approve only if every planned command ran and passed on the current head. A command that exited non-zero, a test file that failed to load, or a typecheck error blocks approval even when you attribute it to the environment or external CI is green. If it cannot be fixed, request changes and say plainly that verification could not be completed, naming the blocker. An environment failure is not a pass: any test file that fails to load, any missing build output, or any typecheck error, including ones outside the changed files, makes the command a failure in the table. Rebuild the missing dependency and run the command again. If it still cannot run, publish `neutral` with the blocker named in `title`, never `success`. Post a new report for each tested head, and reference it from the verdict.
25
+ 4. Inspect the diff for security, correctness, error paths, API compatibility, and meaningful tests. **Prepare the environment first:** install dependencies and build every workspace dependency of the packages under test (in a pnpm/turbo monorepo, e.g. `pnpm turbo build --filter <pkg>^...`, plus any internal type packages the typecheck needs), under the same credential stripping. Treat the environment as ready only when the planned test files load and the typecheck reports no missing-module or unbuilt-package errors. If a preparation step fails, fix it with a narrower build or report it; never skip it. Execute the narrowest relevant verification and typecheck when applicable and safe. A non-code-only change with no application test harness may be verified with exact content, diff-integrity, and current-head checks; do not invent an inapplicable test requirement. Record exact commands, result, and current head SHA. CI status is advisory; a confirmed defect or failed local verification is not. If a direct run is impossible, provide a concrete source-path or recorded-response substitute and explain the limitation. Plan before running: list the tests, typecheck, and lint commands covering each changed package, and any behavior change no existing test covers. Run the plan on the current head; if the head moves, re-plan on the new head. Put per-command results in `summary` and failing test output in `details`. Run `git status --porcelain` before the tests and again before posting the test report; if it prints anything, the tree is not the commit under review, so restore it to the head (or report `Verification incomplete` naming the drift) rather than reporting a result for that SHA. Always put the full test report (plan, per-command results, failing output) in the session handoff. Then post one MR comment with `source_control_comment_change_request`, separate from the verdict, starting with `## Factory test report` and never with a `Verdict:` line. Structure it like this. The line right after the `## Factory test report` heading is the result, `✅ All checks passed`, `❌ Failed`, or `⚠️ Verification incomplete`, followed by the full tested head SHA. Then a table with columns Check, Result, and Tests: Result is `✅ Passed` or `❌ Failed`, and Tests reads like `216 passed, 1 skipped`, with a short reason for each skip. Only commands run on this head go in the table. When the PR fixes a bug and the tests meant to reproduce it were also run against the base code, add a `New tests on base code` row whose Result is `✅ Catches the bug` when they fail there for the expected reason and pass on head, or `❌ Does not catch the bug` when they pass there. Add a **Not run:** line only when a planned check could not run, naming the reason and whether it blocked approval. No recap paragraph. Do not show raw exit codes or `x/y/z` counts. A reader should see a green table only when everything on the head passed. Approve only if every planned command ran and passed on the current head. A command that exited non-zero, a test file that failed to load, or a typecheck error blocks approval even when you attribute it to the environment or external CI is green. If it cannot be fixed, request changes and say plainly that verification could not be completed, naming the blocker. An environment failure is not a pass: any test file that fails to load, any missing build output, or any typecheck error, including ones outside the changed files, makes the command a failure in the table. Rebuild the missing dependency and run the command again. If it still cannot run, list it under **Not run** with the blocker named. Post a new report for each tested head, and reference it from the verdict.
26
26
  5. Before any verdict, scrutinize your own requested changes as critically as the MR: establish why each belongs in this MR, assume the author follows them exactly as written, and trace the result through affected callers and contracts — it must satisfy the required outcome without introducing another failure or unnecessary change. Where a probe's ability to detect the claimed failure is uncertain, run a broken control that isolates it, in a disposable worktree, and capture the command's own exit status. Before approval, challenge the strongest plausible failure case. Approval requires affirmative evidence that the checkout equals the current MR head, behavior is established, applicable local verification passed, prior and current reviewer findings are dispositioned, no known bot review is pending, behavior is meaningfully verified for this change, and the adversarial check did not reveal a blocker. A failed sandbox start, inaccessible checkout, missing diff, or unrun applicable tests fails this gate and requires changes. Never treat an inability to inspect as evidence that there are no defects. An assumption never resolves a confirmed finding. A request-changes verdict must name an actionable defect or verification gap; an inapplicable test suite or provider rejection of approval is not itself a defect in the MR.
27
27
 
28
28
  ## Verdict and handoff
29
29
 
30
30
  Before publishing the verdict, call `factory_review_source` (no arguments) once. It returns four fields, every one derived server-side from the bound work item:
31
31
 
32
- - `sessionUrl` — the Factory session URL that produced this review. This is the **only** field published on the MR (see the `Factory Session` block below).
32
+ - `sessionUrl` — the Factory session URL that produced this review. This is the **only** field published on the MR (see the footer below).
33
33
  - `triggeredBy` — the MR author recorded on the review card at intake. Do not publish this; it is an in-run cross-check input and a session-handoff entry only.
34
34
  - `reviewTarget` — the review card's own `{ integrationId, type, externalId, url }`. Do not publish this; it is an in-run cross-check input and a session-handoff entry only.
35
35
  - `boundRepository` — the project identity stamped on the review card at intake (`{ provider: 'gitlab', host, projectId }` here), or `null` when intake recorded none. Do not publish this; record it verbatim in the session handoff.
@@ -41,8 +41,8 @@ Otherwise, run the in-run cross-check:
41
41
  1. Compare `triggeredBy` with the MR author you already read (the GitLab username field). A mismatch means the session is bound to a different MR than the one being reviewed.
42
42
  2. Compare `reviewTarget.url` with the MR URL you read from `source_control_get_change_request`. Intake records the MR URL for every card (`gitlab/rules.ts:481` writes `url: mergeRequest.url ?? web_url ?? <constructed>`), so `reviewTarget.url` covers the normal case. If `reviewTarget.url` is `null` — a card stored without a URL — do **not** attempt to decode `reviewTarget.externalId`: the GitLab MR externalId is opaque `gitlab-pr:<base64url({version, host, projectId, mergeRequestIid})>` (`gitlab/routes.ts:94`, `gitlab/rules.ts:109`), with no documented way to check it against an MR IID. The bound identity itself is not the gap — the tool returns the intake-stamped `boundRepository` (`{ provider: 'gitlab', host, projectId }`), and the MR fetch is already binding-scoped (`session/source-control-tools.ts` resolves the repository from the session record, so `source_control_get_change_request` cannot return another project's MR). What is missing is a fetch-side value to compare it against: the normalized change-request result carries no numeric project id or intake identifier, and a matching `triggeredBy` author cannot distinguish two MRs by the same author within the project. With no URL, nothing confirms the fetched MR **is the card's MR**. Do not publish: record the `reviewTarget.url` gap and both raw values in the session handoff, skip the verdict call, and hand off to a human.
43
43
 
44
- On any mismatch, stop and record it as a blocking security finding with both values verbatim. Do **not** publish anything on the MR — a mismatch means the fetched MR may not be the session's bound target, and posting any verdict (a request-changes comment included) puts a review on an MR that may be the wrong one. Re-read the MR with `source_control_get_change_request` once and re-run this cross-check; publish only if the fresh check matches. If it still mismatches, hand off without publishing: record the mismatch in the **Factory routing** block, skip the verdict call, and hand off to a human. When publication does proceed, include only `sessionUrl` as a `Factory Session` section at the end of every published body (approve, request-changes comment, and the approval-fallback comment) so a misattributed review can be traced back to its run. `triggeredBy` and `reviewTarget` stay in the session handoff, never on the MR.
44
+ On any mismatch, stop and record it as a blocking security finding with both values verbatim. Do **not** publish anything on the MR — a mismatch means the fetched MR may not be the session's bound target, and posting any verdict (a request-changes comment included) puts a review on an MR that may be the wrong one. Re-read the MR with `source_control_get_change_request` once and re-run this cross-check; publish only if the fresh check matches. If it still mismatches, hand off without publishing: record the mismatch in the **Factory routing** block, skip the verdict call, and hand off to a human. When publication does proceed, end every published body with the footer `<sub>[Factory session](<sessionUrl>)</sub>`, the only routing fact published (approve, request-changes comment, and the approval-fallback comment) so a misattributed review can be traced back to its run. `triggeredBy` and `reviewTarget` stay in the session handoff, never on the MR.
45
45
 
46
- Use `source_control_review_change_request` on the same IID and current `commitId` when available. Compose the body fresh in this pass — never reuse a body from an earlier pass. Its first line is the verdict line (`Verdict: approve` or `Verdict: request changes`) and its second line is `Reviewed head: <full SHA>` naming the head you verified, which must equal the current MR head, the `commitId`, and the `reviewedHeadSha` you record. The tool rejects a body whose verdict line contradicts `event` or whose `Reviewed head:` is not the current head; treat that rejection as a stale body — regenerate it from this pass's findings, never flip the event to match it. For an approve verdict use `event: "approve"`. GitLab cannot represent a GitHub-style request-changes review: for a blocking verdict use `event: "comment"` and start the body with `Verdict: request changes`, followed by concrete findings and evidence. Do not claim that a comment blocks merging. Use the approval fallback only for a confirmed authorization rejection — for example, the current account authored the MR or lacks review permission. In that case re-read the MR with `source_control_get_change_request` and confirm its head still equals the head you reviewed — if it moved, do not post the fallback; refresh and re-run the review gates against the new head. Otherwise make a separate `source_control_comment_change_request` call with a body beginning `Verdict: approve (approval not recorded)`, then `Reviewed head: <full SHA>` naming that verified head, and name the provider rejection in the handoff; never claim the MR was formally approved. For any other rejection (stale `commitId`, changed head, invalid request), refresh the checkout and re-establish the current head, then re-run the substantive review — the diff, finding validation, applicable verification, and approval gates — before retrying publication. Never publish an approval evaluated against a head that has since changed. If the gates cannot be re-run on the refreshed head, report that no verdict was posted. Confirm that the comment call succeeded before the handoff or verdict call. If publication fails, report that failure and do not imply a verdict was posted. Where useful, anchor a specific finding with `source_control_create_diff_comment`, but keep a complete verdict in the top-level review.
46
+ Use `source_control_review_change_request` on the same IID and current `commitId` when available. Compose the body fresh in this pass — never reuse a body from an earlier pass. The body is short: every line has to earn its place, with plain words, no jargon, no restating the diff, and no praise. Line 1 is `## Verdict: approve` or `## Verdict: request changes` and nothing else; line 2 is `Reviewed head: <full SHA>` equal to the current MR head, the `commitId`, and the `reviewedHeadSha` you record. Then one sentence of at most 25 words saying what blocks the merge or why it is safe to merge. Then a findings table with columns #, Severity (triage dot scale, dots then the word: `●○○○ low`, `●●○○ medium`, `●●●○ high`, `●●●● critical`), Blocks merge (`Yes` or `No`, decided separately from severity), Type (Correctness, Security, Tests, Design, Scope, Compatibility, Docs, Merge conflict, or Verification), Finding (what breaks, for whom, and why, in one or two sentences), and Where (a linked `file:line`), blocking rows first, then by severity; omit the table when there are no findings. On request changes, add `### Required changes`: one numbered, linked `file:line` entry per change, in table order, one sentence, imperative and present tense, with no softened requests and no optional tiers. Link every `file:line` in the body to that line at the reviewed head (`[`stream.ts:42`](<project web URL>/-/blob/<full head SHA>/src/stream.ts#L42)`), showing the shortest unambiguous path as the link text; link removed lines at the base SHA. A change with no code location (a failed check or verification gap) gets no link. Add `### Needs a decision` only for questions only a person can answer. Put the test report's result line (the line after its heading), earlier-review dispositions (addressed or refuted only; confirmed ones are table rows), and the one-line adversarial check (approve only) in one collapsed `<details><summary>Review notes</summary>` block. Everything else stays in the session handoff. The tool rejects a body whose verdict line contradicts `event` or whose `Reviewed head:` is not the current head; treat that rejection as a stale body — regenerate it from this pass's findings, never flip the event to match it. For an approve verdict use `event: "approve"`. GitLab cannot represent a GitHub-style request-changes review: for a blocking verdict use `event: "comment"` and start the body with `## Verdict: request changes`, followed by concrete findings and evidence. Do not claim that a comment blocks merging. Use the approval fallback only for a confirmed authorization rejection — for example, the current account authored the MR or lacks review permission. In that case re-read the MR with `source_control_get_change_request` and confirm its head still equals the head you reviewed — if it moved, do not post the fallback; refresh and re-run the review gates against the new head. Otherwise make a separate `source_control_comment_change_request` call with a body beginning `## Verdict: approve (approval not recorded)`, then `Reviewed head: <full SHA>` naming that verified head, and name the provider rejection in the handoff; never claim the MR was formally approved. For any other rejection (stale `commitId`, changed head, invalid request), refresh the checkout and re-establish the current head, then re-run the substantive review — the diff, finding validation, applicable verification, and approval gates — before retrying publication. Never publish an approval evaluated against a head that has since changed. If the gates cannot be re-run on the refreshed head, report that no verdict was posted. Confirm that the comment call succeeded before the handoff or verdict call. If publication fails, report that failure and do not imply a verdict was posted. Where useful, anchor a specific finding with `source_control_create_diff_comment`, but keep a complete verdict in the top-level review.
47
47
 
48
- After the review publication attempt, call `factory_record_review_verdict` with the published `verdict` and the verified `reviewedHeadSha`. The card stays in its review phase; never request a stage transition to end the review. If the call is rejected, address the stated reason before retrying. Then, as the terminal action, give the session handoff and report whether the card was updated. In the session handoff, include MR URL and head SHA, verdict and whether GitLab recorded it, goal, findings with file/line evidence, prior-review disposition, commands/results, assumptions, open questions, any verification limitation, the `Factory Session` block (`sessionUrl` only, matching the MR body), and a **Factory routing** block that records `triggeredBy` verbatim, `reviewTarget` verbatim (`integrationId`, `type`, `externalId`, `url`), `boundRepository` verbatim, and the cross-check outcome — "matched" with the compared MR value or "mismatch: <blocking-finding-ref>".
48
+ After the review publication attempt, call `factory_record_review_verdict` with the published `verdict` and the verified `reviewedHeadSha`. The card stays in its review phase; never request a stage transition to end the review. If the call is rejected, address the stated reason before retrying. Then, as the terminal action, give the session handoff and report whether the card was updated. In the session handoff, include MR URL and head SHA, verdict and whether GitLab recorded it, goal, findings with file/line evidence, prior-review disposition, commands/results, assumptions, open questions, any verification limitation, the published `sessionUrl`, and a **Factory routing** block that records `triggeredBy` verbatim, `reviewTarget` verbatim (`integrationId`, `type`, `externalId`, `url`), `boundRepository` verbatim, and the cross-check outcome — "matched" with the compared MR value or "mismatch: <blocking-finding-ref>".
@@ -11,7 +11,7 @@ Re-review the pull request behind this Factory work item after new commits were
11
11
 
12
12
  You are working in a bound Factory session. Complete the full re-review in one pass, then make `factory_record_review_verdict` your terminal step — one call, repeated only if it is rejected and only with the rejection reason addressed. Never wait for or solicit human input mid-run; every judgment call is yours to resolve.
13
13
 
14
- **Decision rule:** at every fork — did the push actually address a prior finding, is a new pattern deviation deliberate, is the incremental scope creep — pick the answer the history and codebase conventions best support, proceed, and **record the decision as an assumption** for the terminal handoff. Requested changes and decisions a human must make go in the handoff's open questions.
14
+ **Decision rule:** at every fork — did the push actually address a prior finding, is a new pattern deviation deliberate, is the incremental scope creep — pick the answer the history and codebase conventions best support, proceed, and **record the decision as an assumption** for the terminal handoff. Changes the author must make go under **Required changes**, and decisions only a human can make go under **Needs a decision**.
15
15
 
16
16
  Assumptions are for _interpretive_ calls only — was a prior finding meaningfully addressed, is a loose new assertion justified. **A confirmed finding may never be resolved by recording an assumption**: if you verified a defect (prior or new), it stays a finding and weighs into the verdict; writing "treated as non-blocking" next to it does not make it non-blocking.
17
17
 
@@ -76,8 +76,25 @@ If you suspect a regression, don't speculate — construct a repro against the p
76
76
 
77
77
  - `gh pr checks` — CI status on the current head (build, typecheck, tests). Report red, missing, and still-running CI as advisory findings; CI status alone cannot block approval or create a requested change. Inspect failures for evidence of a defect, but only a defect you confirm or a failed verification you run yourself can block the verdict.
78
78
  - **Run it yourself, against the current head.** After the pre-execution inspection from the security section clears the push's diff, check out the PR branch in the session sandbox at the current head and execute the narrowest test suite and typecheck covering the changed packages (e.g. `pnpm --filter <pkg> test`). **Strip credentials from everything the PR's code runs under:** prefix every install/build/test/typecheck command with `env -u GH_TOKEN -u GITHUB_TOKEN` (e.g. `env -u GH_TOKEN -u GITHUB_TOKEN pnpm --filter <pkg> test`) so the PR's scripts and tests cannot read the session's GitHub credentials. Tests never legitimately need those tokens — a test that fails only because they are missing is itself a finding. A prior pass that ran the tests does not clear this pass — the pushed commits are new code, and verification is re-run every pass. Record every command and its outcome for the handoff. If something prevented you from executing anything, the handoff must say so explicitly — a re-review that ran nothing is a weaker re-review and must not hide it.
79
- - **Plan, run, and publish the test check.** Before running anything, write a test plan from the diff: for each changed package, list the test files that exercise the changed code (colocated tests, callers' tests, integration/E2E suites that cross the change), the typecheck/lint commands, and any gap where no existing test covers a behavior change. Prefer the narrowest commands that fully cover the change; widen only when the change is cross-cutting. **Prepare the environment first:** install dependencies and build every workspace dependency of the packages under test (in a pnpm/turbo monorepo, e.g. `pnpm turbo build --filter <pkg>^...`, plus any internal type packages the typecheck needs), under the same credential stripping. Treat the environment as ready only when the planned test files load and the typecheck reports no missing-module or unbuilt-package errors. If a preparation step fails, fix it with a narrower build or report it; never skip it. Immediately before the first command, call `source_control_publish_test_check` with the current full head SHA, `status: "in-progress"`, and the plan as `summary`. Execute the plan and record each command, its exit status, and the pass/fail/skip counts. When done, call `source_control_publish_test_check` again on the same head with `success` (every planned command passed), `failure` (any command failed or a test you ran reproduced a defect), `neutral` (execution was blocked by the security inspection or the environment — static review only), or `cancelled` (the head moved; re-plan on the new head). Put a one-line result in `title`, the test report's Checks on this head table and Regression proof line in `summary`, and failing test names with trimmed output in `details`. Never report `success` for commands you did not run, and never publish for a head other than the one you tested. An environment failure is not a pass: any test file that fails to load, any missing build output, or any typecheck error, including ones outside the changed files, makes the command a failure in the table. Rebuild the missing dependency and run the command again. If it still cannot run, publish `neutral` with the blocker named in `title`, never `success`. If the tool reports the provider cannot publish commit checks or publishing is turned off for the project, continue without the check; the test report comment below still carries the results. Run `git status --porcelain` before the tests and again before publishing `success`; if it prints anything, the tree is not the commit under review, so restore it to the head (or publish `neutral` naming the drift) rather than reporting a result for that SHA.
80
- - **Post the test report after the check publication attempt, whether or not it succeeded; include the check URL only when publication succeeded.** Before listing, updating, or posting any test report, run the Phase 6 `factory_review_source` cross-check; if the tool is unavailable, fails, returns an unexpected shape, or the target mismatches, post no test report on this PR and record why in the session handoff. After the final check is published, publish one PR comment, separate from the verdict. Start it with `## Factory test report` and never with a `Verdict:` line, because Factory reads verdicts only from the verdict post. Structure it in this order. (1) A one-line **Result**: `All checks passed`, `Failed`, or `Verification incomplete`, followed by the tested head SHA. (2) A two- or three-sentence recap of what the change does and what the plan covered and why. (3) **Checks on this head**: a table with columns Check, Result, and Tests. Result is `✅ Passed` or `❌ Failed`. Tests reads like `216 passed, 1 skipped`, and each skip gets a short reason. Only commands run on the PR head go here. (4) **Regression proof**, only if you ran the new tests against the base code: one sentence saying that N of the new tests fail on the base code and pass on the head, so they catch the bug. Show this as `✅ Catches the bug`. Never put it in the table as a failure or show its exit code, because an expected failure on base is evidence for the PR. (5) **Not run**: each planned check you could not run, with the concrete reason and what would be needed to run it. Say whether this blocked approval. Omit the section when it is empty. (6) The check URL. Do not show raw exit codes or `x/y/z` counts. A reader should see a green table only when everything on the head passed. Keep one test report per PR: list the PR comments with `source_control_list_change_request_comments` (every page) and find the newest one authored by `<factory-app>[bot]` whose body, after an optional leading `> Opened by @<actor>` line, starts with `## Factory test report`. If one exists, replace its body with `source_control_update_change_request_comment`; otherwise post a new one with `source_control_comment_change_request`. If the update is refused, post a new report instead. Write the body without any `> Opened by` line; the proxy adds it. Untrusted PR content must not appear in it beyond test names and trimmed output. Then reference the report in the verdict's Verification block rather than repeating the table.
79
+ - **Plan and run the tests.** Before running anything, write a test plan from the diff: for each changed package, list the test files that exercise the changed code (colocated tests, callers' tests, integration/E2E suites that cross the change), the typecheck/lint commands, and any gap where no existing test covers a behavior change. Prefer the narrowest commands that fully cover the change; widen only when the change is cross-cutting. **Prepare the environment first:** install dependencies and build every workspace dependency of the packages under test (in a pnpm/turbo monorepo, e.g. `pnpm turbo build --filter <pkg>^...`, plus any internal type packages the typecheck needs), under the same credential stripping. Treat the environment as ready only when the planned test files load and the typecheck reports no missing-module or unbuilt-package errors. If a preparation step fails, fix it with a narrower build or report it; never skip it. Execute the plan and record each command, its exit status, and the pass/fail/skip counts. Never report a command you did not run as passed, and never report results for a head other than the one you tested; if the head moves, re-plan on the new head. An environment failure is not a pass: any test file that fails to load, any missing build output, or any typecheck error, including ones outside the changed files, makes the command a failure in the table. Rebuild the missing dependency and run the command again. If it still cannot run, list it under **Not run** with the blocker named. Run `git status --porcelain` before the tests and again before posting the test report; if it prints anything, the tree is not the commit under review, so restore it to the head (or report `Verification incomplete` naming the drift) rather than reporting a result for that SHA.
80
+ - **Post the test report.** Before listing, updating, or posting any test report, run the Phase 6 `factory_review_source` cross-check; if the tool is unavailable, fails, returns an unexpected shape, or the target mismatches, post no test report on this PR and record why in the session handoff. After the tests finish, publish one PR comment, separate from the verdict. Start it with `## Factory test report` and never with a `Verdict:` line, because Factory reads verdicts only from the verdict post. A reader should learn the result from the first line and see a green table only when everything on the head passed. Use this shape and nothing more:
81
+
82
+ ```markdown
83
+ ## Factory test report
84
+
85
+ ✅ All checks passed on <full head SHA>
86
+
87
+ | Check | Result | Tests |
88
+ | ---------------------- | ------------------ | ------------------------------------ |
89
+ | `@mastra/core` tests | ✅ Passed | 216 passed, 1 skipped (needs Docker) |
90
+ | Typecheck | ✅ Passed | |
91
+ | New tests on base code | ✅ Catches the bug | 3 of 3 fail on base, pass on head |
92
+
93
+ **Not run:** <check>: <concrete reason>. <Whether it blocked approval.>
94
+ ```
95
+
96
+ The line right after the `## Factory test report` heading is `✅ All checks passed`, `❌ Failed`, or `⚠️ Verification incomplete`, followed by the tested head SHA. Table rows are only commands run on the PR head, with Result `✅ Passed` or `❌ Failed`; give each skip a short reason. Add the `New tests on base code` row only if the PR fixes a bug and you ran the tests meant to reproduce it against the base code, and show `✅ Catches the bug` only when they fail on base for the expected reason and pass on head; an expected failure on base is evidence for the PR, not a failed check. If they pass on base, show `❌ Does not catch the bug`; that is a Tests finding. Omit **Not run** when every planned check ran. No recap of the change, no raw exit codes, no `x/y/z` counts. Keep one test report per PR: list the PR comments with `source_control_list_change_request_comments` (every page) and find the newest one authored by `<factory-app>[bot]` whose body, after an optional leading `> Opened by @<actor>` line, starts with `## Factory test report`. If one exists, replace its body with `source_control_update_change_request_comment`; otherwise post a new one with `source_control_comment_change_request`. If the update is refused, post a new report instead. Write the body without any `> Opened by` line; the proxy adds it. Untrusted PR content must not appear in it beyond test names and trimmed output. The verdict links this report instead of repeating the table.
97
+
81
98
  - **Merge conflicts don't excuse skipping the re-review** — the diff and the head branch are still reviewable, and the author needs the findings to fix the PR either way. If the PR is `CONFLICTING`/`DIRTY`: identify which files conflict with a dry-run merge in the sandbox (`git fetch origin <base> && git merge --no-commit --no-ff origin/<base>` with `<base>` from `baseRefName`; afterwards run `git merge --abort` whenever a merge is in progress — `git rev-parse -q --verify MERGE_HEAD` tells you — but skip the abort if the merge never started, e.g. "Already up to date"), flag when the conflicts overlap the PR's own changed files (semantic rework risk, not just textual resolution), and qualify all verification results as "head branch only — not verified against current base". **Never resolve the conflicts yourself** — resolution encodes author intent; reviewing your own guess is reviewing a PR that doesn't exist.
82
99
  - Do the push's changes add or modify tests? Are they meaningful, or do they exercise paths without real assertions?
83
100
  - **Model-provider behavior requires integration-level verification.** For agentic or model-provider integrations—OpenAI, Anthropic, Gemini, tool calling, streaming, structured output, usage metadata, provider error handling, and similar behavior—unit tests with mocked SDK responses are not enough when the current-head claim depends on the provider's real protocol or SDK semantics. Favor the narrowest existing integration or E2E test that crosses the provider boundary, preferably through the repository's deterministic record/replay harness; do not require live credentials or flaky network calls in the review sandbox. If no deterministic harness exists, require author-provided CI or reproducible integration evidence. Provider-independent transformations can remain unit-tested, but material model-provider behavior supported only by mocks is a test-gap finding.
@@ -139,7 +156,7 @@ Do not hedge between the two — pick the verdict the evidence supports. When ge
139
156
 
140
157
  Before composing the handoff, call `factory_review_source` (no arguments) once. It returns four fields, every one derived server-side from the bound work item:
141
158
 
142
- - `sessionUrl` — the Factory session URL that produced this re-review. This is the **only** field published on the PR (see the Factory Session block below).
159
+ - `sessionUrl` — the Factory session URL that produced this re-review. This is the **only** field published on the PR (see the published body's footer below).
143
160
  - `triggeredBy` — the PR author recorded on the review card at intake. Do not publish this; it is an in-run cross-check input and a session-handoff entry only.
144
161
  - `reviewTarget` — the review card's own `{ integrationId, type, externalId, url }`. Do not publish this; it is an in-run cross-check input and a session-handoff entry only.
145
162
  - `boundRepository` — the repository identity stamped on the review card at intake (`{ provider: 'github', repositoryId }` here), or `null` when intake recorded none. Do not publish this; it is the binding-side input to the null-`url` fallback below.
@@ -155,23 +172,52 @@ On any mismatch, stop and record it as a blocking security finding with both val
155
172
 
156
173
  Compose two artifacts, in order — the **published body** goes on the PR, the **session handoff** goes back into the run's conversation. Don't send either to the conversation yet; both are drafted here, the published body is sent to the PR, the verdict is recorded, and only then is the session handoff posted.
157
174
 
158
- The **published body** (what `gh pr review --body-file` receives) **must open with the verdict line**: `Verdict: approve` or `Verdict: request changes`, then on the next line `Reviewed head: <full 40-character SHA>` naming the exact head you verified, followed by:
175
+ The **published body** (what `gh pr review --body-file` receives) is what the author reads, often from a notification. Every line has to earn its place: plain words, no jargon, no restating the diff, no praise, nothing about the author. The verdict comes first and the findings come next; anything a reader does not need in order to act or to trust the verdict stays in the session handoff. Use this shape, dropping each optional part that would be empty:
176
+
177
+ ```markdown
178
+ ## Verdict: request changes
179
+
180
+ Reviewed head: <full 40-character SHA>
181
+
182
+ <One sentence: what blocks the merge, or why it is safe to merge.>
183
+
184
+ | # | Severity | Blocks merge | Type | Finding | Where |
185
+ | --- | --------- | ------------ | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
186
+ | 1 | ●●●○ high | Yes | Correctness | <What breaks, for whom, and why.> | [`stream.ts:42`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.ts#L42) |
187
+ | 2 | ●○○○ low | No | Tests | <What is missing and what it would catch.> | [`stream.test.ts:10`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.test.ts#L10) |
188
+
189
+ ### Required changes
190
+
191
+ 1. [`stream.ts:42`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.ts#L42): <Imperative change.>
192
+
193
+ ### Needs a decision
194
+
195
+ - <Question only a person can answer, and the answer this re-review assumed.>
196
+
197
+ <details>
198
+ <summary>Review notes</summary>
199
+
200
+ - **Tests:** <The test report's result line (the line after its heading), linked to the report.>
201
+ - **Last review:** <Each prior-pass finding the push addressed, refuted, or made obsolete, by subject and `file:line`, with the commit or evidence in a few words.>
202
+ - **Earlier reviews:** <Reviewer, subject, `file:line`: addressed or refuted, with the evidence in a few words.>
203
+ - **Why approve:** <The strongest case for request changes, and why it fails.>
204
+
205
+ </details>
159
206
 
160
- - **Prior pass disposition** — every substantive item from your previous review, classified: addressed, partially addressed, still open, refuted by the push, or invalidated by the push. Cite the commit or `file:line` proving each addressed/refuted/invalidated call. A prior blocking finding still open is called out plainly at the top of this section.
161
- - **Findings** — lead with the mechanism of the most consequential finding; new-this-pass findings from the push and from the fresh whole-PR sweep are each labeled as `[push]` or `[fresh]` so the record is honest about where they came from. Distill — this is a handoff, not a transcript.
162
- - **Approach** — the required outcome and the simplest sufficient design from your Phase 1 record (recovered or rewritten), and whether the PR's approach and scope — with the push folded in — are justified against it. Agreement stated in one line; disagreement with the evidence that supports the alternative.
163
- - **Issue and intent** — the authorizing issue, current PR classification, current approval-label state, and whether the cumulative implementation and scope match the independently established contract and approved discussion. State what changed from the prior issue/intent understanding, if anything.
164
- - **Verification** — every command you executed against the current head (tests, typecheck, repros) with its outcome, including base-versus-current-head evidence for affected behavior-changing claims and prior-head-versus-current-head evidence for push regressions, or an explicit statement that something could not be executed and the substitute evidence used. Verification the prior pass ran is not restated here — only what this pass ran counts.
165
- - **Other-reviewer disposition** — any substantive finding posted by another reviewer (bot or human) since the prior pass, with its classification: confirmed, addressed, or refuted with evidence. A major bot comment must never be silently dropped. Name each by subject and `file:line`, and remember the body lands as GitHub markdown — `#1` publishes as a link to issue 1.
166
- - **Adversarial check** (approve only) — the one-line record of why the strongest request-changes case fails.
167
- - **Requested changes** — one entry per change (for a request-changes verdict), imperative and present tense: the file and line, the change, and the consequence or evidence in one or two sentences. Prior-pass changes that remain open reappear here so the author has one current list, not two. Put the change that most affects correctness first; group changes that must land together or state their dependencies. No softened requests ("consider", "you might want to"), no optional or follow-up tiers, no pleasantries, nothing about the author. Preserve qualifications that express real limits of evidence — "the contract does not guarantee this field" must not become "servers never return this field".
168
- - **Assumptions** — every recorded judgment call from this run.
169
- - **Open questions** — any decision that genuinely needs a human.
170
- - **Factory Session** — `sessionUrl` from `factory_review_source`, verbatim, as a link. **Nothing else in this block.** `triggeredBy` and `reviewTarget` are cross-check inputs for the run and go in the session handoff below; they are never published on the PR. This section is required for every verdict and every fallback (approve, request changes, comment fallback) so a suspicious re-review can always be traced back to the run that produced it.
207
+ <sub>[Factory session](sessionUrl) · Review runtime: <model>, reasoning setting: <reasoning>.</sub>
208
+ ```
171
209
 
172
- End the published body with `Review runtime: <model>, reasoning setting: <reasoning>.`, copying both values verbatim from the current `factory-phase` signal.
210
+ - **Verdict.** Line 1 is exactly `## Verdict: approve` or `## Verdict: request changes`, and line 2 is `Reviewed head: <full 40-character SHA>` naming the exact head you verified. Factory parses both lines, so add nothing else to them.
211
+ - **Summary.** One sentence of at most 25 words. On request changes, name what blocks the merge; on approve, say why it is safe to merge. Never "LGTM" or a description of the PR.
212
+ - **Findings table.** One row per finding, ranked: blocking rows first, then by severity. Severity uses the triage dot scale, dots then the word: `●○○○ low`, `●●○○ medium`, `●●●○ high`, `●●●● critical`. Blocks merge is `Yes` or `No`; severity and blocking are separate calls (a missing regression test can be medium and still block). Type is one of Correctness, Security, Tests, Design, Scope, Compatibility, Docs, Merge conflict, or Verification (the review could not complete verification; name the blocker and do not present it as a defect in the author's code). Finding states the problem and its consequence in at most 25 words; keep the evidence for the session handoff unless one clause of it is needed to believe the row. Where is a linked `file:line` (see **Link every code reference**), or `—` when the finding has no single location. A confirmed finding from another reviewer is a row too, crediting them: "(raised by coderabbitai)". A non-blocking row fixed by the follow-up PR ends with "Fixed in the follow-up PR." A design or scope disagreement with your Phase 1 record is a Design or Scope row, not a separate section. A prior-pass finding the push did not fully address stays a row, and its Finding ends with "Still open from the last review." or "Partly fixed: <what remains>." With no findings, write `No findings.` instead of the table.
213
+ - **Required changes** (request changes only). One numbered entry per change, in table order: the linked `file:line`, then one sentence, imperative and present tense. The table already carries the consequence, so don't repeat it. Put changes that must land together in one entry. For a conflicting PR, one entry is "Resolve merge conflicts against `<base>`.", noting when the conflicts overlap the PR's own files. No softened requests ("consider", "you might want to"), no optional or follow-up tiers, no pleasantries. Preserve qualifications that express real limits of evidence: "the contract does not guarantee this field" must not become "servers never return this field".
214
+ - **Needs a decision.** Only questions that genuinely need a person. Omit the section otherwise.
215
+ - **Review notes.** Collapsed, and only what a reader may need to trust the verdict. **Tests** is always present. **Last review** lists only prior-pass findings the push addressed, refuted, or invalidated; findings still open are table rows. Omit it when there are none. **Earlier reviews** lists only findings other reviewers (bots included) posted since the prior pass that are addressed or refuted; confirmed ones are table rows. Omit it when there are none. **Why approve** is the one-line adversarial check record, approve only. Nothing else goes here.
216
+ - **Link every code reference.** Each `file:line` in the published body is a link to that line at the reviewed head: `[`stream.ts:42`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.ts#L42)`, with `#L40-L44` for a range. Use the full head SHA in the URL, never a branch name, so the link still shows what you reviewed after more pushes. Show the shortest path that is unambiguous in the PR (usually the file name) as the link text; the link carries the full path. A reference to a removed line links to the base SHA instead, and code from an earlier review that the latest pushes removed links to that review's reviewed head SHA. A change with no code location (an unpushed branch, a failed check, a verification gap) gets no link: state the change in one sentence. A reference to another reviewer's comment links to that comment.
217
+ - **GitHub markdown.** `#1` publishes as a link to issue 1, so name findings by subject and `file:line`, never by `#n`.
218
+ - **Footer.** `sessionUrl` from `factory_review_source`, verbatim, as the Factory session link. It is the only routing fact published: `triggeredBy`, `reviewTarget`, and `boundRepository` are cross-check inputs for the run and are never published on the PR. The footer is required on every verdict and every fallback (approve, request changes, comment fallback), so a suspicious re-review — one that lands on the wrong PR, or approves and requests changes at once — can always be traced back to the run that produced it. Copy both runtime values verbatim from the current `factory-phase` signal.
173
219
 
174
- The **session handoff** (posted as the final conversation message after the verdict is recorded) mirrors the published body and additionally records the routing facts that must not appear on the PR: append a **Factory routing** block with `triggeredBy` verbatim, `reviewTarget` verbatim (`integrationId`, `type`, `externalId`, `url`), `boundRepository` verbatim, and the cross-check outcome — "matched" with the compared value from Phase 1, or "mismatch: <blocking-finding-ref>" if the check produced the blocking security finding above.
220
+ The **session handoff** (posted as the final conversation message after the verdict is recorded) is the full record. It is the published body followed by a **Run record** with: **Prior pass disposition** (every substantive item from your previous review, classified addressed, partially addressed, still open, refuted by the push, or invalidated by the push, with the commit or `file:line` proving each call), **Approach** (the required outcome and simplest sufficient design from your Phase 1 record, and whether the PR's approach and scope are justified against it), **Issue and intent** (the authorizing issue, PR classification, current approval-label state, and whether the implemented behavior and scope match the independently established contract and approved discussion), **Findings evidence** (the mechanism and evidence behind each table row, grounded in the history you traced), Label each finding `[push]` or `[fresh]` here so the record is honest about where it came from. **Verification** (every command you executed against the current head with its outcome, including base-versus-current-head evidence for affected behavior-changing claims and prior-head-versus-current-head evidence for push regressions, or what could not be executed and the substitute evidence used; verification the prior pass ran does not count; plus how the verdict was published: new review, edit, or comment fallback), **Other-reviewer disposition** (every substantive finding another reviewer, bot or human, posted since the prior pass, classified confirmed, addressed, or refuted with evidence), and **Assumptions** (every recorded judgment call from the run). Then append a **Factory routing** block with `triggeredBy` verbatim, `reviewTarget` verbatim (`integrationId`, `type`, `externalId`, `url`), `boundRepository` verbatim, and the cross-check outcome — "matched" with the compared value from Phase 1, or "mismatch: <blocking-finding-ref>" if the check produced the blocking security finding above.
175
221
 
176
222
  **The head must not have moved.** Immediately before publishing, run `gh pr view <number> --json headRefOid --jq .headRefOid` and compare it with the SHA your verification ran on (`git rev-parse HEAD`). A push can land while you verify or wait on bots, and a verdict on a superseded head misleads the author. If the head moved, do not publish: refresh the checkout to the new head, review the new commits and re-run the verification they affect, revise the handoff, then check again. Name the reviewed head SHA in the handoff.
177
223
 
@@ -179,10 +225,10 @@ Next, publish the re-review on the PR itself — this is part of every pass, not
179
225
 
180
226
  **Gate the file immediately before posting.** Run these checks against the exact file you are about to pass to `--body-file`, and post nothing if any fails — regenerate the body from this pass's findings instead:
181
227
 
182
- 1. `head -n1 <file>` is exactly `Verdict: approve` when you will use `--approve`, or exactly `Verdict: request changes` when you will use `--request-changes`.
228
+ 1. `head -n1 <file>` is exactly `## Verdict: approve` when you will use `--approve`, or exactly `## Verdict: request changes` when you will use `--request-changes`.
183
229
  2. The `Reviewed head:` SHA in the file equals `gh pr view <number> --json headRefOid --jq .headRefOid` and the `reviewedHeadSha` you will pass to `factory_record_review_verdict`.
184
230
 
185
- **Update your earlier verdict instead of stacking a new one.** Before posting, find your latest verdict post on this PR. List `gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate` and `gh api repos/<owner>/<repo>/issues/<number>/comments --paginate`, keep entries whose `.user.login` is `<factory-app>[bot]` and whose body (after an optional leading `> Opened by @<actor>` line) starts with `Verdict:`, drop reviews in state `DISMISSED`, and take the newest. Then:
231
+ **Update your earlier verdict instead of stacking a new one.** Before posting, find your latest verdict post on this PR. List `gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate` and `gh api repos/<owner>/<repo>/issues/<number>/comments --paginate`, keep entries whose `.user.login` is `<factory-app>[bot]` and whose body (after an optional leading `> Opened by @<actor>` line) starts with `Verdict:` or `## Verdict:`, drop reviews in state `DISMISSED`, and take the newest. Then:
186
232
 
187
233
  - Your verdict is request changes and the PR author (REST `.user.login`) is not `<factory-app>[bot]`: post a new verdict. Edits send no notification and do not complete a pending re-review request, so a human author would never learn the pass finished.
188
234
  - The latest is a PR comment and you are publishing as a comment (misconfiguration or fallback below): edit it with `gh api -X PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@<file>`.
@@ -199,7 +245,7 @@ When you are not editing, submit a PR review matching the verdict:
199
245
 
200
246
  **Author-identity misconfiguration must be visible, never silent.** GitHub refuses both approve and request changes from the PR's author, so a review token that authored the PR can never record a verdict in `reviewDecision` or satisfy branch protection. Before submitting, compare the reviewing identity (`gh api user --jq .login`; for an App installation token that call may fail — then treat a submission rejected with GitHub's "Can not approve/request changes on your own pull request" error as the same signal) with the PR author login from the REST lookup in the in-run cross-check (`.user.login`, never `gh pr view`'s `.author.login`, which formats App authors as `app/<slug>` and would hide a match). When they match:
201
247
 
202
- 1. Add this line to the published body immediately after the `Reviewed head:` line (the verdict line stays first and `Reviewed head:` stays second): `> ⚠️ **Factory misconfiguration:** the review token is the PR author, so GitHub cannot record this verdict as an approving or changes-requested review (it will not satisfy branch protection or workflows that require an approving or changes-requested review). Configure a separate reviewer token for Factory reviews.`
248
+ 1. Add this line to the published body immediately after the `Reviewed head:` line (the verdict line stays first and `Reviewed head:` stays second): `> ⚠️ **Factory misconfiguration:** the review token is the PR author, so GitHub cannot record this verdict as a review or count it toward branch protection. Configure a separate reviewer token for Factory reviews.`
203
249
  2. Publish with `gh pr comment <number> --body-file <file>`. Keep the verdict line first, as above: Factory wakes the author on a request-changes verdict only from a comment, or from a `COMMENTED` review Factory posted on its own PR, whose first line (after the proxy's `> Opened by` line) is the verdict.
204
250
  3. Report the misconfiguration and the publish method under **Verification** and in the **Factory routing** block of the handoff.
205
251
 
@@ -214,13 +260,13 @@ After publishing, reconcile the verdict label: approve adds `status:auto-approve
214
260
  1. Branch from the reviewed PR's current head: `git fetch origin pull/<number>/head && git checkout -b factory/rereview-followups-pr-<number> FETCH_HEAD`.
215
261
  2. Apply the fixes, run the narrowest tests covering them, and commit. **Credit the human whose work these commits build on.** The reviewed PR's `author` (from the Phase 1 `gh pr view --json` call) tells you who: when `is_bot` is false, add a `Co-Authored-By: <login> <ID+<login>@users.noreply.github.com>` trailer to every commit, resolving `ID` with `gh api users/<login> --jq .id`. When the author is a bot — the Factory's own pull requests are — credit the reporter of the issue the PR closes instead, if it links one. Credit nobody rather than guess at an identity: a trailer naming the wrong account is worse than no trailer.
216
262
  3. Push the branch and open a follow-up PR with `gh pr create`: target the reviewed PR's head branch when it lives in this repository, so the author can merge the follow-ups into their PR with one click; when the reviewed PR comes from a fork, target its base branch instead and state in the body that it lands after PR <number>.
217
- 4. Write the follow-up body to `.artifacts/factory-rereview/follow-up-pr-<number>.md`; it links the re-review and lists each finding it addresses, and the handoff links the follow-up PR.
263
+ 4. Write the follow-up body to `.artifacts/factory-rereview/follow-up-pr-<number>.md`; it links the re-review and lists each finding it addresses in one line each, with no other sections, and the handoff links the follow-up PR.
218
264
 
219
265
  Keep it strictly non-blocking and low-risk. A fix that demands design judgment, changes behavior, or grows beyond the mechanical stays a recorded finding — don't ship your own guess. **Never mix blocking findings into a follow-up PR**: those are requested changes on the reviewed PR, and implementing them yourself would review your own code. If tests fail on a follow-up fix, drop that fix and keep it a finding. If there are no such findings, skip this step entirely.
220
266
 
221
267
  Then make your terminal `factory_record_review_verdict` call with the published `verdict` (`approve` or `request changes`) and `reviewedHeadSha`, the head SHA you verified. The card stays in its review phase with the verdict shown on it; the merge moves it to a terminal phase, so never request a stage transition to end the re-review. The next push re-reviews it automatically.
222
268
 
223
- If the call is rejected, read the stated reason, address it (re-examine contested findings, re-review if the PR changed again mid-run), and retry once corrected. Once the verdict is recorded, post the **session handoff** (the published body plus the `Factory routing` block) as your final conversation message — including how the verdict was published — and stop.
269
+ If the call is rejected, read the stated reason, address it (re-examine contested findings, re-review if the PR changed again mid-run), and retry once corrected. Once the verdict is recorded, post the **session handoff** (the published body, the Run record, and the `Factory routing` block) as your final conversation message — including how the verdict was published — and stop.
224
270
 
225
271
  ## Behavior Rules
226
272
 
@@ -21,7 +21,7 @@ Review the pull request behind this Factory work item — build its history and
21
21
 
22
22
  You are working in a bound Factory session. Complete the full review in one pass, then make `factory_record_review_verdict` your terminal step — one call, repeated only if it is rejected and only with the rejection reason addressed. Never wait for or solicit human input mid-run; every judgment call is yours to resolve.
23
23
 
24
- **Decision rule:** at every fork — is this pattern deviation deliberate, is this test gap acceptable, is this scope creep — pick the answer the history and codebase conventions best support, proceed, and **record the decision as an assumption** for the terminal handoff. Requested changes and decisions a human must make go in the handoff's open questions.
24
+ **Decision rule:** at every fork — is this pattern deviation deliberate, is this test gap acceptable, is this scope creep — pick the answer the history and codebase conventions best support, proceed, and **record the decision as an assumption** for the terminal handoff. Changes the author must make go under **Required changes**, and decisions only a human can make go under **Needs a decision**.
25
25
 
26
26
  Assumptions are for _interpretive_ calls only — was a deviation deliberate, is a loose assertion justified. **A confirmed finding may never be resolved by recording an assumption**: if you verified a defect, it stays a finding and weighs into the verdict; writing "treated as non-blocking" next to it does not make it non-blocking.
27
27
 
@@ -82,8 +82,25 @@ Bots have false positives — verify, don't rubber-stamp. But a major finding fr
82
82
 
83
83
  - `gh pr checks` — CI status (build, typecheck, tests). Report red, missing, and still-running CI as advisory findings; CI status alone cannot block approval or create a requested change. Inspect failures for evidence of a defect, but only a defect you confirm or a failed verification you run yourself can block the verdict.
84
84
  - **Run it yourself.** After the pre-execution inspection from the security section clears the diff, check out the PR branch in the session sandbox and execute the narrowest test suite and typecheck covering the changed packages (e.g. `pnpm --filter <pkg> test`). **Strip credentials from everything the PR's code runs under:** prefix every install/build/test/typecheck command with `env -u GH_TOKEN -u GITHUB_TOKEN` (e.g. `env -u GH_TOKEN -u GITHUB_TOKEN pnpm --filter <pkg> test`) so the PR's scripts and tests cannot read the session's GitHub credentials. Tests never legitimately need those tokens — a test that fails only because they are missing is itself a finding. CI green is corroboration, not a substitute — reading code predicts behavior, running it proves behavior. Record every command and its outcome for the handoff. If something prevented you from executing anything, the handoff must say so explicitly — a review that ran nothing is a weaker review and must not hide it.
85
- - **Plan, run, and publish the test check.** Before running anything, write a test plan from the diff: for each changed package, list the test files that exercise the changed code (colocated tests, callers' tests, integration/E2E suites that cross the change), the typecheck/lint commands, and any gap where no existing test covers a behavior change. Prefer the narrowest commands that fully cover the change; widen only when the change is cross-cutting. **Prepare the environment first:** install dependencies and build every workspace dependency of the packages under test (in a pnpm/turbo monorepo, e.g. `pnpm turbo build --filter <pkg>^...`, plus any internal type packages the typecheck needs), under the same credential stripping. Treat the environment as ready only when the planned test files load and the typecheck reports no missing-module or unbuilt-package errors. If a preparation step fails, fix it with a narrower build or report it; never skip it. Immediately before the first command, call `source_control_publish_test_check` with the current full head SHA, `status: "in-progress"`, and the plan as `summary`. Execute the plan and record each command, its exit status, and the pass/fail/skip counts. When done, call `source_control_publish_test_check` again on the same head with `success` (every planned command passed), `failure` (any command failed or a test you ran reproduced a defect), `neutral` (execution was blocked by the security inspection or the environment — static review only), or `cancelled` (the head moved; re-plan on the new head). Put a one-line result in `title`, the test report's Checks on this head table and Regression proof line in `summary`, and failing test names with trimmed output in `details`. Never report `success` for commands you did not run, and never publish for a head other than the one you tested. An environment failure is not a pass: any test file that fails to load, any missing build output, or any typecheck error, including ones outside the changed files, makes the command a failure in the table. Rebuild the missing dependency and run the command again. If it still cannot run, publish `neutral` with the blocker named in `title`, never `success`. If the tool reports the provider cannot publish commit checks or publishing is turned off for the project, continue without the check; the test report comment below still carries the results. Run `git status --porcelain` before the tests and again before publishing `success`; if it prints anything, the tree is not the commit under review, so restore it to the head (or publish `neutral` naming the drift) rather than reporting a result for that SHA.
86
- - **Post the test report after the check publication attempt, whether or not it succeeded; include the check URL only when publication succeeded.** Before listing, updating, or posting any test report, run the Phase 6 `factory_review_source` cross-check; if the tool is unavailable, fails, returns an unexpected shape, or the target mismatches, post no test report on this PR and record why in the session handoff. After the final check is published, publish one PR comment, separate from the verdict. Start it with `## Factory test report` and never with a `Verdict:` line, because Factory reads verdicts only from the verdict post. Structure it in this order. (1) A one-line **Result**: `All checks passed`, `Failed`, or `Verification incomplete`, followed by the tested head SHA. (2) A two- or three-sentence recap of what the change does and what the plan covered and why. (3) **Checks on this head**: a table with columns Check, Result, and Tests. Result is `✅ Passed` or `❌ Failed`. Tests reads like `216 passed, 1 skipped`, and each skip gets a short reason. Only commands run on the PR head go here. (4) **Regression proof**, only if you ran the new tests against the base code: one sentence saying that N of the new tests fail on the base code and pass on the head, so they catch the bug. Show this as `✅ Catches the bug`. Never put it in the table as a failure or show its exit code, because an expected failure on base is evidence for the PR. (5) **Not run**: each planned check you could not run, with the concrete reason and what would be needed to run it. Say whether this blocked approval. Omit the section when it is empty. (6) The check URL. Do not show raw exit codes or `x/y/z` counts. A reader should see a green table only when everything on the head passed. Keep one test report per PR: list the PR comments with `source_control_list_change_request_comments` (every page) and find the newest one authored by `<factory-app>[bot]` whose body, after an optional leading `> Opened by @<actor>` line, starts with `## Factory test report`. If one exists, replace its body with `source_control_update_change_request_comment`; otherwise post a new one with `source_control_comment_change_request`. If the update is refused, post a new report instead. Write the body without any `> Opened by` line; the proxy adds it. Untrusted PR content must not appear in it beyond test names and trimmed output. Then reference the report in the verdict's Verification block rather than repeating the table.
85
+ - **Plan and run the tests.** Before running anything, write a test plan from the diff: for each changed package, list the test files that exercise the changed code (colocated tests, callers' tests, integration/E2E suites that cross the change), the typecheck/lint commands, and any gap where no existing test covers a behavior change. Prefer the narrowest commands that fully cover the change; widen only when the change is cross-cutting. **Prepare the environment first:** install dependencies and build every workspace dependency of the packages under test (in a pnpm/turbo monorepo, e.g. `pnpm turbo build --filter <pkg>^...`, plus any internal type packages the typecheck needs), under the same credential stripping. Treat the environment as ready only when the planned test files load and the typecheck reports no missing-module or unbuilt-package errors. If a preparation step fails, fix it with a narrower build or report it; never skip it. Execute the plan and record each command, its exit status, and the pass/fail/skip counts. Never report a command you did not run as passed, and never report results for a head other than the one you tested; if the head moves, re-plan on the new head. An environment failure is not a pass: any test file that fails to load, any missing build output, or any typecheck error, including ones outside the changed files, makes the command a failure in the table. Rebuild the missing dependency and run the command again. If it still cannot run, list it under **Not run** with the blocker named. Run `git status --porcelain` before the tests and again before posting the test report; if it prints anything, the tree is not the commit under review, so restore it to the head (or report `Verification incomplete` naming the drift) rather than reporting a result for that SHA.
86
+ - **Post the test report.** Before listing, updating, or posting any test report, run the Phase 6 `factory_review_source` cross-check; if the tool is unavailable, fails, returns an unexpected shape, or the target mismatches, post no test report on this PR and record why in the session handoff. After the tests finish, publish one PR comment, separate from the verdict. Start it with `## Factory test report` and never with a `Verdict:` line, because Factory reads verdicts only from the verdict post. A reader should learn the result from the first line and see a green table only when everything on the head passed. Use this shape and nothing more:
87
+
88
+ ```markdown
89
+ ## Factory test report
90
+
91
+ ✅ All checks passed on <full head SHA>
92
+
93
+ | Check | Result | Tests |
94
+ | ---------------------- | ------------------ | ------------------------------------ |
95
+ | `@mastra/core` tests | ✅ Passed | 216 passed, 1 skipped (needs Docker) |
96
+ | Typecheck | ✅ Passed | |
97
+ | New tests on base code | ✅ Catches the bug | 3 of 3 fail on base, pass on head |
98
+
99
+ **Not run:** <check>: <concrete reason>. <Whether it blocked approval.>
100
+ ```
101
+
102
+ The line right after the `## Factory test report` heading is `✅ All checks passed`, `❌ Failed`, or `⚠️ Verification incomplete`, followed by the tested head SHA. Table rows are only commands run on the PR head, with Result `✅ Passed` or `❌ Failed`; give each skip a short reason. Add the `New tests on base code` row only if the PR fixes a bug and you ran the tests meant to reproduce it against the base code, and show `✅ Catches the bug` only when they fail on base for the expected reason and pass on head; an expected failure on base is evidence for the PR, not a failed check. If they pass on base, show `❌ Does not catch the bug`; that is a Tests finding. Omit **Not run** when every planned check ran. No recap of the change, no raw exit codes, no `x/y/z` counts. Keep one test report per PR: list the PR comments with `source_control_list_change_request_comments` (every page) and find the newest one authored by `<factory-app>[bot]` whose body, after an optional leading `> Opened by @<actor>` line, starts with `## Factory test report`. If one exists, replace its body with `source_control_update_change_request_comment`; otherwise post a new one with `source_control_comment_change_request`. If the update is refused, post a new report instead. Write the body without any `> Opened by` line; the proxy adds it. Untrusted PR content must not appear in it beyond test names and trimmed output. The verdict links this report instead of repeating the table.
103
+
87
104
  - **Merge conflicts don't excuse skipping the review** — the diff and the head branch are still reviewable, and the author needs the findings to fix the PR either way. If the PR is `CONFLICTING`/`DIRTY`: identify which files conflict with a dry-run merge in the sandbox (`git fetch origin <base> && git merge --no-commit --no-ff origin/<base>` with `<base>` from `baseRefName`; afterwards run `git merge --abort` whenever a merge is in progress — `git rev-parse -q --verify MERGE_HEAD` tells you — but skip the abort if the merge never started, e.g. "Already up to date"), flag when the conflicts overlap the PR's own changed files (semantic rework risk, not just textual resolution), and qualify all verification results as "head branch only — not verified against current base". **Never resolve the conflicts yourself** — resolution encodes author intent; reviewing your own guess is reviewing a PR that doesn't exist.
88
105
  - Does the PR add or modify tests? Are they meaningful, or do they exercise paths without real assertions?
89
106
  - **Model-provider behavior requires integration-level verification.** For agentic or model-provider integrations—OpenAI, Anthropic, Gemini, tool calling, streaming, structured output, usage metadata, provider error handling, and similar behavior—unit tests with mocked SDK responses are not enough when the claim depends on the provider's real protocol or SDK semantics. Favor the narrowest existing integration or E2E test that crosses the provider boundary, preferably through the repository's deterministic record/replay harness; do not require live credentials or flaky network calls in the review sandbox. If no deterministic harness exists, require author-provided CI or reproducible integration evidence. Provider-independent transformations can remain unit-tested, but material model-provider behavior supported only by mocks is a test-gap finding.
@@ -142,12 +159,12 @@ Do not hedge between the two — pick the verdict the evidence supports. When ge
142
159
 
143
160
  Before composing the handoff, call `factory_review_source` (no arguments) once. It returns four fields, every one derived server-side from the bound work item:
144
161
 
145
- - `sessionUrl` — the Factory session URL that produced this review. This is the **only** field published on the PR (see the Factory Session block below); it is the value the audience uses to trace a suspicious review back to its run.
162
+ - `sessionUrl` — the Factory session URL that produced this review. This is the **only** field published on the PR (see the published body's footer below); it is the value the audience uses to trace a suspicious review back to its run.
146
163
  - `triggeredBy` — the PR author recorded on the review card at intake. Do not publish this; it is an in-run cross-check input and a session-handoff entry only.
147
164
  - `reviewTarget` — the review card's own `{ integrationId, type, externalId, url }`. Do not publish this; it is an in-run cross-check input and a session-handoff entry only.
148
165
  - `boundRepository` — the repository identity stamped on the review card at intake (`{ provider: 'github', repositoryId }` here), or `null` when intake recorded none. Do not publish this; it is the binding-side input to the null-`url` fallback below.
149
166
 
150
- If the tool call fails or returns an unexpected shape — **and identically if the tool is not offered on this session at all** (a review-role session with no configured browser-facing origin, no active binding, or no bound work item drops the tool from the toolset) — do **not** publish the review. The required Factory Session block can't be filled in with values that don't exist, and a review body without provenance can't be traced back to its run. Stop after Phase 6, record the tool's absence or failure and its raw response in the handoff under **Verification**, and hand off to a human — the verdict step below is skipped in this failure mode.
167
+ If the tool call fails or returns an unexpected shape — **and identically if the tool is not offered on this session at all** (a review-role session with no configured browser-facing origin, no active binding, or no bound work item drops the tool from the toolset) — do **not** publish the review. The required session link can't be filled in with values that don't exist, and a review body without provenance can't be traced back to its run. Stop after Phase 6, record the tool's absence or failure and its raw response in the handoff under **Verification**, and hand off to a human — the verdict step below is skipped in this failure mode.
151
168
 
152
169
  Before drafting the handoff, run the in-run cross-check against the tool's output:
153
170
 
@@ -158,22 +175,51 @@ On any mismatch, stop and record it as a blocking security finding with both val
158
175
 
159
176
  Compose two artifacts, in order — the **published body** goes on the PR, the **session handoff** goes back into the run's conversation. Don't send either to the conversation yet; both are drafted here, the published body is sent to the PR, the verdict is recorded, and only then is the session handoff posted.
160
177
 
161
- The **published body** (what `gh pr review --body-file` receives) **must open with the verdict line**: `Verdict: approve` or `Verdict: request changes`, then on the next line `Reviewed head: <full 40-character SHA>` naming the exact head you verified, followed by:
178
+ The **published body** (what `gh pr review --body-file` receives) is what the author reads, often from a notification. Every line has to earn its place: plain words, no jargon, no restating the diff, no praise, nothing about the author. The verdict comes first and the findings come next; anything a reader does not need in order to act or to trust the verdict stays in the session handoff. Use this shape, dropping each optional part that would be empty:
179
+
180
+ ```markdown
181
+ ## Verdict: request changes
182
+
183
+ Reviewed head: <full 40-character SHA>
184
+
185
+ <One sentence: what blocks the merge, or why it is safe to merge.>
186
+
187
+ | # | Severity | Blocks merge | Type | Finding | Where |
188
+ | --- | --------- | ------------ | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
189
+ | 1 | ●●●○ high | Yes | Correctness | <What breaks, for whom, and why.> | [`stream.ts:42`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.ts#L42) |
190
+ | 2 | ●○○○ low | No | Tests | <What is missing and what it would catch.> | [`stream.test.ts:10`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.test.ts#L10) |
191
+
192
+ ### Required changes
193
+
194
+ 1. [`stream.ts:42`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.ts#L42): <Imperative change.>
195
+
196
+ ### Needs a decision
197
+
198
+ - <Question only a person can answer, and the answer this review assumed.>
199
+
200
+ <details>
201
+ <summary>Review notes</summary>
202
+
203
+ - **Tests:** <The test report's result line (the line after its heading), linked to the report.>
204
+ - **Earlier reviews:** <Reviewer, subject, `file:line`: addressed or refuted, with the evidence in a few words.>
205
+ - **Why approve:** <The strongest case for request changes, and why it fails.>
206
+
207
+ </details>
162
208
 
163
- - **Findings** — lead with the mechanism of the most consequential finding, then correctness, tests, scope, and pattern-consistency, each grounded in the history you traced. Distill — this is a handoff, not a transcript.
164
- - **Approach** — the required outcome and the simplest sufficient design from your Phase 1 record, and whether the PR's approach and scope are justified against it. Agreement stated in one line; disagreement with the evidence that supports the alternative.
165
- - **Issue and intent** — the authorizing issue, PR classification, current approval-label state, and whether the implemented behavior and scope match the independently established contract and approved discussion.
166
- - **Verification** — every command you executed (tests, typecheck, repros) with its outcome, including base-versus-head evidence for behavior-changing claims, or an explicit statement that something could not be executed and the substitute evidence used.
167
- - **Existing review disposition** — every substantive finding from prior reviewers (bots included, your own earlier passes included) with its classification: confirmed, addressed, or refuted with evidence. A major bot comment must never be silently dropped. Name each by subject and `file:line`, and remember the body lands as GitHub markdown — `#1` publishes as a link to issue 1.
168
- - **Adversarial check** (approve only) — the one-line record of why the strongest request-changes case fails.
169
- - **Requested changes** — one entry per change (for a request-changes verdict), imperative and present tense: the file and line, the change, and the consequence or evidence in one or two sentences. Put the change that most affects correctness first; group changes that must land together or state their dependencies. No softened requests ("consider", "you might want to"), no optional or follow-up tiers, no pleasantries, nothing about the author. Preserve qualifications that express real limits of evidence — "the contract does not guarantee this field" must not become "servers never return this field".
170
- - **Assumptions** — every recorded judgment call from the run.
171
- - **Open questions** — any decision that genuinely needs a human.
172
- - **Factory Session** — `sessionUrl` from `factory_review_source`, verbatim, as a link. **Nothing else in this block.** `triggeredBy` and `reviewTarget` are cross-check inputs for the run and go in the session handoff below; they are never published on the PR. This section is required for every verdict and every fallback (approve, request changes, comment fallback) so a suspicious review — one that lands on the wrong PR, or approves and requests changes at once — can always be traced back to the run that produced it.
209
+ <sub>[Factory session](sessionUrl) · Review runtime: <model>, reasoning setting: <reasoning>.</sub>
210
+ ```
173
211
 
174
- End the published body with `Review runtime: <model>, reasoning setting: <reasoning>.`, copying both values verbatim from the current `factory-phase` signal.
212
+ - **Verdict.** Line 1 is exactly `## Verdict: approve` or `## Verdict: request changes`, and line 2 is `Reviewed head: <full 40-character SHA>` naming the exact head you verified. Factory parses both lines, so add nothing else to them.
213
+ - **Summary.** One sentence of at most 25 words. On request changes, name what blocks the merge; on approve, say why it is safe to merge. Never "LGTM" or a description of the PR.
214
+ - **Findings table.** One row per finding, ranked: blocking rows first, then by severity. Severity uses the triage dot scale, dots then the word: `●○○○ low`, `●●○○ medium`, `●●●○ high`, `●●●● critical`. Blocks merge is `Yes` or `No`; severity and blocking are separate calls (a missing regression test can be medium and still block). Type is one of Correctness, Security, Tests, Design, Scope, Compatibility, Docs, Merge conflict, or Verification (the review could not complete verification; name the blocker and do not present it as a defect in the author's code). Finding states the problem and its consequence in at most 25 words; keep the evidence for the session handoff unless one clause of it is needed to believe the row. Where is a linked `file:line` (see **Link every code reference**), or `—` when the finding has no single location. A confirmed finding from another reviewer is a row too, crediting them: "(raised by coderabbitai)". A non-blocking row fixed by the follow-up PR ends with "Fixed in the follow-up PR." A design or scope disagreement with your Phase 1 record is a Design or Scope row, not a separate section. With no findings, write `No findings.` instead of the table.
215
+ - **Required changes** (request changes only). One numbered entry per change, in table order: the linked `file:line`, then one sentence, imperative and present tense. The table already carries the consequence, so don't repeat it. Put changes that must land together in one entry. For a conflicting PR, one entry is "Resolve merge conflicts against `<base>`.", noting when the conflicts overlap the PR's own files. No softened requests ("consider", "you might want to"), no optional or follow-up tiers, no pleasantries. Preserve qualifications that express real limits of evidence: "the contract does not guarantee this field" must not become "servers never return this field".
216
+ - **Needs a decision.** Only questions that genuinely need a person. Omit the section otherwise.
217
+ - **Review notes.** Collapsed, and only what a reader may need to trust the verdict. **Tests** is always present. **Earlier reviews** lists only prior findings (bots included) that are addressed or refuted; confirmed ones are table rows. Omit it when there are none. **Why approve** is the one-line adversarial check record, approve only. Nothing else goes here.
218
+ - **Link every code reference.** Each `file:line` in the published body is a link to that line at the reviewed head: `[`stream.ts:42`](https://github.com/<owner>/<repo>/blob/<headSha>/src/stream.ts#L42)`, with `#L40-L44` for a range. Use the full head SHA in the URL, never a branch name, so the link still shows what you reviewed after more pushes. Show the shortest path that is unambiguous in the PR (usually the file name) as the link text; the link carries the full path. A reference to a removed line links to the base SHA instead. A change with no code location (an unpushed branch, a failed check, a verification gap) gets no link: state the change in one sentence. A reference to another reviewer's comment links to that comment.
219
+ - **GitHub markdown.** `#1` publishes as a link to issue 1, so name findings by subject and `file:line`, never by `#n`.
220
+ - **Footer.** `sessionUrl` from `factory_review_source`, verbatim, as the Factory session link. It is the only routing fact published: `triggeredBy`, `reviewTarget`, and `boundRepository` are cross-check inputs for the run and are never published on the PR. The footer is required on every verdict and every fallback (approve, request changes, comment fallback), so a suspicious review — one that lands on the wrong PR, or approves and requests changes at once — can always be traced back to the run that produced it. Copy both runtime values verbatim from the current `factory-phase` signal.
175
221
 
176
- The **session handoff** (posted as the final conversation message after the verdict is recorded) mirrors the published body and additionally records the routing facts that must not appear on the PR: append a **Factory routing** block with `triggeredBy` verbatim, `reviewTarget` verbatim (`integrationId`, `type`, `externalId`, `url`), `boundRepository` verbatim, and the cross-check outcome — "matched" with the compared value from Phase 1, or "mismatch: <blocking-finding-ref>" if the check produced the blocking security finding above.
222
+ The **session handoff** (posted as the final conversation message after the verdict is recorded) is the full record. It is the published body followed by a **Run record** with: **Approach** (the required outcome and simplest sufficient design from your Phase 1 record, and whether the PR's approach and scope are justified against it), **Issue and intent** (the authorizing issue, PR classification, current approval-label state, and whether the implemented behavior and scope match the independently established contract and approved discussion), **Findings evidence** (the mechanism and evidence behind each table row, grounded in the history you traced), **Verification** (every command you executed (tests, typecheck, repros) with its outcome, including base-versus-head evidence for behavior-changing claims, or what could not be executed and the substitute evidence used; plus how the verdict was published: new review, edit, or comment fallback), **Existing review disposition** (every substantive prior finding, bots and your own earlier passes included, classified confirmed, addressed, or refuted with evidence), and **Assumptions** (every recorded judgment call from the run). Then append a **Factory routing** block with `triggeredBy` verbatim, `reviewTarget` verbatim (`integrationId`, `type`, `externalId`, `url`), `boundRepository` verbatim, and the cross-check outcome — "matched" with the compared value from Phase 1, or "mismatch: <blocking-finding-ref>" if the check produced the blocking security finding above.
177
223
 
178
224
  **The head must not have moved.** Immediately before publishing, run `gh pr view <number> --json headRefOid --jq .headRefOid` and compare it with the SHA your verification ran on (`git rev-parse HEAD`). A push can land while you verify or wait on bots, and a verdict on a superseded head misleads the author. If the head moved, do not publish: refresh the checkout to the new head, review the new commits and re-run the verification they affect, revise the handoff, then check again. Name the reviewed head SHA in the handoff.
179
225
 
@@ -181,10 +227,10 @@ Next, publish the review on the PR itself — this is part of every pass, not so
181
227
 
182
228
  **Gate the file immediately before posting.** Run these checks against the exact file you are about to pass to `--body-file`, and post nothing if any fails — regenerate the body from this pass's findings instead:
183
229
 
184
- 1. `head -n1 <file>` is exactly `Verdict: approve` when you will use `--approve`, or exactly `Verdict: request changes` when you will use `--request-changes`.
230
+ 1. `head -n1 <file>` is exactly `## Verdict: approve` when you will use `--approve`, or exactly `## Verdict: request changes` when you will use `--request-changes`.
185
231
  2. The `Reviewed head:` SHA in the file equals `gh pr view <number> --json headRefOid --jq .headRefOid` and the `reviewedHeadSha` you will pass to `factory_record_review_verdict`.
186
232
 
187
- **Update your earlier verdict instead of stacking a new one.** Before posting, find your latest verdict post on this PR. List `gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate` and `gh api repos/<owner>/<repo>/issues/<number>/comments --paginate`, keep entries whose `.user.login` is `<factory-app>[bot]` and whose body (after an optional leading `> Opened by @<actor>` line) starts with `Verdict:`, drop reviews in state `DISMISSED`, and take the newest. Then:
233
+ **Update your earlier verdict instead of stacking a new one.** Before posting, find your latest verdict post on this PR. List `gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate` and `gh api repos/<owner>/<repo>/issues/<number>/comments --paginate`, keep entries whose `.user.login` is `<factory-app>[bot]` and whose body (after an optional leading `> Opened by @<actor>` line) starts with `Verdict:` or `## Verdict:`, drop reviews in state `DISMISSED`, and take the newest. Then:
188
234
 
189
235
  - Your verdict is request changes and the PR author (REST `.user.login`) is not `<factory-app>[bot]`: post a new verdict. Edits send no notification and do not complete a pending re-review request, so a human author would never learn the pass finished.
190
236
  - The latest is a PR comment and you are publishing as a comment (misconfiguration or fallback below): edit it with `gh api -X PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@<file>`.
@@ -201,7 +247,7 @@ When you are not editing, submit a PR review matching the verdict:
201
247
 
202
248
  **Author-identity misconfiguration must be visible, never silent.** GitHub refuses both approve and request changes from the PR's author, so a review token that authored the PR can never record a verdict in `reviewDecision` or satisfy branch protection. Before submitting, compare the reviewing identity (`gh api user --jq .login`; for an App installation token that call may fail — then treat a submission rejected with GitHub's "Can not approve/request changes on your own pull request" error as the same signal) with the PR author login from the REST lookup in the in-run cross-check (`.user.login`, never `gh pr view`'s `.author.login`, which formats App authors as `app/<slug>` and would hide a match). When they match:
203
249
 
204
- 1. Add this line to the published body immediately after the `Reviewed head:` line (the verdict line stays first and `Reviewed head:` stays second): `> ⚠️ **Factory misconfiguration:** the review token is the PR author, so GitHub cannot record this verdict as an approving or changes-requested review (it will not satisfy branch protection or workflows that require an approving or changes-requested review). Configure a separate reviewer token for Factory reviews.`
250
+ 1. Add this line to the published body immediately after the `Reviewed head:` line (the verdict line stays first and `Reviewed head:` stays second): `> ⚠️ **Factory misconfiguration:** the review token is the PR author, so GitHub cannot record this verdict as a review or count it toward branch protection. Configure a separate reviewer token for Factory reviews.`
205
251
  2. Publish with `gh pr comment <number> --body-file <file>`. Keep the verdict line first, as above: Factory wakes the author on a request-changes verdict only from a comment, or from a `COMMENTED` review Factory posted on its own PR, whose first line (after the proxy's `> Opened by` line) is the verdict.
206
252
  3. Report the misconfiguration and the publish method under **Verification** and in the **Factory routing** block of the handoff.
207
253
 
@@ -216,13 +262,13 @@ After publishing, reconcile the verdict label: approve adds `status:auto-approve
216
262
  1. Branch from the reviewed PR's head: `git fetch origin pull/<number>/head && git checkout -b factory/review-followups-pr-<number> FETCH_HEAD`.
217
263
  2. Apply the fixes, run the narrowest tests covering them, and commit. **Credit the human whose work these commits build on.** The reviewed PR's `author` (from the Phase 1 `gh pr view --json` call) tells you who: when `is_bot` is false, add a `Co-Authored-By: <login> <ID+<login>@users.noreply.github.com>` trailer to every commit, resolving `ID` with `gh api users/<login> --jq .id`. When the author is a bot — the Factory's own pull requests are — credit the reporter of the issue the PR closes instead, if it links one. Credit nobody rather than guess at an identity: a trailer naming the wrong account is worse than no trailer.
218
264
  3. Push the branch and open a follow-up PR with `gh pr create`: target the reviewed PR's head branch when it lives in this repository, so the author can merge the follow-ups into their PR with one click; when the reviewed PR comes from a fork, target its base branch instead and state in the body that it lands after PR <number>.
219
- 4. Write the follow-up body to `.artifacts/factory-review/follow-up-pr-<number>.md`; it links the review and lists each finding it addresses, and the handoff links the follow-up PR.
265
+ 4. Write the follow-up body to `.artifacts/factory-review/follow-up-pr-<number>.md`; it links the review and lists each finding it addresses in one line each, with no other sections, and the handoff links the follow-up PR.
220
266
 
221
267
  Keep it strictly non-blocking and low-risk. A fix that demands design judgment, changes behavior, or grows beyond the mechanical stays a recorded finding — don't ship your own guess. **Never mix blocking findings into a follow-up PR**: those are requested changes on the reviewed PR, and implementing them yourself would review your own code. If tests fail on a follow-up fix, drop that fix and keep it a finding. If there are no such findings, skip this step entirely.
222
268
 
223
269
  Then make your terminal `factory_record_review_verdict` call with the published `verdict` (`approve` or `request changes`) and `reviewedHeadSha`, the head SHA you verified. The card stays in its review phase with the verdict shown on it; the merge moves it to a terminal phase, so never request a stage transition to end the review. The next push re-reviews it automatically.
224
270
 
225
- If the call is rejected, read the stated reason, address it (re-examine contested findings, re-review if the PR changed), and retry once corrected. Once the verdict is recorded, post the **session handoff** (the published body plus the `Factory routing` block) as your final conversation message — including how the verdict was published — and stop.
271
+ If the call is rejected, read the stated reason, address it (re-examine contested findings, re-review if the PR changed), and retry once corrected. Once the verdict is recorded, post the **session handoff** (the published body, the Run record, and the `Factory routing` block) as your final conversation message — including how the verdict was published — and stop.
226
272
 
227
273
  ## Behavior Rules
228
274
 
@@ -40,14 +40,13 @@ Push for the smallest change that fixes the reported problem, with proportionate
40
40
 
41
41
  ## Report
42
42
 
43
- Write the findings argument of the verdict call as Markdown the builder (on request changes) or the change request body (on approve) can use directly:
43
+ Write the findings argument of the verdict call as Markdown the builder (on request changes) or the change request body (on approve) can use directly. Keep it short: every line has to earn its place, with plain words and no jargon, no recap of the diff, and no praise. Drop each part that would be empty:
44
44
 
45
45
  1. **Result** line: `Approved`, `Changes requested`, or `Verification incomplete`, followed by the full head SHA.
46
- 2. A two-to-three sentence recap of the change and what the test plan covered.
47
- 3. **Checks on this head**: the same table format as the Factory test report in `factory-review` (Check / Result / Tests, ✅ Passed or ❌ Failed, no raw exit codes), plus **Regression proof** and **Not run** sections when they apply.
48
- 4. On request changes: a numbered list of discrete **Required changes**, each a blocking finding with a file pointer and the reason. Each must be something the builder can act on in the next round.
49
- 5. **Follow-ups**: a separate list of non-blocking findings, or `None`. They are never required work; on approve they carry into the change request body.
50
- 6. On approve: the one-line adversarial check record.
46
+ 2. **Checks on this head**: the same table format as the Factory test report in `factory-review` (Check / Result / Tests, ✅ Passed or ❌ Failed, no raw exit codes), with a `New tests on base code` row when you proved the tests catch the bug, and a one-line **Not run:** note when a planned check could not run.
47
+ 3. On request changes: a numbered list of discrete **Required changes**, each a blocking finding with a `file:line` pointer (linked to that line at the reviewed head when the repository is on GitHub or GitLab, since the report can end up in the change request body) and the reason in one sentence. Workflow and verification failures with no code location, such as an unpushed branch or a failed check, get no pointer. Each must be something the builder can act on in the next round.
48
+ 4. **Follow-ups**: a separate list of non-blocking findings, one line each; omit it when there are none. They are never required work; on approve they carry into the change request body.
49
+ 5. On approve: the one-line adversarial check record.
51
50
 
52
51
  ## Verdict
53
52
 
@@ -123,32 +123,19 @@ Write one concise **handoff** for whoever plans the fix. It must begin with the
123
123
  **Next step:** <one action>
124
124
 
125
125
  <details>
126
- <summary><strong>Why these ratings</strong></summary>
126
+ <summary><strong>Details</strong></summary>
127
+
128
+ **Why these ratings**
127
129
 
128
130
  - **Confidence** — <evidence>
129
131
  - **Effort** — <scope>
130
132
  - **Impact** — <who is affected and how>
131
133
 
132
- </details>
133
-
134
- <details>
135
- <summary><strong>Root cause</strong></summary>
136
-
137
- <root cause with evidence, contributing areas with file paths and relevant history, affected surface, suggested direction, related issues/PRs. Distill — this is a handoff artifact, not a transcript.>
138
-
139
- </details>
134
+ **Root cause** — <root cause with evidence, contributing areas with file paths and relevant history, affected surface, suggested direction, related issues/PRs. Distill — this is a handoff artifact, not a transcript.>
140
135
 
141
- <details>
142
- <summary><strong>Reproduction</strong></summary>
143
-
144
- <for reproduced bugs: exact successful steps. Otherwise: attempted steps, environment, and result, or `Not applicable` / `Not reproduced` with a reason.>
145
-
146
- </details>
147
-
148
- <details>
149
- <summary><strong>Assumptions</strong></summary>
136
+ **Reproduction** — <for reproduced bugs: exact successful steps. Otherwise: attempted steps, environment, and result, or `Not applicable` / `Not reproduced` with a reason.>
150
137
 
151
- <every recorded decision from the run>
138
+ **Assumptions** — <every recorded decision from the run, or `None`>
152
139
 
153
140
  </details>
154
141
 
@@ -163,7 +150,8 @@ Fill the placeholders as follows:
163
150
  - `<Type>` is one of: bug, feature request, docs, question/support, maintenance, duplicate, resolved, invalid, spam, out-of-scope, other, capitalized for display. `<Severity>` and `<level>` are the lowercase ratings from the guides below. `<Route>` is one of: Plan fix, Await approval, Ask author for info, Close as duplicate/resolved/invalid/spam/out-of-scope, Answer provided / close, No transition / refresh, Other.
164
151
  - `<dots>` shows the rating at a glance. Severity uses four dots: `●○○○` low, `●●○○` medium, `●●●○` high, `●●●●` critical. Confidence, effort, and impact use three: `●○○` low, `●●○` medium, `●●●` high. Always follow the dots with the word.
165
152
  - Each rating reason is at most 12 words.
166
- - Keep the collapsed sections collapsed. Only the ratings table, the summary, the next step, and open questions stay visible.
153
+ - Keep everything else in the one collapsed **Details** block. Only the ratings table, the summary, the next step, and open questions stay visible. Every line in Details has to earn its place: cut anything a planner would not act on.
154
+ - On GitHub, link every file or `file:line` reference to the code at the commit you investigated: `[`stream.ts:42`](https://github.com/<owner>/<repo>/blob/<full SHA>/src/stream.ts#L42)`. Use the full SHA, not a branch name, so the link keeps pointing at the code you read. Link issues, PRs, and commits you mention too.
167
155
  - Use no alerts or emoji, and no tables other than the ratings table.
168
156
 
169
157
  Severity guide: