@cbartens/bkit 6.1.1 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (313) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +42 -32
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -22,7 +22,11 @@ import * as fs from "node:fs";
22
22
  import * as os from "node:os";
23
23
  import * as path from "node:path";
24
24
 
25
- import { BKIT_LINT_FILE_SCRIPT, BKIT_TEST_FILE_SCRIPT } from "../../install/manifest.js";
25
+ import {
26
+ BKIT_GATE_CHANGED_SCRIPT,
27
+ BKIT_LINT_FILE_SCRIPT,
28
+ BKIT_TEST_FILE_SCRIPT,
29
+ } from "../../install/manifest.js";
26
30
  import { clampLogPath } from "../../ledgers/clamp-log.js";
27
31
  import {
28
32
  appendLine,
@@ -30,23 +34,11 @@ import {
30
34
  validateCiSelection,
31
35
  testRunProblem,
32
36
  } from "../../ledgers/status.js";
33
- import {
34
- classifyLockExit,
35
- CommandError,
36
- EXIT,
37
- git,
38
- runGit,
39
- testsLockHolder,
40
- wholeNumber,
41
- type CommandSpec,
42
- } from "../lib.js";
37
+ import { CommandError, EXIT, git, runGit, wholeNumber, type CommandSpec } from "../lib.js";
43
38
  import { parseJson } from "../../shared/json.js";
39
+ import { oneLine } from "../../shared/text.js";
44
40
  import { readPackageJson } from "../../shared/package-json.js";
45
- import {
46
- COULD_NOT_RUN_EXIT_CODES,
47
- scriptCommand,
48
- testCommand,
49
- } from "../../shared/package-manager.js";
41
+ import { COULD_NOT_RUN_EXIT_CODES, scriptCommand } from "../../shared/package-manager.js";
50
42
  import { CONFIG_DEFAULTS, readBkitConfig, type TaskCaps } from "../../shared/settings.js";
51
43
  import {
52
44
  FILE_FLAG,
@@ -68,8 +60,33 @@ import {
68
60
  type PlanTaskBlock,
69
61
  } from "./plan-blocks.js";
70
62
  import { writeStepRow } from "./steps.js";
63
+ import { activeRunStart } from "./counters.js";
64
+ import {
65
+ REPORT_ENV,
66
+ reportFailures,
67
+ runGateUnderLock,
68
+ runTestFile,
69
+ runToLog,
70
+ type JunitCase,
71
+ type LockedRun,
72
+ } from "./junit.js";
71
73
  import { appendRecord, clampFile, type ClampRecord } from "./context.js";
72
- import { testsChangedVerb } from "./tests-changed.js";
74
+ import { minPushPathspecs } from "../ci/ci.js";
75
+ import { requiredPushGate, runWithReceipt } from "../ci/push-gate.js";
76
+ import { testsBaseVerb } from "./tests-base.js";
77
+ import {
78
+ changedBetween,
79
+ changedFiles,
80
+ commitExists,
81
+ declares,
82
+ snapshotTree,
83
+ deletedFiles,
84
+ importersOf,
85
+ testsChangedVerb,
86
+ } from "./tests-changed.js";
87
+ import { ORIGIN_DEV, featureBase } from "./feature-base.js";
88
+ import { testsJumpVerb } from "./tests-jump.js";
89
+ import { readPlanRows } from "./ledgers.js";
73
90
 
74
91
  /** Exit code: no candidate gate is declared in package.json. */
75
92
  export const EXIT_NO_GATE = 3;
@@ -84,8 +101,6 @@ export const TEST_RUN_ROW = "test-run";
84
101
  /** The env var naming the folder every runner a gate calls writes its JUnit XML into. */
85
102
  export const REPORT_DIR_ENV = "BKIT_TEST_REPORT_DIR";
86
103
 
87
- export { classifyLockExit } from "../lib.js";
88
-
89
104
  const NO_REPORT_HINT =
90
105
  `no JUnit report in $${REPORT_DIR_ENV} — failures unknown; turn on each test runner's JUnit ` +
91
106
  `reporter in the gate and point its output into $${REPORT_DIR_ENV} ` +
@@ -114,36 +129,94 @@ export function resolveGate(dir: string, candidates: readonly string[]): string
114
129
  );
115
130
  }
116
131
 
117
- /** The scope string the status rows record: the package runner plus the script name. */
118
- export const gateScope = (gate: string) => scriptCommand(gate).join(" ");
132
+ /** The `--changed-since` word that names the feature's start commit. */
133
+ export const FEATURE_BASE_WORD = "feature-base";
119
134
 
120
135
  /**
121
- * Run argv with stdout and stderr interleaved into `log` (like `> log 2>&1`).
122
- * Exit 127 when the binary is missing; 128 + n when killed by signal n.
136
+ * `--changed-since` as a commit name: `feature-base` resolves through `featureBase`, which
137
+ * falls back to the name `origin/dev` when it cannot work out the feature's start commit.
123
138
  */
124
- export function runToLog(
125
- argv: string[],
126
- cwd: string,
127
- log: string,
128
- env?: Record<string, string>,
129
- ): number {
130
- fs.mkdirSync(path.dirname(log), { recursive: true });
131
- const fd = fs.openSync(log, "w");
132
- const protectedArgv = testCommand(argv);
133
- const res = spawnSync(protectedArgv[0]!, protectedArgv.slice(1), {
134
- cwd,
135
- stdio: ["ignore", fd, fd],
136
- env: env === undefined ? process.env : { ...process.env, ...env },
137
- });
138
- fs.closeSync(fd);
139
- if (res.error) {
140
- fs.appendFileSync(log, `${argv[0]}: not found on PATH (${res.error.message})\n`);
141
- return 127;
139
+ function sinceBase(
140
+ top: string,
141
+ raw: string | undefined,
142
+ log: (line: string) => void,
143
+ ): string | undefined {
144
+ if (raw !== FEATURE_BASE_WORD) return raw;
145
+ const base = featureBase(top, log);
146
+ if (base === ORIGIN_DEV)
147
+ log(`feature base: no meeting point with ${ORIGIN_DEV} — measuring from ${ORIGIN_DEV}`);
148
+ else log(`feature base: ${base}`);
149
+ return base;
150
+ }
151
+
152
+ /**
153
+ * The files `bkit:gate:changed` gets for a run measured from `base`: the changed files plus
154
+ * the files that still mention a deleted one, sorted, with the deleted files. Null when the
155
+ * search for those files fails: the caller runs the whole check, never a pass.
156
+ */
157
+ function changedScope(
158
+ top: string,
159
+ base: string,
160
+ candidates: readonly string[],
161
+ log: (line: string) => void,
162
+ diff: { files: string[]; deleted: string[] } = {
163
+ files: changedFiles(top, base),
164
+ deleted: deletedFiles(top, base),
165
+ },
166
+ ): { files: string[]; deleted: string[] } | null {
167
+ const { files: changed, deleted } = diff;
168
+ const importers = importersOf(top, base, deleted);
169
+ if (importers === null) {
170
+ log(
171
+ `could not search ${base} for the files that mention the deleted ${deleted.join(" ")} — running the whole ${resolveGate(top, candidates) ?? "--gate"}`,
172
+ );
173
+ return null;
142
174
  }
143
- if (res.status !== null) return res.status;
144
- return 128 + ((res.signal ? os.constants.signals[res.signal] : undefined) ?? 1);
175
+ for (const [file, hits] of importers)
176
+ log(
177
+ hits.length === 0
178
+ ? `deleted ${file}: no file mentions it`
179
+ : `deleted ${file}: checking the ${hits.length} file(s) that mention it`,
180
+ );
181
+ return { files: [...new Set([...changed, ...[...importers.values()].flat()])].sort(), deleted };
145
182
  }
146
183
 
184
+ /**
185
+ * The `tested` snapshot of the newest PASS test-run row of `steps` in `workflow` whose
186
+ * commit still exists, or null; each snapshot gone from the object store is logged.
187
+ */
188
+ function newestPass(
189
+ top: string,
190
+ file: string,
191
+ workflow: string,
192
+ steps: readonly string[],
193
+ log: (line: string) => void,
194
+ ): string | null {
195
+ const passes = readStatusRows(file).filter(
196
+ (r) =>
197
+ r.type === TEST_RUN_ROW &&
198
+ r.workflow === workflow &&
199
+ typeof r.step === "string" &&
200
+ steps.includes(r.step) &&
201
+ r.verdict === "PASS" &&
202
+ typeof r.tested === "string",
203
+ );
204
+ for (const row of passes.reverse()) {
205
+ const sha = String(row.tested);
206
+ if (commitExists(top, sha)) {
207
+ log(
208
+ `testing the files changed since run ${String(row.run)} of ${String(row.step)} passed (snapshot ${sha})`,
209
+ );
210
+ return sha;
211
+ }
212
+ log(`the snapshot ${sha} of run ${String(row.run)} of ${String(row.step)} is gone`);
213
+ }
214
+ return null;
215
+ }
216
+
217
+ /** The scope string the status rows record: the package runner plus the script name. */
218
+ export const gateScope = (gate: string) => scriptCommand(gate).join(" ");
219
+
147
220
  /** `{log}.reports`, emptied: a previous attempt's reports never count toward this one. */
148
221
  function freshReportDir(log: string): string {
149
222
  const dir = `${log}.reports`;
@@ -152,17 +225,6 @@ function freshReportDir(log: string): string {
152
225
  return dir;
153
226
  }
154
227
 
155
- /** Failing plus erroring test cases across every `*.xml` under `dir`; null when there is none. */
156
- export function countReportFailures(dir: string): number | null {
157
- const xml = (fs.readdirSync(dir, { recursive: true }) as string[]).filter(
158
- (f) => f.endsWith(".xml") && fs.statSync(path.join(dir, f)).isFile(),
159
- );
160
- if (xml.length === 0) return null;
161
- return xml
162
- .flatMap((f) => parseJunit(fs.readFileSync(path.join(dir, f), "utf-8")))
163
- .filter((c) => c.state === "failure" || c.state === "error").length;
164
- }
165
-
166
228
  const tailLines = (file: string, n: number) =>
167
229
  fs
168
230
  .readFileSync(file, "utf-8")
@@ -170,6 +232,30 @@ const tailLines = (file: string, n: number) =>
170
232
  .split(/\r?\n/)
171
233
  .slice(-n);
172
234
 
235
+ /** The most failing-test names one `test-run` row keeps. */
236
+ export const FAILED_TESTS_CAP = 100;
237
+
238
+ /** A failing JUnit case as a `failedTests` name: `{file ?? classname} > {name}`, or the name alone. */
239
+ export const caseLabel = (c: JunitCase) => {
240
+ const where = c.file ?? c.classname;
241
+ return where === null || where === "" ? c.name : `${where} > ${c.name}`;
242
+ };
243
+
244
+ /**
245
+ * The `failedTests` row fields for `names`: unique, sorted, at most `FAILED_TESTS_CAP`, with
246
+ * `failedTestsTruncated` when cut; none when `names` is empty.
247
+ */
248
+ export function failedTestsField(names: readonly string[]): {
249
+ failedTests?: string[];
250
+ failedTestsTruncated?: true;
251
+ } {
252
+ const unique = [...new Set(names.filter((n) => n !== ""))].sort();
253
+ if (unique.length === 0) return {};
254
+ return unique.length > FAILED_TESTS_CAP
255
+ ? { failedTests: unique.slice(0, FAILED_TESTS_CAP), failedTestsTruncated: true }
256
+ : { failedTests: unique };
257
+ }
258
+
173
259
  /**
174
260
  * Append one `test-run` row to `file`. `run` numbers this step's test-run rows in the
175
261
  * workflow's active run (since its last workflow-started row), this one included, so a
@@ -189,6 +275,10 @@ function appendTestRun(
189
275
  artifact: string | undefined;
190
276
  source?: "ci" | "local";
191
277
  evidence?: Record<string, unknown>;
278
+ /** The `snapshotTree` commit of the tree the run tested; left off the row when null. */
279
+ tested?: string | null;
280
+ failedTests?: string[];
281
+ failedTestsTruncated?: true;
192
282
  },
193
283
  ): Record<string, unknown> {
194
284
  const rows = readStatusRows(file);
@@ -215,6 +305,9 @@ function appendTestRun(
215
305
  log: r.log,
216
306
  ...(r.artifact === undefined ? {} : { artifact: r.artifact }),
217
307
  ...(r.source === undefined ? {} : { source: r.source }),
308
+ ...(typeof r.tested === "string" ? { tested: r.tested } : {}),
309
+ ...(r.failedTests === undefined ? {} : { failedTests: r.failedTests }),
310
+ ...(r.failedTestsTruncated === undefined ? {} : { failedTestsTruncated: true }),
218
311
  ...r.evidence,
219
312
  };
220
313
  const problem = testRunProblem(row);
@@ -227,17 +320,19 @@ function appendTestRun(
227
320
  // Test-first: JUnit reading, plan `Test first:` lines, red / green judgement
228
321
  // ---------------------------------------------------------------------------
229
322
 
230
- /** The env var naming the JUnit report path `bkit:test:file` must write. */
231
- export const REPORT_ENV = "BKIT_TEST_REPORT";
232
323
  /** The status row step a group's red writes: one row per `tests red` run, a state and blob per planned test. */
233
324
  export const RED_STEP = "build-tests-red";
234
325
 
326
+ /** The status row step `steps finish` writes for a contradicted planned test: one row per takeover task it adds. */
327
+ export const TAKEOVER_STEP = "build-takeover";
328
+
235
329
  /** How a planned test stood at the group's red. */
236
330
  export type RedState =
237
331
  | "red"
238
332
  | "red-not-loaded"
239
333
  | "passed-accepted"
240
334
  | "updated"
335
+ | "taken-over"
241
336
  | "vacuous"
242
337
  | "missing"
243
338
  | "no-report"
@@ -259,20 +354,28 @@ export interface RedTest {
259
354
  block?: string | null;
260
355
  /** The tests step's reason, on `passed-accepted`. */
261
356
  reason?: string;
262
- /** On `updated`: the commit the group started at, where the test already existed. */
357
+ /**
358
+ * On `updated`: the commit the test already existed at — the group's start, or the run's
359
+ * start for a takeover.
360
+ */
263
361
  base?: string;
362
+ /** The earlier task this test was taken over from (`planTakeovers`), when that task has a baseline. */
363
+ from?: number;
264
364
  }
265
365
 
266
366
  /**
267
367
  * The states that count as a red: the test failed, its file did not load, the tests step
268
- * vouched for its pass, or it is an existing test updated and passing, whose diff the
269
- * verifier judges (it may add expectations, never remove or loosen one).
368
+ * vouched for its pass, it is an existing test updated and passing, whose diff the
369
+ * verifier judges (it may add expectations, never remove or loosen one), or it is a test
370
+ * taken over from an earlier task, written in this build and passing after its rewrite
371
+ * (reported as changed hands, not proven failing).
270
372
  */
271
373
  export const RED_PROVEN: ReadonlySet<RedState> = new Set([
272
374
  "red",
273
375
  "red-not-loaded",
274
376
  "passed-accepted",
275
377
  "updated",
378
+ "taken-over",
276
379
  ]);
277
380
 
278
381
  /** The `build-tests-red` rows of `workflow` in status.jsonl, in file order; `group` narrows. */
@@ -335,26 +438,178 @@ export function redEntries(file: string, workflow: string, group?: number): Map<
335
438
  return out;
336
439
  }
337
440
 
441
+ /**
442
+ * The plan beside a run's status file: `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` →
443
+ * `docs/plans/{YYYYMM}/{FID}-plan.md`.
444
+ */
445
+ export function runPlanPath(statusFile: string): string {
446
+ const logs = path.dirname(statusFile);
447
+ return path.join(path.dirname(path.dirname(logs)), `${path.basename(logs)}-plan.md`);
448
+ }
449
+
338
450
  /** A planned test that differs from how the group's tests step left it. */
339
451
  export interface TouchedTest {
340
452
  test: string;
341
453
  name: string;
342
454
  }
343
455
 
456
+ /** A changed planned test, with what `finish` records when a BLOCKED line lets it through. */
457
+ export interface TouchedDetail extends TouchedTest {
458
+ task: number;
459
+ /** The test's current block hash; null when no line names it. */
460
+ block: string | null;
461
+ /** The blob of the baseline's text (the red's blob, or a change record's `after`); null when unknown. */
462
+ text: string | null;
463
+ /** The blob of the first baseline of the chain (the red's, or the first change's `blob`). */
464
+ origin: string | null;
465
+ /** True when the baseline is a code step's `changedTests` record. */
466
+ fromChange: boolean;
467
+ /** True when no per-test block exists, so the whole file's blob stands in for the test. */
468
+ wholeFile: boolean;
469
+ }
470
+
471
+ /** The lock's baseline for one planned test: its latest red or recorded change. */
472
+ export interface LockBaseline extends RedTest {
473
+ /** Every reason a code step's `changedTests` record carried for this test, in order. */
474
+ reasons: string[];
475
+ /** True when the newest record for this test is a code step's `changedTests` entry. */
476
+ fromChange: boolean;
477
+ /** The blob of the baseline's text; null when unknown. */
478
+ text: string | null;
479
+ /** The blob of the chain's first baseline (what `tests green` diffs against); null when unknown. */
480
+ origin: string | null;
481
+ }
482
+
344
483
  /**
345
- * The planned tests of `group` a code step changed since their red: a test whose own lines
346
- * (`testBlock`) no longer hash to the recorded block. A row with no block (written before
347
- * per-test locking, or when no line carried the name) derives the block from the recorded
348
- * blob; when that holds no block either, the whole file's blob is compared. Other edits to a
349
- * test file are free.
484
+ * The lock's baseline per planned test, from the status rows in order: every `build-tests-red`
485
+ * entry (a proven red is never replaced by an unproven result for the same lines) and every
486
+ * `changedTests` record of a code step; the latest per key wins. `planned` (the plan-named key
487
+ * set) limits the keys; null keeps them all.
488
+ */
489
+ export function lockBaselines(
490
+ rows: Array<Record<string, unknown>>,
491
+ planned: Set<string> | null,
492
+ ): Map<string, LockBaseline> {
493
+ const out = new Map<string, LockBaseline>();
494
+ /** The newest blob any red recorded per test file (a later tests step's additions included). */
495
+ const newestBlob = new Map<string, string>();
496
+ for (const row of rows) {
497
+ if (row.type !== "step-done") continue;
498
+ if (row.step === RED_STEP && typeof row.group === "number") {
499
+ for (const t of redTestsOf(row)) {
500
+ if (t.blob !== null) newestBlob.set(t.test, t.blob);
501
+ const key = redKey(t.task, t.test, t.testName);
502
+ if (planned !== null && !planned.has(key)) continue;
503
+ const earlier = out.get(key);
504
+ const keepsProof =
505
+ earlier !== undefined &&
506
+ RED_PROVEN.has(earlier.state) &&
507
+ !RED_PROVEN.has(t.state) &&
508
+ typeof earlier.block === "string" &&
509
+ earlier.block === t.block;
510
+ if (!keepsProof)
511
+ out.set(key, {
512
+ ...t,
513
+ reasons: earlier?.reasons ?? [],
514
+ fromChange: false,
515
+ text: t.blob,
516
+ origin: t.blob,
517
+ });
518
+ // A takeover's entry, whatever its state, is the new baseline of every earlier key
519
+ // naming the same test: the earlier task's lock moves onto the taken-over lines.
520
+ if (t.from === undefined) continue;
521
+ for (const [k, b] of out)
522
+ if (k !== key && b.test === t.test && sameTestName(b.testName, t.testName))
523
+ out.set(k, {
524
+ ...b,
525
+ state: t.state,
526
+ blob: t.blob,
527
+ block: t.block,
528
+ fromChange: false,
529
+ text: t.blob,
530
+ origin: t.blob,
531
+ });
532
+ }
533
+ }
534
+ if (CODE_STEPS.has(String(row.step)) && Array.isArray(row.changedTests)) {
535
+ for (const c of row.changedTests as Array<Record<string, unknown>>) {
536
+ if (typeof c.task !== "number" || typeof c.test !== "string") continue;
537
+ if (typeof c.testName !== "string") continue;
538
+ if (typeof c.reason !== "string" || c.reason === "") continue;
539
+ const key = redKey(c.task, c.test, c.testName);
540
+ if (planned !== null && !planned.has(key)) continue;
541
+ const earlier = out.get(key);
542
+ out.set(key, {
543
+ task: c.task,
544
+ test: c.test,
545
+ testName: c.testName,
546
+ state: "red",
547
+ blob: null,
548
+ block: typeof c.block === "string" ? c.block : null,
549
+ fromChange: true,
550
+ text: typeof c.after === "string" ? c.after : null,
551
+ origin: earlier?.origin ?? (typeof c.blob === "string" ? c.blob : null),
552
+ reasons: [
553
+ ...(earlier?.reasons ?? []),
554
+ ...(typeof c.reason === "string" ? [c.reason] : []),
555
+ ],
556
+ });
557
+ }
558
+ }
559
+ }
560
+ // A test no line names (block null) is locked by its whole file, against the file's newest red blob.
561
+ for (const b of out.values()) {
562
+ const blob = newestBlob.get(b.test);
563
+ if (b.fromChange || b.block !== null || blob === undefined || b.blob === null) continue;
564
+ b.blob = blob;
565
+ b.text = blob;
566
+ b.origin = blob;
567
+ }
568
+ return out;
569
+ }
570
+
571
+ /** The code steps whose `changedTests` records move the lock's baseline. */
572
+ const CODE_STEPS = new Set([
573
+ "build-plan-tasks",
574
+ "build-plan-gaps-remediate",
575
+ "build-plan-gaps-remediate-holistic",
576
+ ]);
577
+
578
+ /** The status rows of one workflow. */
579
+ export const workflowRows = (file: string, workflow: string) =>
580
+ fs.existsSync(file)
581
+ ? (readStatusRows(file) as Array<Record<string, unknown>>).filter(
582
+ (r) => r.workflow === workflow,
583
+ )
584
+ : [];
585
+
586
+ /** The key set of the tests a plan's `TEST FIRST` lines name (done tasks included), or null with no plan. */
587
+ function plannedKeys(plan: string | undefined): Set<string> | null {
588
+ return plan === undefined
589
+ ? null
590
+ : new Set(
591
+ readTestFirst(plan).flatMap((s) =>
592
+ s.kind === "test" ? s.tests.map((t) => redKey(s.task, t.test, t.name)) : [],
593
+ ),
594
+ );
595
+ }
596
+
597
+ /**
598
+ * The planned tests (every group) a code step changed since their baseline (`lockBaselines`): a
599
+ * test whose own lines (`testBlock`) no longer hash to the recorded block. A record with no
600
+ * block (written before per-test locking, or when no line carried the name) derives the block
601
+ * from the recorded blob; when that holds no block either, the whole file's blob is compared.
602
+ * Other edits to a test file are free. With `plan` (the plan's text), only tests a `TEST FIRST`
603
+ * line still names are checked: a name the plan dropped locks nothing. Each result carries the
604
+ * test's task, its current block and the reasons already recorded, for `finish`.
350
605
  */
351
606
  export function touchedTests(
352
607
  top: string,
353
608
  file: string,
354
609
  workflow: string,
355
- group: number,
356
- ): TouchedTest[] {
357
- const touched: TouchedTest[] = [];
610
+ plan?: string,
611
+ ): Array<TouchedDetail & { reasons: string[] }> {
612
+ const touched: Array<TouchedDetail & { reasons: string[] }> = [];
358
613
  const texts = new Map<string, string | null>();
359
614
  const textOf = (test: string) => {
360
615
  if (!texts.has(test)) {
@@ -363,20 +618,54 @@ export function touchedTests(
363
618
  }
364
619
  return texts.get(test)!;
365
620
  };
366
- for (const t of redEntries(file, workflow, group).values()) {
621
+ for (const t of lockBaselines(workflowRows(file, workflow), plannedKeys(plan)).values()) {
622
+ const now = blockHash(textOf(t.test), t.testName);
623
+ const hit = (wholeFile: boolean) =>
624
+ touched.push({
625
+ test: t.test,
626
+ name: t.testName,
627
+ task: t.task,
628
+ block: now,
629
+ reasons: t.reasons,
630
+ text: t.text,
631
+ origin: t.origin,
632
+ fromChange: t.fromChange,
633
+ wholeFile,
634
+ });
367
635
  let block = t.block ?? null;
368
636
  if (block === null) block = blockHash(blobText(top, t.blob), t.testName);
369
637
  if (block === null) {
370
- if (git(top, ["hash-object", "--", t.test]) !== t.blob)
371
- touched.push({ test: t.test, name: t.testName });
638
+ if (t.blob === null && t.fromChange) {
639
+ if (now !== null && t.reasons.length > 0) hit(true);
640
+ continue;
641
+ }
642
+ if (git(top, ["hash-object", "--", t.test]) !== t.blob) hit(true);
372
643
  continue;
373
644
  }
374
- if (blockHash(textOf(t.test), t.testName) !== block)
375
- touched.push({ test: t.test, name: t.testName });
645
+ if (now !== block) hit(false);
376
646
  }
377
647
  return touched;
378
648
  }
379
649
 
650
+ /**
651
+ * The line diff of the test's own lines from the baseline text `blob` to the file now, and
652
+ * whether it only adds lines; null when either side cannot be read.
653
+ */
654
+ export function baselineDiff(
655
+ top: string,
656
+ blob: string | null,
657
+ test: string,
658
+ name: string,
659
+ ): { additive: boolean; diff: string } | null {
660
+ // A null blob is a red that recorded the file `missing`: every line of the test is added.
661
+ const was = blob === null ? "" : testBlock(blobText(top, blob), name);
662
+ const abs = path.join(top, test);
663
+ const now = fs.existsSync(abs) ? testBlock(fs.readFileSync(abs, "utf-8"), name) : null;
664
+ if (was === null || now === null) return null;
665
+ const d = lineDiff(was, now);
666
+ return { additive: d.removed === 0, diff: d.text };
667
+ }
668
+
380
669
  /** The text a recorded blob holds, untrimmed; null when the object store lacks it. */
381
670
  function blobText(top: string, blob: string | null): string | null {
382
671
  if (blob === null) return null;
@@ -481,7 +770,7 @@ export function lineDiff(
481
770
  before: string,
482
771
  after: string,
483
772
  ): { text: string; removed: number; added: number } {
484
- const a = before.split("\n");
773
+ const a = before === "" ? [] : before.split("\n");
485
774
  const b = after.split("\n");
486
775
  const lcs: number[][] = Array.from({ length: a.length + 1 }, () =>
487
776
  new Array<number>(b.length + 1).fill(0),
@@ -539,65 +828,6 @@ const NO_TEST_FILE_HINT =
539
828
  `argument and writes a JUnit report to $${REPORT_ENV} ` +
540
829
  "(.bkit/workflows.md § Local gate scripts)";
541
830
 
542
- export type CaseState = "passed" | "failure" | "error" | "skipped";
543
- export interface JunitCase {
544
- name: string;
545
- state: CaseState;
546
- /** The failure element's `message` attribute: the runner's one-line summary. */
547
- message: string;
548
- /** The failure element's text: the assertion output, where some runners put the detail. */
549
- detail: string;
550
- }
551
-
552
- const XML_ENTITIES: Record<string, string> = {
553
- amp: "&",
554
- lt: "<",
555
- gt: ">",
556
- quot: '"',
557
- apos: "'",
558
- };
559
-
560
- function decodeXml(s: string): string {
561
- return s.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, e: string) => {
562
- if (!e.startsWith("#")) return XML_ENTITIES[e.toLowerCase()] ?? whole;
563
- const cp = /^#x/i.test(e) ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
564
- return cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : whole;
565
- });
566
- }
567
-
568
- const ATTRS = String.raw`((?:\s+[\w:.-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)`;
569
-
570
- function attr(attrs: string, name: string): string | undefined {
571
- const m = new RegExp(String.raw`\s${name}\s*=\s*(?:"([^"]*)"|'([^']*)')`).exec(attrs);
572
- return m ? decodeXml(m[1] ?? m[2] ?? "") : undefined;
573
- }
574
-
575
- /** CDATA text as escaped character data, so a tag inside it never ends an element early. */
576
- const escapeCdata = (xml: string) =>
577
- xml.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, text: string) =>
578
- text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"),
579
- );
580
-
581
- /** Every `<testcase>` in a JUnit report: its name, outcome, first failure message and detail. */
582
- export function parseJunit(xml: string): JunitCase[] {
583
- const body = escapeCdata(xml).replace(/<!--[\s\S]*?-->/g, "");
584
- const cases: JunitCase[] = [];
585
- const testcase = new RegExp(String.raw`<testcase${ATTRS}\s*(?:\/>|>([\s\S]*?)<\/testcase>)`, "g");
586
- const outcome = new RegExp(
587
- String.raw`<(failure|error|skipped)${ATTRS}\s*(?:\/>|>([\s\S]*?)<\/\1>)`,
588
- );
589
- for (const m of body.matchAll(testcase)) {
590
- const child = outcome.exec(m[2] ?? "");
591
- cases.push({
592
- name: attr(m[1] ?? "", "name") ?? "",
593
- state: child ? (child[1] as CaseState) : "passed",
594
- message: child ? (attr(child[2] ?? "", "message") ?? "") : "",
595
- detail: child ? decodeXml((child[3] ?? "").replace(/<[^>]*>/g, "")).trim() : "",
596
- });
597
- }
598
- return cases;
599
- }
600
-
601
831
  /** A report case is the named test when its name is the name, or ends with it as the last segment. */
602
832
  export const isNamedCase = (caseName: string, want: string) =>
603
833
  caseName === want || caseName.endsWith(` ${want}`);
@@ -692,26 +922,107 @@ export const TEST_EXCEPTION = "**TEST EXCEPTION:**";
692
922
  /** The plan caps `package.json` `bkit.workflows.tasks` sets for the checkout `cwd` sits in. */
693
923
  export const planCaps = (cwd: string): TaskCaps => readBkitConfig(toplevel(cwd)).tasks;
694
924
 
925
+ /** `ledgers check` on the plan text as plan-check problems: the line absent or unfilled, or each key with no row. */
926
+ function ledgerRowProblems(root: string, text: string): PlanProblem[] {
927
+ const r = readPlanRows(root, text);
928
+ if (r.unreadable !== undefined)
929
+ return [
930
+ {
931
+ line: r.line,
932
+ kind: "ledger",
933
+ message: `${r.unreadable} — list each decision / deferral row key written for this plan, or write None`,
934
+ },
935
+ ];
936
+ if (r.missing.length === 0) return [];
937
+ return [
938
+ {
939
+ line: r.line,
940
+ kind: "ledger",
941
+ message: `no docs/decisions.jsonl or docs/deferrals.jsonl row for ${r.missing.map((k) => `\`${k}\``).join(", ")} — write each missing row, or correct the **Ledger rows:** line`,
942
+ },
943
+ ];
944
+ }
945
+
695
946
  /** The caps as the plan-check report and help state them. */
696
947
  export const capsText = (c: TaskCaps) =>
697
948
  `${c.maxPerGroup} tasks and ${c.maxTestsPerGroup} TEST FIRST tests per group; ${c.maxTestsPerTask} tests across ${c.maxTestFilesPerTask} test files per task`;
698
949
 
699
- /** A task block's TEST FIRST read as one `TestFirst`; a TEST EXCEPTION with no TEST FIRST is its `n/a`. */
950
+ /** A later task's planned test that an earlier task of the plan also names. */
951
+ export interface Takeover {
952
+ /** The later task, whose TEST FIRST names the test. */
953
+ task: number;
954
+ /** The nearest earlier task (plan order) naming the same test. */
955
+ from: number;
956
+ test: string;
957
+ /** The name as the later task writes it. */
958
+ name: string;
959
+ /** 1-based plan line of the later task's TEST FIRST entry. */
960
+ line: number;
961
+ /** True when both tasks sit in one group. */
962
+ sameGroup: boolean;
963
+ }
964
+
965
+ /** The test a JUnit-style suite path (`suite > test`) names: its last segment. */
966
+ const lastSegment = (name: string) => name.split(" > ").pop()!.trim();
967
+
968
+ /**
969
+ * Two planned test names name one test: equal, or, when one of them has no ` > ` (a bare
970
+ * test name against a suite path), equal in their last segment. Two suite paths must match
971
+ * whole: `a > works` and `b > works` are two tests.
972
+ */
973
+ export const sameTestName = (a: string, b: string) =>
974
+ a === b || ((!a.includes(" > ") || !b.includes(" > ")) && lastSegment(a) === lastSegment(b));
975
+
976
+ /**
977
+ * Every planned test a later task names that an earlier task (plan order, done tasks
978
+ * included) also names in the same file: the later task takes the test over. `from` is
979
+ * the nearest earlier task naming it. Paths compare posix-normalized; names compare per
980
+ * `sameTestName`.
981
+ */
982
+ export function planTakeovers(text: string): Takeover[] {
983
+ const seen: Array<{ task: number; group: number; test: string; name: string }> = [];
984
+ const out: Takeover[] = [];
985
+ for (const t of parsePlanBlocks(text).tasks) {
986
+ const mine = t.testFirst?.tests ?? [];
987
+ for (const x of mine) {
988
+ const test = path.posix.normalize(x.test);
989
+ const owner = [...seen]
990
+ .reverse()
991
+ .find((s) => s.test === test && sameTestName(s.name, x.name));
992
+ if (owner !== undefined)
993
+ out.push({
994
+ task: t.task,
995
+ from: owner.task,
996
+ test,
997
+ name: x.name,
998
+ line: x.line,
999
+ sameGroup: owner.group === t.group,
1000
+ });
1001
+ }
1002
+ for (const x of mine)
1003
+ seen.push({ task: t.task, group: t.group, test: path.posix.normalize(x.test), name: x.name });
1004
+ }
1005
+ return out;
1006
+ }
1007
+
700
1008
  /**
701
1009
  * Planned tests of open tasks whose name a test in their file already carries: the tests
702
1010
  * step cannot write a new test under that name, so it either updates the existing one or
703
- * finds it passing. Reported only — the plan names the update, or a new name.
1011
+ * finds it passing. Reported only — the plan names the update, or a new name. A test the
1012
+ * task takes over from an earlier task (`planTakeovers`) is left out.
704
1013
  */
705
1014
  function existingTestNames(
706
1015
  text: string,
707
1016
  top: string,
708
1017
  ): Array<{ line: number; task: number; test: string; name: string }> {
709
1018
  const out: Array<{ line: number; task: number; test: string; name: string }> = [];
1019
+ const takenOver = new Set(planTakeovers(text).map((k) => redKey(k.task, k.test, k.name)));
710
1020
  for (const t of parsePlanBlocks(text).tasks) {
711
1021
  if (t.done) continue;
712
1022
  const s = testFirstOf(t);
713
1023
  if (s.kind !== "test") continue;
714
1024
  for (const x of s.tests) {
1025
+ if (takenOver.has(redKey(t.task, x.test, x.name))) continue;
715
1026
  const abs = path.join(top, x.test);
716
1027
  if (!fs.existsSync(abs)) continue;
717
1028
  if (testBlock(fs.readFileSync(abs, "utf-8"), x.name) !== null)
@@ -721,6 +1032,7 @@ function existingTestNames(
721
1032
  return out;
722
1033
  }
723
1034
 
1035
+ /** A task block's TEST FIRST read as one `TestFirst`; a TEST EXCEPTION with no TEST FIRST is its `n/a`. */
724
1036
  function testFirstOf(t: PlanTaskBlock): TestFirst {
725
1037
  const { task, testFirst: tf, testException: exc } = t;
726
1038
  const plain = (tests: PlannedTest[]) => tests.map(({ test, name }) => ({ test, name }));
@@ -785,7 +1097,8 @@ export interface PlanProblem {
785
1097
  | "inventory"
786
1098
  | "matrix"
787
1099
  | "supersession"
788
- | "markers";
1100
+ | "markers"
1101
+ | "ledger";
789
1102
  message: string;
790
1103
  }
791
1104
 
@@ -895,18 +1208,34 @@ export function checkPlanText(text: string, caps: TaskCaps = CONFIG_DEFAULTS.tas
895
1208
  // matrix section yields no problem: the refusal is on a row, and issue-form plans carry none.
896
1209
  const matrix = derivedTestMatrix(text);
897
1210
  if (matrix !== null) {
898
- if (matrix.taskColumn === null)
1211
+ const expected = "Test description | Type | Target file | Task";
1212
+ const header = (matrix.head[0] ?? "")
1213
+ .split("|")
1214
+ .slice(1, -1)
1215
+ .map((c) => c.trim().toLowerCase())
1216
+ .join(" | ");
1217
+ if (header !== expected.toLowerCase())
899
1218
  problems.push({
900
1219
  line: matrix.line,
901
1220
  kind: "matrix",
902
- message:
903
- "the Derived Test Matrix header has no `Task` column; add one naming the task each row's test belongs to",
1221
+ message: `the Derived Test Matrix header must be exactly \`${expected}\`, in that order with no other columns`,
904
1222
  });
905
- else {
1223
+ if (matrix.taskColumn !== null) {
906
1224
  const mapped = new Set<number>();
907
1225
  for (const row of matrix.rows) {
908
1226
  const named = row.tasks.map((n) => `TASK ${n}`);
909
- if (row.tasks.length === 0)
1227
+ const taskCell = (row.cells[matrix.taskColumn] ?? "").trim();
1228
+ if (
1229
+ row.cells.length !== 4 ||
1230
+ (taskCell !== "" &&
1231
+ !/^(?:task\s*)?\d+(?:\s*(?:,|and)\s*(?:task\s*)?\d+)*$/i.test(taskCell))
1232
+ )
1233
+ problems.push({
1234
+ line: row.number,
1235
+ kind: "matrix",
1236
+ message: `Derived Test Matrix row must have 4 cells in the template's order, with only task numbers (\`N\` or \`TASK N\`) in its \`Task\` cell`,
1237
+ });
1238
+ else if (row.tasks.length === 0)
910
1239
  problems.push({
911
1240
  line: row.number,
912
1241
  kind: "matrix",
@@ -1118,22 +1447,6 @@ export function planExistence(text: string, root: string): ExistenceFinding[] {
1118
1447
  return out.sort((a, b) => a.line - b.line);
1119
1448
  }
1120
1449
 
1121
- /** Run one test file through `bkit:test:file`; the report is read and removed. */
1122
- function runTestFile(
1123
- top: string,
1124
- test: string,
1125
- log: string,
1126
- ): { exitCode: number; cases: JunitCase[] | null } {
1127
- const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bkit-test-report-"));
1128
- const report = path.join(dir, "junit.xml");
1129
- const exitCode = runToLog([...scriptCommand(BKIT_TEST_FILE_SCRIPT), test], top, log, {
1130
- [REPORT_ENV]: report,
1131
- });
1132
- const cases = fs.existsSync(report) ? parseJunit(fs.readFileSync(report, "utf-8")) : null;
1133
- fs.rmSync(dir, { recursive: true, force: true });
1134
- return { exitCode, cases };
1135
- }
1136
-
1137
1450
  const couldNotRunMessage = (exitCode: number) =>
1138
1451
  `${gateScope(BKIT_TEST_FILE_SCRIPT)} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no test executed`;
1139
1452
 
@@ -1411,6 +1724,32 @@ interface Unproven {
1411
1724
  detail: string;
1412
1725
  }
1413
1726
 
1727
+ /** A planned test a code step changed under a BLOCKED line: the owner answers it at the end of the build. */
1728
+ interface Changed {
1729
+ task: number;
1730
+ test: string;
1731
+ name: string;
1732
+ reason: string;
1733
+ /** The test's own-line diff from its baseline; null when a side cannot be read. */
1734
+ diff: string | null;
1735
+ additive: boolean | null;
1736
+ }
1737
+
1738
+ /**
1739
+ * A planned test a later task took over: `from` is the earlier owner; `diff` / `additive`
1740
+ * compare the test's own lines at the owner's red with the file now (null when a side
1741
+ * cannot be read). Never a gap and never unproven.
1742
+ */
1743
+ interface TakenOver {
1744
+ task: number;
1745
+ from: number;
1746
+ test: string;
1747
+ name: string;
1748
+ state: RedState;
1749
+ additive: boolean | null;
1750
+ diff: string | null;
1751
+ }
1752
+
1414
1753
  /**
1415
1754
  * An existing test the tests step changed: the verifier judges its diff since `base`.
1416
1755
  * `additive` = the test's own lines since `base` gained lines and lost none (null when
@@ -1444,6 +1783,23 @@ function updatedEntry(
1444
1783
  return { ...entry, additive: d.removed === 0, diff: d.text };
1445
1784
  }
1446
1785
 
1786
+ /** The `TakenOver` entry for a red entry carrying `from`: its lines at the owner's red against now. */
1787
+ function takenOverEntry(top: string, reds: Map<string, RedTest>, red: RedTest): TakenOver {
1788
+ const owner = [...reds.values()].find(
1789
+ (r) => r.task === red.from && r.test === red.test && sameTestName(r.testName, red.testName),
1790
+ );
1791
+ const d = owner === undefined ? null : baselineDiff(top, owner.blob, red.test, red.testName);
1792
+ return {
1793
+ task: red.task,
1794
+ from: red.from!,
1795
+ test: red.test,
1796
+ name: red.testName,
1797
+ state: red.state,
1798
+ additive: d?.additive ?? null,
1799
+ diff: d?.diff ?? null,
1800
+ };
1801
+ }
1802
+
1447
1803
  /** A planned test the group's red did not prove, and why. */
1448
1804
  interface RedGap {
1449
1805
  task: number;
@@ -1459,6 +1815,27 @@ interface PassesLine extends PlannedTest {
1459
1815
  reason: string;
1460
1816
  }
1461
1817
 
1818
+ /** A ``BLOCKED — {TASK N|Gap N}: test `{file}` `{name}` — {why}`` line of a code step's log. */
1819
+ export interface BlockedTest extends PlannedTest {
1820
+ reason: string;
1821
+ /** The task a `TASK N` line names; null for a `Gap N` line. */
1822
+ task: number | null;
1823
+ }
1824
+
1825
+ /** Every BLOCKED line of a code step's log that names a planned test, with its reason. */
1826
+ export function blockedTests(log: string): BlockedTest[] {
1827
+ return [
1828
+ ...log.matchAll(
1829
+ /^BLOCKED\s*[—–-]+\s*(TASK|Gap)\s+(\d+):\s*test\s+`([^`]+)`\s+`([^`]+)`\s*[—–-]+\s*(.+)$/gm,
1830
+ ),
1831
+ ].map((m) => ({
1832
+ test: m[3]!.trim(),
1833
+ name: m[4]!.trim(),
1834
+ reason: m[5]!.trim(),
1835
+ task: m[1] === "TASK" ? Number(m[2]) : null,
1836
+ }));
1837
+ }
1838
+
1462
1839
  /** Every PASSES line of a tests step's log: the tests the writer saw passing and vouches for. */
1463
1840
  function passesLines(log: string): PassesLine[] {
1464
1841
  return [
@@ -1551,6 +1928,8 @@ function writeAuditReport(
1551
1928
  landed: Landed[];
1552
1929
  unproven: Unproven[];
1553
1930
  updated: Updated[];
1931
+ takenOver: TakenOver[];
1932
+ changed: Changed[];
1554
1933
  outputs: Array<{ test: string; tail: string }>;
1555
1934
  },
1556
1935
  ): void {
@@ -1575,7 +1954,7 @@ function writeAuditReport(
1575
1954
  if (o.gaps.length === 0) out.push("None.");
1576
1955
  for (const g of o.gaps)
1577
1956
  out.push(
1578
- `- ${g.task === null ? "Plan" : `Task ${g.task}`} \`${g.kind}\` — ${g.detail} — Fixable: ${g.fixable} — log: ${g.logLine}`,
1957
+ `- ${g.task === null ? "Plan" : `Task ${g.task}`} \`${g.kind}\` — ${oneLine(g.detail)} — Fixable: ${g.fixable} — log: ${g.logLine}`,
1579
1958
  );
1580
1959
  if (o.exceptions.length > 0) out.push("", "## Test exceptions", "");
1581
1960
  for (const e of o.exceptions)
@@ -1606,11 +1985,35 @@ function writeAuditReport(
1606
1985
  out.push("", ` ${fence}diff`, ...u.diff.split("\n").map((l) => ` ${l}`), ` ${fence}`, "");
1607
1986
  }
1608
1987
  }
1988
+ if (o.takenOver.length > 0) out.push("", "## Taken over", "");
1989
+ for (const t of o.takenOver) {
1990
+ const judged =
1991
+ t.state === "taken-over"
1992
+ ? "changed hands and passes after the rewrite: not proven failing, and never a gap"
1993
+ : `recorded \`${t.state}\` after the rewrite`;
1994
+ out.push(
1995
+ `- Task ${t.task} \`${t.test}\` "${t.name}" — taken over from Task ${t.from}; ${judged}`,
1996
+ );
1997
+ if (t.diff !== null) {
1998
+ const fence = fenceFor(t.diff);
1999
+ out.push("", ` ${fence}diff`, ...t.diff.split("\n").map((l) => ` ${l}`), ` ${fence}`, "");
2000
+ }
2001
+ }
1609
2002
  if (o.unproven.length > 0) out.push("", "## Unproven", "");
1610
2003
  for (const u of o.unproven)
1611
2004
  out.push(
1612
2005
  `- Task ${u.task} \`${u.test}\` "${u.name}" — ${u.detail}; the owner answers it at the end of the build`,
1613
2006
  );
2007
+ if (o.changed.length > 0) out.push("", "## Changed by a code step", "");
2008
+ for (const c of o.changed) {
2009
+ out.push(
2010
+ `- Task ${c.task} \`${c.test}\` "${c.name}" — a code step changed it under a BLOCKED line: ${c.reason}; the owner answers it at the end of the build`,
2011
+ );
2012
+ if (c.diff !== null) {
2013
+ const fence = fenceFor(c.diff);
2014
+ out.push("", ` ${fence}diff`, ...c.diff.split("\n").map((l) => ` ${l}`), ` ${fence}`, "");
2015
+ }
2016
+ }
1614
2017
  for (const t of o.outputs) {
1615
2018
  const fence = fenceFor(t.tail);
1616
2019
  out.push("", `## Runner output — \`${t.test}\``, "", fence, t.tail, fence);
@@ -1624,10 +2027,12 @@ export const testsCommand: CommandSpec = {
1624
2027
  summary:
1625
2028
  "Run the deepest declared local gate, or one test file to record a red and audit a green.",
1626
2029
  verbs: {
2030
+ base: testsBaseVerb,
1627
2031
  changed: testsChangedVerb,
2032
+ jump: testsJumpVerb,
1628
2033
  run: {
1629
2034
  summary:
1630
- "Run the first declared --gate, and with --file append a test-run status row for the run; exit 0 PASS, 1 FAIL, 4 could not run, 81 tests lock held.",
2035
+ "Run the first declared --gate, or with --changed-since only the files changed since that commit, and with --file append a test-run status row for the run; exit 0 PASS (also when nothing changed), 1 FAIL, 4 could not run, 81 tests lock held (read from the lock status file, never from the exit code alone).",
1631
2036
  use: "by-hand",
1632
2037
  flags: [
1633
2038
  {
@@ -1675,6 +2080,16 @@ export const testsCommand: CommandSpec = {
1675
2080
  help: "status.jsonl: append one test-run row for this run, pass or fail; needs --workflow and --step",
1676
2081
  },
1677
2082
  { name: "workflow", type: "string", help: "--file: workflow name, for the test-run row" },
2083
+ {
2084
+ name: "changed-since",
2085
+ type: "string",
2086
+ help: `commit the work began on, or \`${FEATURE_BASE_WORD}\` for the feature's start commit (\`origin/dev\` when it cannot be worked out): run \`${BKIT_GATE_CHANGED_SCRIPT}\` on the files changed since it (uncommitted and committed) plus the files that mention a deleted one, recording the file count as the scope; a failed search for those files, or an undeclared \`${BKIT_GATE_CHANGED_SCRIPT}\` → the --gate runs whole`,
2087
+ },
2088
+ {
2089
+ name: "since-pass-of",
2090
+ type: "string",
2091
+ help: `step[,step...]: measure from the \`tested\` snapshot of the newest PASS test-run row of these steps in --workflow whose snapshot still exists; with none, from --changed-since; needs --file, --workflow and --changed-since`,
2092
+ },
1678
2093
  { name: "ci-run", type: "string", help: "selected GitHub evidence run ID" },
1679
2094
  { name: "ci-url", type: "string", help: "selected GitHub evidence attempt URL" },
1680
2095
  ],
@@ -1692,13 +2107,13 @@ export const testsCommand: CommandSpec = {
1692
2107
  exitCode: "the gate's exit code",
1693
2108
  gate: "the script that ran",
1694
2109
  scope: "the command that ran, as status rows record it",
1695
- failures: `0 on PASS; on FAIL the failing + erroring test cases in the JUnit reports, or null when no report counts any (unknown, never 0)`,
2110
+ failures: `0 on PASS; on FAIL the failing + erroring test cases in the JUnit reports, or null when no report counts any (unknown, never 0); a CI evidence round: the selected run's failed jobs without the capstone, or null`,
1696
2111
  reports: `{log}.reports — emptied before the run and passed to the gate as $${REPORT_DIR_ENV}`,
1697
2112
  log: "where the full output was saved (as given); the untouched original",
1698
2113
  logBytes: "size of the saved output",
1699
2114
  artifact: "--artifact as given, else null",
1700
2115
  clamp: "the artifact's clamp record (raw = the log, source = scope), else null",
1701
- row: `the ${TEST_RUN_ROW} row appended to --file ({type, workflow, at, step, attempt?, run, verdict, exitCode, failures, scope, log, artifact?}; run = this step's test-run rows in the workflow's active run, this one included), else null; a tests-lock wait writes no row`,
2116
+ row: `the ${TEST_RUN_ROW} row appended to --file ({type, workflow, at, step, attempt?, run, verdict, exitCode, failures, scope, log, artifact?, source, tested?, failedTests?, failedTestsTruncated?}; run = this step's test-run rows in the workflow's active run, this one included; tested = on a local row, the commit (no ref) holding the tree the gate ran on, left off when git cannot build it; failedTests = on a FAIL, each failing case as \`{file or classname} > {name}\` (a CI evidence round: \`job:{name}\` per failed job), unique, sorted, at most ${FAILED_TESTS_CAP}, failedTestsTruncated true when cut), else null; a tests-lock wait writes no row`,
1702
2117
  lockHolder: "tests-lock holder when the wait gave up, else null",
1703
2118
  },
1704
2119
  textOmit: ["clamp", "row"],
@@ -1805,18 +2220,19 @@ export const testsCommand: CommandSpec = {
1805
2220
  source: "ci",
1806
2221
  verdict: "FAIL",
1807
2222
  exitCode: null,
1808
- failures: null,
2223
+ failures: selection.failedJobCount ?? null,
1809
2224
  scope,
1810
2225
  log: logArg,
1811
2226
  artifact,
1812
2227
  evidence,
2228
+ ...failedTestsField((selection.failedJobs ?? []).map((job) => `job:${job}`)),
1813
2229
  });
1814
2230
  ctx.emit({
1815
2231
  source: "ci",
1816
2232
  verdict: "FAIL",
1817
2233
  scope,
1818
2234
  exitCode: null,
1819
- failures: null,
2235
+ failures: selection.failedJobCount ?? null,
1820
2236
  ...evidence,
1821
2237
  artifact,
1822
2238
  log: logArg,
@@ -1838,7 +2254,58 @@ export const testsCommand: CommandSpec = {
1838
2254
  // Gates are declared and run at the top of the checkout being tested (the
1839
2255
  // feature worktree), wherever in it the caller happens to stand.
1840
2256
  const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1841
- const gate = resolveGate(top, candidates);
2257
+ const passSteps = str(ctx.flags.sincePassOf)
2258
+ ?.split(",")
2259
+ .map((s) => s.trim())
2260
+ .filter(Boolean);
2261
+ if (
2262
+ passSteps !== undefined &&
2263
+ (status === undefined || ctx.flags.changedSince === undefined || passSteps.length === 0)
2264
+ )
2265
+ throw new CommandError(
2266
+ EXIT.USAGE,
2267
+ "--since-pass-of needs one or more steps, --file, --workflow and --changed-since",
2268
+ );
2269
+ const sinceRaw = sinceBase(top, str(ctx.flags.changedSince), ctx.log);
2270
+ if (
2271
+ sinceRaw !== undefined &&
2272
+ git(top, ["rev-parse", "-q", "--verify", `${sinceRaw}^{commit}`]) === null
2273
+ )
2274
+ throw new CommandError(EXIT.USAGE, `--changed-since ${sinceRaw} names no commit`);
2275
+ // The tree this run tests, taken before the gate starts.
2276
+ const tested = status === undefined ? null : snapshotTree(top);
2277
+ if (status !== undefined && tested === null)
2278
+ ctx.log("could not snapshot the working tree — the test-run row records no tested");
2279
+ // With --since-pass-of: the files that differ from the newest passing run's snapshot.
2280
+ const passDiff = (): { base: string; files: string[]; deleted: string[] } | null => {
2281
+ if (passSteps === undefined) return null;
2282
+ const pass = newestPass(top, status!, workflow!, passSteps, ctx.log);
2283
+ if (pass === null) {
2284
+ ctx.log(
2285
+ `no passing run of ${passSteps.join(", ")} to measure from — testing from --changed-since ${sinceRaw}`,
2286
+ );
2287
+ return null;
2288
+ }
2289
+ const diff = changedBetween(top, pass, tested);
2290
+ if (diff === null) {
2291
+ ctx.log(
2292
+ `could not list the files changed since the passing run at ${pass} — testing from --changed-since ${sinceRaw}`,
2293
+ );
2294
+ return null;
2295
+ }
2296
+ return { base: pass, ...diff };
2297
+ };
2298
+ let scoped: { files: string[]; deleted: string[] } | null = null;
2299
+ if (sinceRaw !== undefined && declares(top, BKIT_GATE_CHANGED_SCRIPT)) {
2300
+ const fromPass = passDiff();
2301
+ scoped =
2302
+ fromPass === null
2303
+ ? changedScope(top, sinceRaw, candidates, ctx.log)
2304
+ : changedScope(top, fromPass.base, candidates, ctx.log, fromPass);
2305
+ }
2306
+ const useChanged = scoped !== null;
2307
+ const changed = scoped?.files ?? [];
2308
+ const gate = useChanged ? BKIT_GATE_CHANGED_SCRIPT : resolveGate(top, candidates);
1842
2309
  if (gate === null) {
1843
2310
  const read = readPackageJson(top);
1844
2311
  if (!read.ok) ctx.log(`package.json at ${top} is ${read.reason}`);
@@ -1847,21 +2314,86 @@ export const testsCommand: CommandSpec = {
1847
2314
  );
1848
2315
  return EXIT_NO_GATE;
1849
2316
  }
1850
- const scope = gateScope(gate);
2317
+ const scope = useChanged
2318
+ ? `${gateScope(gate)} (${changed.length} changed file${changed.length === 1 ? "" : "s"})`
2319
+ : gateScope(gate);
1851
2320
  const log = path.resolve(ctx.cwd, logArg);
2321
+ if (scoped !== null && changed.length === 0) {
2322
+ ctx.log(
2323
+ scoped.deleted.length === 0
2324
+ ? `no files changed since ${sinceRaw} — nothing to run`
2325
+ : `only deleted files that no file mentions changed since ${sinceRaw} — nothing to run`,
2326
+ );
2327
+ const row =
2328
+ status === undefined
2329
+ ? null
2330
+ : appendTestRun(status, {
2331
+ workflow: workflow!,
2332
+ step: step!,
2333
+ attempt,
2334
+ verdict: "PASS",
2335
+ exitCode: 0,
2336
+ failures: 0,
2337
+ scope,
2338
+ log: logArg,
2339
+ artifact: undefined,
2340
+ source: "local",
2341
+ tested,
2342
+ });
2343
+ ctx.emit({
2344
+ source: "local",
2345
+ verdict: "PASS",
2346
+ exitCode: 0,
2347
+ gate,
2348
+ scope,
2349
+ failures: 0,
2350
+ reports: null,
2351
+ log: logArg,
2352
+ logBytes: 0,
2353
+ artifact: null,
2354
+ clamp: null,
2355
+ row,
2356
+ lockHolder: null,
2357
+ });
2358
+ return EXIT.OK;
2359
+ }
1852
2360
  const reports = freshReportDir(log);
1853
2361
  ctx.log(`running ${scope} — full output in ${logArg}`);
1854
2362
  const fetchedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
1855
2363
  const who = ["bkit tests run", gate, fid, step].filter(Boolean).join(" ");
1856
- const exitCode = runToLog(scriptCommand(gate), top, log, {
1857
- [REPORT_DIR_ENV]: reports,
1858
- LOCAL_STACK_LOCK_WAIT_S: String(waitS),
1859
- LOCAL_STACK_LOCK_WHO: who,
1860
- });
2364
+ // The gate's run under the tests lock, kept for the receipt's lock-wait check.
2365
+ const lock: { run?: LockedRun } = {};
2366
+ const runGate = () => {
2367
+ lock.run = runGateUnderLock(
2368
+ useChanged ? [...scriptCommand(gate), ...changed] : scriptCommand(gate),
2369
+ top,
2370
+ log,
2371
+ {
2372
+ [REPORT_DIR_ENV]: reports,
2373
+ LOCAL_STACK_LOCK_WAIT_S: String(waitS),
2374
+ LOCAL_STACK_LOCK_WHO: who,
2375
+ },
2376
+ );
2377
+ return lock.run.exitCode;
2378
+ };
2379
+ // The required full gate leaves a push receipt, so the branch's first push
2380
+ // reuses it; bookkeeping paths may be uncommitted, as every engine call writes one.
2381
+ const exitCode =
2382
+ sinceRaw === undefined && gate === requiredPushGate(top)
2383
+ ? runWithReceipt(
2384
+ top,
2385
+ gate,
2386
+ minPushPathspecs(readBkitConfig(top)),
2387
+ runGate,
2388
+ ctx.log,
2389
+ () => lock.run?.lock === "lock-wait",
2390
+ )
2391
+ : runGate();
1861
2392
  const logText = fs.readFileSync(log, "utf-8");
1862
- const lockExit = classifyLockExit({ exitCode, log: logText, who });
2393
+ // runWithReceipt always runs the gate, so lock.run is set here.
2394
+ const lockExit = lock.run?.lock ?? "gate";
1863
2395
  const lockWait = lockExit === "lock-wait";
1864
- const lockHolder = lockWait ? testsLockHolder(logText, who) : null;
2396
+ const lockHolder = lockWait ? (lock.run?.status?.holder ?? null) : null;
1865
2397
  const lines =
1866
2398
  lockExit === "gate"
1867
2399
  ? Number(tailRaw) > 0
@@ -1871,7 +2403,8 @@ export const testsCommand: CommandSpec = {
1871
2403
  for (const line of lines) ctx.log(line);
1872
2404
  const couldNotRun = lockExit === "could-not-run" || COULD_NOT_RUN_EXIT_CODES.has(exitCode);
1873
2405
  const verdict = couldNotRun || lockWait ? null : exitCode === 0 ? "PASS" : "FAIL";
1874
- const counted = lockExit === "gate" ? countReportFailures(reports) : null;
2406
+ const failing = lockExit === "gate" ? reportFailures(reports) : null;
2407
+ const counted = failing?.length ?? null;
1875
2408
  if (counted === null && lockExit === "gate") ctx.log(NO_REPORT_HINT);
1876
2409
  else if (verdict === "FAIL" && counted === 0)
1877
2410
  ctx.log(
@@ -1915,6 +2448,8 @@ export const testsCommand: CommandSpec = {
1915
2448
  log: logArg,
1916
2449
  artifact,
1917
2450
  source: "local",
2451
+ tested,
2452
+ ...failedTestsField(verdict === "FAIL" ? (failing ?? []).map(caseLabel) : []),
1918
2453
  });
1919
2454
  ctx.emit({
1920
2455
  source: "local",
@@ -1938,7 +2473,9 @@ export const testsCommand: CommandSpec = {
1938
2473
  if (lockWait) return EXIT.AGENT_WAIT;
1939
2474
  if (couldNotRun) {
1940
2475
  ctx.log(
1941
- `${scope} could not run (exit ${exitCode}: ${lockExit === "could-not-run" ? "tests lock refused" : exitCode === 126 ? "not executable" : "command not found"}) — no tests executed; this is not a FAIL verdict`,
2476
+ lock.run?.status?.outcome === "held-too-long"
2477
+ ? `${scope} could not finish (exit ${exitCode}: stopped at the tests-lock hold limit) — its tests have no result; this is not a FAIL verdict`
2478
+ : `${scope} could not run (exit ${exitCode}: ${lockExit === "could-not-run" ? "tests lock refused" : exitCode === 126 ? "not executable" : "command not found"}) — no tests executed; this is not a FAIL verdict`,
1942
2479
  );
1943
2480
  return EXIT_COULD_NOT_RUN;
1944
2481
  }
@@ -1948,7 +2485,7 @@ export const testsCommand: CommandSpec = {
1948
2485
  },
1949
2486
  red: {
1950
2487
  summary:
1951
- "Run every TEST FIRST test of one group's open tasks before any task code exists, and write one build-tests-red row holding a state and blob per planned test; a test an earlier row of the group proved red, its file unchanged since, is not run again. Exit 0 every test red, 1 a gap (a test passing, absent from its report, failing lint, or its file missing), 3 bkit:test:file undeclared (blobs recorded, nothing ran), 4 a script could not run.",
2488
+ "Run every TEST FIRST test of one group's open tasks before any task code exists, and write one build-tests-red row holding a state and blob per planned test; a test an earlier row of the group proved red, its file unchanged since, is not run again. A test a later task takes over from an earlier one (same file and name) carries `from`, and one that passes after the rewrite is recorded taken-over. Exit 0 every test red, 1 a gap (a test passing, absent from its report, failing lint, or its file missing), 3 bkit:test:file undeclared (blobs recorded, nothing ran), 4 a script could not run.",
1952
2489
  use: "workflow",
1953
2490
  flags: [
1954
2491
  FILE_FLAG,
@@ -1983,10 +2520,10 @@ export const testsCommand: CommandSpec = {
1983
2520
  reason: "why test-first is not enforced",
1984
2521
  attempt: "this group's build-tests-red rows so far, this one included",
1985
2522
  tests:
1986
- "[{task, test, testName, state, blob, reason?}] in plan order, the tests run now: state red | red-not-loaded | passed-accepted | vacuous | missing | no-report | lint | unknown; blob the test file's git blob as it stood (null when the file is missing); reason the tests step's, on passed-accepted",
2523
+ "[{task, test, testName, state, blob, reason?, base?, from?}] in plan order, the tests run now: state red | red-not-loaded | passed-accepted | updated | taken-over | vacuous | missing | no-report | lint | unknown; blob the test file's git blob as it stood (null when the file is missing); reason the tests step's, on passed-accepted; from the earlier task a takeover took the test over from (a passing takeover written in this build is taken-over, one that existed at the run start is updated with base the run's start commit)",
1987
2524
  skipped:
1988
2525
  "planned tests an earlier row of the group proved red, their file unchanged since: not run again, and not on this row",
1989
- gaps: "[{task, test, name, kind, detail}]: every planned test whose state is not red, red-not-loaded or passed-accepted; kind is the state",
2526
+ gaps: "[{task, test, name, kind, detail}]: every planned test whose state is not red, red-not-loaded, passed-accepted, updated or taken-over; kind is the state",
1990
2527
  row: "the build-tests-red row written",
1991
2528
  log: "where the report was written (as given)",
1992
2529
  },
@@ -2034,7 +2571,7 @@ export const testsCommand: CommandSpec = {
2034
2571
  // retry, a handover or a task added to the group runs only what is left, and an edit
2035
2572
  // to another test of the same file costs no proof. A test whose lines could not be
2036
2573
  // found, and rows from before per-test locking, stand while the whole file is unchanged.
2037
- const proven = redEntries(status, workflow, group);
2574
+ const proven = lockBaselines(workflowRows(status, workflow), null);
2038
2575
  const textOf = (test: string) => {
2039
2576
  const abs = path.join(top, test);
2040
2577
  return fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
@@ -2053,17 +2590,41 @@ export const testsCommand: CommandSpec = {
2053
2590
  const shown = runGit(top, ["show", `${startSha}:${t.test}`]);
2054
2591
  return shown.ok ? blockHash(shown.stdout, t.testName) : null;
2055
2592
  };
2593
+ // A takeover whose earlier task has a baseline carries `from`; a passing one is judged
2594
+ // against the run start, not the group start.
2595
+ const takeovers = new Map(
2596
+ planTakeovers(planText).map((k) => [redKey(k.task, k.test, k.name), k]),
2597
+ );
2598
+ const baselines = [...proven.values()];
2599
+ const fromOf = (task: number, test: string, name: string) => {
2600
+ const k = takeovers.get(redKey(task, test, name));
2601
+ if (k === undefined) return undefined;
2602
+ const owned = baselines.some(
2603
+ (b) => b.task === k.from && b.test === k.test && sameTestName(b.testName, k.name),
2604
+ );
2605
+ return owned ? k.from : undefined;
2606
+ };
2607
+ const runStartRaw = activeRunStart(status, workflow)?.parentSha;
2608
+ const runStart = typeof runStartRaw === "string" ? runStartRaw : undefined;
2609
+ /** The test's lines at the run's start commit: it existed before this build. */
2610
+ const blockAtRunStart = (t: RedTest) => {
2611
+ if (runStart === undefined) return null;
2612
+ const shown = runGit(top, ["show", `${runStart}:${t.test}`]);
2613
+ return shown.ok ? blockHash(shown.stdout, t.testName) : null;
2614
+ };
2056
2615
  const tests: RedTest[] = [];
2057
2616
  let skipped = 0;
2058
2617
  for (const s of readTestFirst(planText, group)) {
2059
2618
  if (s.kind !== "test" || done.has(s.task)) continue;
2060
2619
  for (const t of s.tests) {
2620
+ const from = fromOf(s.task, t.test, t.name);
2061
2621
  const planned: RedTest = {
2062
2622
  task: s.task,
2063
2623
  test: t.test,
2064
2624
  testName: t.name,
2065
2625
  state: "unknown",
2066
2626
  blob: null,
2627
+ ...(from === undefined ? {} : { from }),
2067
2628
  };
2068
2629
  if (standing(planned)) skipped += 1;
2069
2630
  else tests.push(planned);
@@ -2139,6 +2700,26 @@ export const testsCommand: CommandSpec = {
2139
2700
  }
2140
2701
  for (const t of mine) {
2141
2702
  const judged = judgeRed(cases, t.testName, file);
2703
+ if (t.from !== undefined && judged.state === "vacuous") {
2704
+ const pre = blockAtRunStart(t);
2705
+ if (pre === null) {
2706
+ t.state = "taken-over";
2707
+ details.set(
2708
+ t,
2709
+ `taken over from TASK ${t.from} and passing after its rewrite: changed hands, not proven failing`,
2710
+ );
2711
+ continue;
2712
+ }
2713
+ if (pre !== t.block) {
2714
+ t.state = "updated";
2715
+ t.base = runStart;
2716
+ details.set(
2717
+ t,
2718
+ `taken over from TASK ${t.from}; it existed before the run (\`${runStart!.slice(0, 9)}\`) and passes: the verifier judges its diff — it may add expectations, never remove or loosen one`,
2719
+ );
2720
+ continue;
2721
+ }
2722
+ }
2142
2723
  const accepted =
2143
2724
  judged.state === "vacuous"
2144
2725
  ? passes.find(
@@ -2223,7 +2804,7 @@ export const testsCommand: CommandSpec = {
2223
2804
  },
2224
2805
  green: {
2225
2806
  summary:
2226
- "Audit a plan's test-first evidence (each TEST FIRST test red at its group's tests step, by the build-tests-red row, or accepted there as passing before any task code; the named test passing now); exit 0 no gaps, 1 gaps or a plan with no task markers.",
2807
+ "Audit a plan's test-first evidence (each TEST FIRST test red at its group's tests step, by the build-tests-red row, or accepted there as passing before any task code; the named test passing now); a taken-over test is listed under takenOver with its diff since the earlier task's red, never as a gap or unproven; exit 0 no gaps, 1 gaps or a plan with no task markers.",
2227
2808
  use: "workflow",
2228
2809
  flags: [
2229
2810
  FILE_FLAG,
@@ -2255,6 +2836,10 @@ export const testsCommand: CommandSpec = {
2255
2836
  "[{task, test, name, reason}]: tests the tests step accepted as passing before any task code (passed-accepted on the red row); no red is due for them",
2256
2837
  unproven:
2257
2838
  "[{task, test, name, detail}]: tests with no proven red (no build-tests-red row, or a state other than red, red-not-loaded, updated or passed-accepted) and no honoured TEST EXCEPTION; never a gap — the owner answers them once, at the end of the build",
2839
+ changed:
2840
+ "[{task, test, name, reason, diff, additive}]: plan-named tests (every group) a code step changed under a BLOCKED line naming them (the step's changedTests record), with the diff of the test's own lines since its baseline and whether it only adds lines; never a gap — the owner answers them once, at the end of the build",
2841
+ takenOver:
2842
+ "[{task, from, test, name, state, diff, additive}]: planned tests a later task took over (a red entry with from); diff / additive compare the test's own lines at the earlier owner's red with the file now (null when a side cannot be read); never a gap, never unproven",
2258
2843
  updated:
2259
2844
  "[{task, test, name, base, additive, diff}]: existing tests the tests step changed (updated on the red row); base is the group's start commit; additive = the test's own lines since base gained lines and lost none (null when a side cannot be read), diff = their unified line diff; the verifier judges each diff — it may add expectations, never remove or loosen one",
2260
2845
  log: "where the report was written (as given)",
@@ -2288,6 +2873,20 @@ export const testsCommand: CommandSpec = {
2288
2873
  (resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
2289
2874
  ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
2290
2875
  : undefined);
2876
+ const changed: Changed[] = [
2877
+ ...lockBaselines(workflowRows(statusFile(ctx), workflow), plannedKeys(planText)).values(),
2878
+ ]
2879
+ .filter((b) => b.fromChange && b.reasons.length > 0)
2880
+ .map((b) => ({
2881
+ task: b.task,
2882
+ test: b.test,
2883
+ name: b.testName,
2884
+ reason: b.reasons.join("; "),
2885
+ ...(() => {
2886
+ const d = baselineDiff(top, b.origin, b.test, b.testName);
2887
+ return { diff: d?.diff ?? null, additive: d?.additive ?? null };
2888
+ })(),
2889
+ }));
2291
2890
  const empty = {
2292
2891
  verdict: null,
2293
2892
  rows: [],
@@ -2296,6 +2895,8 @@ export const testsCommand: CommandSpec = {
2296
2895
  landed: [],
2297
2896
  unproven: [],
2298
2897
  updated: [],
2898
+ takenOver: [],
2899
+ changed,
2299
2900
  outputs: [],
2300
2901
  };
2301
2902
  if (reason !== undefined) {
@@ -2309,6 +2910,8 @@ export const testsCommand: CommandSpec = {
2309
2910
  alreadyLanded: [],
2310
2911
  unproven: [],
2311
2912
  updated: [],
2913
+ takenOver: [],
2914
+ changed,
2312
2915
  log: logArg,
2313
2916
  });
2314
2917
  ctx.log(`test-first not enforced: ${reason}`);
@@ -2320,6 +2923,7 @@ export const testsCommand: CommandSpec = {
2320
2923
  const landed: Landed[] = [];
2321
2924
  const unproven: Unproven[] = [];
2322
2925
  const updated: Updated[] = [];
2926
+ const takenOver: TakenOver[] = [];
2323
2927
  const statusRel = repoRel(top, ctx.cwd, statusFile(ctx));
2324
2928
  const exceptions: ExceptionResult[] = [];
2325
2929
  const gaps: Gap[] = [];
@@ -2425,6 +3029,7 @@ export const testsCommand: CommandSpec = {
2425
3029
  landed.push({ task: s.task, test: t.test, name: t.name, reason: red.reason ?? "" });
2426
3030
  } else if (RED_PROVEN.has(red.state)) {
2427
3031
  row.red = red.state;
3032
+ if (red.from !== undefined) takenOver.push(takenOverEntry(top, reds, red));
2428
3033
  if (red.state === "updated")
2429
3034
  updated.push(updatedEntry(top, s.task, t, red.base ?? null));
2430
3035
  } else {
@@ -2475,6 +3080,8 @@ export const testsCommand: CommandSpec = {
2475
3080
  landed,
2476
3081
  unproven,
2477
3082
  updated,
3083
+ takenOver,
3084
+ changed,
2478
3085
  outputs,
2479
3086
  });
2480
3087
  ctx.emit({
@@ -2485,6 +3092,8 @@ export const testsCommand: CommandSpec = {
2485
3092
  alreadyLanded: landed,
2486
3093
  unproven,
2487
3094
  updated,
3095
+ takenOver,
3096
+ changed,
2488
3097
  log: logArg,
2489
3098
  });
2490
3099
  ctx.log(
@@ -2494,7 +3103,7 @@ export const testsCommand: CommandSpec = {
2494
3103
  },
2495
3104
  },
2496
3105
  "plan-check": {
2497
- summary: `Check a plan's group and task blocks: the block format, DONE WHEN and TEST FIRST on every task, DEPENDS ON order, the caps from package.json \`bkit.workflows.tasks\` (defaults: ${capsText(CONFIG_DEFAULTS.tasks)}), a Reuse Inventory NEW row per CREATE file, a Supersession Inventory row per DELETE, a \`Task\` on every Derived Test Matrix row and a row per test-bearing task, and that each READ / UPDATE / DELETE file and symbol exists; exit 0 no problems, 1 refused.`,
3106
+ summary: `Check a plan's group and task blocks: the block format, DONE WHEN and TEST FIRST on every task, DEPENDS ON order, the caps from package.json \`bkit.workflows.tasks\` (defaults: ${capsText(CONFIG_DEFAULTS.tasks)}), a Reuse Inventory NEW row per CREATE file, a Supersession Inventory row per DELETE, a \`Task\` on every Derived Test Matrix row and a row per test-bearing task, and that each READ / UPDATE / DELETE file and symbol exists; lists each later task's TEST FIRST test an earlier task also names under takeovers, reported only; exit 0 no problems, 1 refused.`,
2498
3107
  use: "by-hand",
2499
3108
  flags: [
2500
3109
  {
@@ -2514,6 +3123,11 @@ export const testsCommand: CommandSpec = {
2514
3123
  required: true,
2515
3124
  help: "file the report is written to, `Problems:` header first (directories are created)",
2516
3125
  },
3126
+ {
3127
+ name: "ledger-rows",
3128
+ type: "boolean",
3129
+ help: "also refuse a plan whose `**Ledger rows:**` line is absent, unfilled or names a key with no docs/decisions.jsonl or docs/deferrals.jsonl row (the `ledgers check` test)",
3130
+ },
2517
3131
  ],
2518
3132
  output: {
2519
3133
  plan: "the plan file checked (as given)",
@@ -2521,11 +3135,13 @@ export const testsCommand: CommandSpec = {
2521
3135
  "[{group, title, tasks, tests, kb}]: each group's tasks, planned TEST FIRST tests and size",
2522
3136
  tasks: "[{task, group, tests, files}]: each task's planned tests and distinct test files",
2523
3137
  problems:
2524
- "[{line, kind, message}]: format | stray | field | depends | cap | inventory | matrix | supersession | markers — each refuses the plan",
3138
+ "[{line, kind, message}]: format | stray | field | depends | cap | inventory | matrix | supersession | markers | ledger (--ledger-rows only) — each refuses the plan",
2525
3139
  existence:
2526
3140
  "[{line, task, message}]: READ / UPDATE / DELETE files or symbols not found; refuses only with --existence=refuse",
2527
3141
  existing:
2528
- "[{line, task, test, name}]: planned tests of open tasks whose name a test in their file already carries; reported only, never refuses",
3142
+ "[{line, task, test, name}]: planned tests of open tasks whose name a test in their file already carries, takeovers left out; reported only, never refuses",
3143
+ takeovers:
3144
+ "[{task, from, test, name, line, sameGroup}]: planned tests a later task names that an earlier task (`from`, the nearest) also names; reported only, never refuses",
2529
3145
  log: "where the report was written (as given)",
2530
3146
  },
2531
3147
  run: (ctx) => {
@@ -2544,8 +3160,11 @@ export const testsCommand: CommandSpec = {
2544
3160
  const text = fs.readFileSync(planAbs, "utf-8");
2545
3161
  const caps = planCaps(ctx.cwd);
2546
3162
  const { groups, sizes, problems } = checkPlanText(text, caps);
3163
+ if (ctx.flags.ledgerRows === true)
3164
+ problems.push(...ledgerRowProblems(toplevel(ctx.cwd), text));
2547
3165
  const existence = planExistence(text, toplevel(ctx.cwd));
2548
3166
  const existing = existingTestNames(text, toplevel(ctx.cwd));
3167
+ const takeovers = planTakeovers(text);
2549
3168
  const refused = problems.length > 0 || (existenceArg === "refuse" && existence.length > 0);
2550
3169
 
2551
3170
  const out = [
@@ -2596,10 +3215,24 @@ export const testsCommand: CommandSpec = {
2596
3215
  out.push(
2597
3216
  `- \`${plan}:${e.line}\` TASK ${e.task}: \`${e.test}\` already holds a test named "${e.name}" — name the update to it in TEST FIRST, or give the new test a new name`,
2598
3217
  );
3218
+ if (takeovers.length > 0) out.push("", "## Tests that change hands (reported only)", "");
3219
+ for (const k of takeovers)
3220
+ out.push(
3221
+ `- \`${plan}:${k.line}\` TASK ${k.task} takes over "${k.name}" in \`${k.test}\` from TASK ${k.from}${k.sameGroup ? " (same group: one test, one baseline)" : " — the build records it failing again"}`,
3222
+ );
2599
3223
  const log = path.resolve(ctx.cwd, logArg);
2600
3224
  fs.mkdirSync(path.dirname(log), { recursive: true });
2601
3225
  fs.writeFileSync(log, `${out.join("\n")}\n`);
2602
- ctx.emit({ plan, groups, tasks: sizes, problems, existence, existing, log: logArg });
3226
+ ctx.emit({
3227
+ plan,
3228
+ groups,
3229
+ tasks: sizes,
3230
+ problems,
3231
+ existence,
3232
+ existing,
3233
+ takeovers,
3234
+ log: logArg,
3235
+ });
2603
3236
  ctx.log(
2604
3237
  `plan check: ${problems.length} problem(s), ${existence.length} existence finding(s)${refused ? " — refused" : ""}; report in ${logArg}`,
2605
3238
  );