@cbartens/bkit 6.1.0 → 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 (317) 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 +43 -33
  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 +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  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 +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -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 +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -20,19 +20,28 @@ import { createHash } from "node:crypto";
20
20
  import * as fs from "node:fs";
21
21
  import * as os from "node:os";
22
22
  import * as path from "node:path";
23
- import { BKIT_LINT_FILE_SCRIPT, BKIT_TEST_FILE_SCRIPT } from "../../install/manifest.js";
23
+ import { BKIT_GATE_CHANGED_SCRIPT, BKIT_LINT_FILE_SCRIPT, BKIT_TEST_FILE_SCRIPT, } from "../../install/manifest.js";
24
24
  import { clampLogPath } from "../../ledgers/clamp-log.js";
25
25
  import { appendLine, statusTimestamp, validateCiSelection, testRunProblem, } from "../../ledgers/status.js";
26
- import { classifyLockExit, CommandError, EXIT, git, runGit, testsLockHolder, wholeNumber, } from "../lib.js";
26
+ import { CommandError, EXIT, git, runGit, wholeNumber } from "../lib.js";
27
27
  import { parseJson } from "../../shared/json.js";
28
+ import { oneLine } from "../../shared/text.js";
28
29
  import { readPackageJson } from "../../shared/package-json.js";
29
- import { COULD_NOT_RUN_EXIT_CODES, scriptCommand, testCommand, } from "../../shared/package-manager.js";
30
+ import { COULD_NOT_RUN_EXIT_CODES, scriptCommand } from "../../shared/package-manager.js";
30
31
  import { CONFIG_DEFAULTS, readBkitConfig } from "../../shared/settings.js";
31
32
  import { FILE_FLAG, GROUP_FLAG, WORKFLOW_FLAG, positiveInt, readStatusRows, readRuns, statusFile, str, } from "./status.js";
32
33
  import { NO_MARKERS_REASON, derivedTestMatrix, fenceNeverClosed, parsePlanBlocks, reuseInventory, supersessionInventory, } from "./plan-blocks.js";
33
34
  import { writeStepRow } from "./steps.js";
35
+ import { activeRunStart } from "./counters.js";
36
+ import { REPORT_ENV, reportFailures, runGateUnderLock, runTestFile, runToLog, } from "./junit.js";
34
37
  import { appendRecord, clampFile } from "./context.js";
35
- import { testsChangedVerb } from "./tests-changed.js";
38
+ import { minPushPathspecs } from "../ci/ci.js";
39
+ import { requiredPushGate, runWithReceipt } from "../ci/push-gate.js";
40
+ import { testsBaseVerb } from "./tests-base.js";
41
+ import { changedBetween, changedFiles, commitExists, declares, snapshotTree, deletedFiles, importersOf, testsChangedVerb, } from "./tests-changed.js";
42
+ import { ORIGIN_DEV, featureBase } from "./feature-base.js";
43
+ import { testsJumpVerb } from "./tests-jump.js";
44
+ import { readPlanRows } from "./ledgers.js";
36
45
  /** Exit code: no candidate gate is declared in package.json. */
37
46
  export const EXIT_NO_GATE = 3;
38
47
  /** Exit code: the gate could not run (exit 126 / 127, or the package runner is missing). */
@@ -43,7 +52,6 @@ export const EXIT_ARTIFACT_STEP = 5;
43
52
  export const TEST_RUN_ROW = "test-run";
44
53
  /** The env var naming the folder every runner a gate calls writes its JUnit XML into. */
45
54
  export const REPORT_DIR_ENV = "BKIT_TEST_REPORT_DIR";
46
- export { classifyLockExit } from "../lib.js";
47
55
  const NO_REPORT_HINT = `no JUnit report in $${REPORT_DIR_ENV} — failures unknown; turn on each test runner's JUnit ` +
48
56
  `reporter in the gate and point its output into $${REPORT_DIR_ENV} ` +
49
57
  "(.bkit/workflows.md § Local gate scripts)";
@@ -65,30 +73,66 @@ export function resolveGate(dir, candidates) {
65
73
  return typeof body === "string" && body.trim() !== "";
66
74
  }) ?? null);
67
75
  }
68
- /** The scope string the status rows record: the package runner plus the script name. */
69
- export const gateScope = (gate) => scriptCommand(gate).join(" ");
76
+ /** The `--changed-since` word that names the feature's start commit. */
77
+ export const FEATURE_BASE_WORD = "feature-base";
70
78
  /**
71
- * Run argv with stdout and stderr interleaved into `log` (like `> log 2>&1`).
72
- * Exit 127 when the binary is missing; 128 + n when killed by signal n.
79
+ * `--changed-since` as a commit name: `feature-base` resolves through `featureBase`, which
80
+ * falls back to the name `origin/dev` when it cannot work out the feature's start commit.
73
81
  */
74
- export function runToLog(argv, cwd, log, env) {
75
- fs.mkdirSync(path.dirname(log), { recursive: true });
76
- const fd = fs.openSync(log, "w");
77
- const protectedArgv = testCommand(argv);
78
- const res = spawnSync(protectedArgv[0], protectedArgv.slice(1), {
79
- cwd,
80
- stdio: ["ignore", fd, fd],
81
- env: env === undefined ? process.env : { ...process.env, ...env },
82
- });
83
- fs.closeSync(fd);
84
- if (res.error) {
85
- fs.appendFileSync(log, `${argv[0]}: not found on PATH (${res.error.message})\n`);
86
- return 127;
82
+ function sinceBase(top, raw, log) {
83
+ if (raw !== FEATURE_BASE_WORD)
84
+ return raw;
85
+ const base = featureBase(top, log);
86
+ if (base === ORIGIN_DEV)
87
+ log(`feature base: no meeting point with ${ORIGIN_DEV} — measuring from ${ORIGIN_DEV}`);
88
+ else
89
+ log(`feature base: ${base}`);
90
+ return base;
91
+ }
92
+ /**
93
+ * The files `bkit:gate:changed` gets for a run measured from `base`: the changed files plus
94
+ * the files that still mention a deleted one, sorted, with the deleted files. Null when the
95
+ * search for those files fails: the caller runs the whole check, never a pass.
96
+ */
97
+ function changedScope(top, base, candidates, log, diff = {
98
+ files: changedFiles(top, base),
99
+ deleted: deletedFiles(top, base),
100
+ }) {
101
+ const { files: changed, deleted } = diff;
102
+ const importers = importersOf(top, base, deleted);
103
+ if (importers === null) {
104
+ log(`could not search ${base} for the files that mention the deleted ${deleted.join(" ")} — running the whole ${resolveGate(top, candidates) ?? "--gate"}`);
105
+ return null;
87
106
  }
88
- if (res.status !== null)
89
- return res.status;
90
- return 128 + ((res.signal ? os.constants.signals[res.signal] : undefined) ?? 1);
107
+ for (const [file, hits] of importers)
108
+ log(hits.length === 0
109
+ ? `deleted ${file}: no file mentions it`
110
+ : `deleted ${file}: checking the ${hits.length} file(s) that mention it`);
111
+ return { files: [...new Set([...changed, ...[...importers.values()].flat()])].sort(), deleted };
91
112
  }
113
+ /**
114
+ * The `tested` snapshot of the newest PASS test-run row of `steps` in `workflow` whose
115
+ * commit still exists, or null; each snapshot gone from the object store is logged.
116
+ */
117
+ function newestPass(top, file, workflow, steps, log) {
118
+ const passes = readStatusRows(file).filter((r) => r.type === TEST_RUN_ROW &&
119
+ r.workflow === workflow &&
120
+ typeof r.step === "string" &&
121
+ steps.includes(r.step) &&
122
+ r.verdict === "PASS" &&
123
+ typeof r.tested === "string");
124
+ for (const row of passes.reverse()) {
125
+ const sha = String(row.tested);
126
+ if (commitExists(top, sha)) {
127
+ log(`testing the files changed since run ${String(row.run)} of ${String(row.step)} passed (snapshot ${sha})`);
128
+ return sha;
129
+ }
130
+ log(`the snapshot ${sha} of run ${String(row.run)} of ${String(row.step)} is gone`);
131
+ }
132
+ return null;
133
+ }
134
+ /** The scope string the status rows record: the package runner plus the script name. */
135
+ export const gateScope = (gate) => scriptCommand(gate).join(" ");
92
136
  /** `{log}.reports`, emptied: a previous attempt's reports never count toward this one. */
93
137
  function freshReportDir(log) {
94
138
  const dir = `${log}.reports`;
@@ -96,20 +140,30 @@ function freshReportDir(log) {
96
140
  fs.mkdirSync(dir, { recursive: true });
97
141
  return dir;
98
142
  }
99
- /** Failing plus erroring test cases across every `*.xml` under `dir`; null when there is none. */
100
- export function countReportFailures(dir) {
101
- const xml = fs.readdirSync(dir, { recursive: true }).filter((f) => f.endsWith(".xml") && fs.statSync(path.join(dir, f)).isFile());
102
- if (xml.length === 0)
103
- return null;
104
- return xml
105
- .flatMap((f) => parseJunit(fs.readFileSync(path.join(dir, f), "utf-8")))
106
- .filter((c) => c.state === "failure" || c.state === "error").length;
107
- }
108
143
  const tailLines = (file, n) => fs
109
144
  .readFileSync(file, "utf-8")
110
145
  .replace(/\r?\n$/, "")
111
146
  .split(/\r?\n/)
112
147
  .slice(-n);
148
+ /** The most failing-test names one `test-run` row keeps. */
149
+ export const FAILED_TESTS_CAP = 100;
150
+ /** A failing JUnit case as a `failedTests` name: `{file ?? classname} > {name}`, or the name alone. */
151
+ export const caseLabel = (c) => {
152
+ const where = c.file ?? c.classname;
153
+ return where === null || where === "" ? c.name : `${where} > ${c.name}`;
154
+ };
155
+ /**
156
+ * The `failedTests` row fields for `names`: unique, sorted, at most `FAILED_TESTS_CAP`, with
157
+ * `failedTestsTruncated` when cut; none when `names` is empty.
158
+ */
159
+ export function failedTestsField(names) {
160
+ const unique = [...new Set(names.filter((n) => n !== ""))].sort();
161
+ if (unique.length === 0)
162
+ return {};
163
+ return unique.length > FAILED_TESTS_CAP
164
+ ? { failedTests: unique.slice(0, FAILED_TESTS_CAP), failedTestsTruncated: true }
165
+ : { failedTests: unique };
166
+ }
113
167
  /**
114
168
  * Append one `test-run` row to `file`. `run` numbers this step's test-run rows in the
115
169
  * workflow's active run (since its last workflow-started row), this one included, so a
@@ -140,6 +194,9 @@ function appendTestRun(file, r) {
140
194
  log: r.log,
141
195
  ...(r.artifact === undefined ? {} : { artifact: r.artifact }),
142
196
  ...(r.source === undefined ? {} : { source: r.source }),
197
+ ...(typeof r.tested === "string" ? { tested: r.tested } : {}),
198
+ ...(r.failedTests === undefined ? {} : { failedTests: r.failedTests }),
199
+ ...(r.failedTestsTruncated === undefined ? {} : { failedTestsTruncated: true }),
143
200
  ...r.evidence,
144
201
  };
145
202
  const problem = testRunProblem(row);
@@ -151,20 +208,23 @@ function appendTestRun(file, r) {
151
208
  // ---------------------------------------------------------------------------
152
209
  // Test-first: JUnit reading, plan `Test first:` lines, red / green judgement
153
210
  // ---------------------------------------------------------------------------
154
- /** The env var naming the JUnit report path `bkit:test:file` must write. */
155
- export const REPORT_ENV = "BKIT_TEST_REPORT";
156
211
  /** The status row step a group's red writes: one row per `tests red` run, a state and blob per planned test. */
157
212
  export const RED_STEP = "build-tests-red";
213
+ /** The status row step `steps finish` writes for a contradicted planned test: one row per takeover task it adds. */
214
+ export const TAKEOVER_STEP = "build-takeover";
158
215
  /**
159
216
  * The states that count as a red: the test failed, its file did not load, the tests step
160
- * vouched for its pass, or it is an existing test updated and passing, whose diff the
161
- * verifier judges (it may add expectations, never remove or loosen one).
217
+ * vouched for its pass, it is an existing test updated and passing, whose diff the
218
+ * verifier judges (it may add expectations, never remove or loosen one), or it is a test
219
+ * taken over from an earlier task, written in this build and passing after its rewrite
220
+ * (reported as changed hands, not proven failing).
162
221
  */
163
222
  export const RED_PROVEN = new Set([
164
223
  "red",
165
224
  "red-not-loaded",
166
225
  "passed-accepted",
167
226
  "updated",
227
+ "taken-over",
168
228
  ]);
169
229
  /** The `build-tests-red` rows of `workflow` in status.jsonl, in file order; `group` narrows. */
170
230
  function redRows(file, workflow, group) {
@@ -215,13 +275,131 @@ export function redEntries(file, workflow, group) {
215
275
  return out;
216
276
  }
217
277
  /**
218
- * The planned tests of `group` a code step changed since their red: a test whose own lines
219
- * (`testBlock`) no longer hash to the recorded block. A row with no block (written before
220
- * per-test locking, or when no line carried the name) derives the block from the recorded
221
- * blob; when that holds no block either, the whole file's blob is compared. Other edits to a
222
- * test file are free.
278
+ * The plan beside a run's status file: `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` →
279
+ * `docs/plans/{YYYYMM}/{FID}-plan.md`.
280
+ */
281
+ export function runPlanPath(statusFile) {
282
+ const logs = path.dirname(statusFile);
283
+ return path.join(path.dirname(path.dirname(logs)), `${path.basename(logs)}-plan.md`);
284
+ }
285
+ /**
286
+ * The lock's baseline per planned test, from the status rows in order: every `build-tests-red`
287
+ * entry (a proven red is never replaced by an unproven result for the same lines) and every
288
+ * `changedTests` record of a code step; the latest per key wins. `planned` (the plan-named key
289
+ * set) limits the keys; null keeps them all.
290
+ */
291
+ export function lockBaselines(rows, planned) {
292
+ const out = new Map();
293
+ /** The newest blob any red recorded per test file (a later tests step's additions included). */
294
+ const newestBlob = new Map();
295
+ for (const row of rows) {
296
+ if (row.type !== "step-done")
297
+ continue;
298
+ if (row.step === RED_STEP && typeof row.group === "number") {
299
+ for (const t of redTestsOf(row)) {
300
+ if (t.blob !== null)
301
+ newestBlob.set(t.test, t.blob);
302
+ const key = redKey(t.task, t.test, t.testName);
303
+ if (planned !== null && !planned.has(key))
304
+ continue;
305
+ const earlier = out.get(key);
306
+ const keepsProof = earlier !== undefined &&
307
+ RED_PROVEN.has(earlier.state) &&
308
+ !RED_PROVEN.has(t.state) &&
309
+ typeof earlier.block === "string" &&
310
+ earlier.block === t.block;
311
+ if (!keepsProof)
312
+ out.set(key, {
313
+ ...t,
314
+ reasons: earlier?.reasons ?? [],
315
+ fromChange: false,
316
+ text: t.blob,
317
+ origin: t.blob,
318
+ });
319
+ // A takeover's entry, whatever its state, is the new baseline of every earlier key
320
+ // naming the same test: the earlier task's lock moves onto the taken-over lines.
321
+ if (t.from === undefined)
322
+ continue;
323
+ for (const [k, b] of out)
324
+ if (k !== key && b.test === t.test && sameTestName(b.testName, t.testName))
325
+ out.set(k, {
326
+ ...b,
327
+ state: t.state,
328
+ blob: t.blob,
329
+ block: t.block,
330
+ fromChange: false,
331
+ text: t.blob,
332
+ origin: t.blob,
333
+ });
334
+ }
335
+ }
336
+ if (CODE_STEPS.has(String(row.step)) && Array.isArray(row.changedTests)) {
337
+ for (const c of row.changedTests) {
338
+ if (typeof c.task !== "number" || typeof c.test !== "string")
339
+ continue;
340
+ if (typeof c.testName !== "string")
341
+ continue;
342
+ if (typeof c.reason !== "string" || c.reason === "")
343
+ continue;
344
+ const key = redKey(c.task, c.test, c.testName);
345
+ if (planned !== null && !planned.has(key))
346
+ continue;
347
+ const earlier = out.get(key);
348
+ out.set(key, {
349
+ task: c.task,
350
+ test: c.test,
351
+ testName: c.testName,
352
+ state: "red",
353
+ blob: null,
354
+ block: typeof c.block === "string" ? c.block : null,
355
+ fromChange: true,
356
+ text: typeof c.after === "string" ? c.after : null,
357
+ origin: earlier?.origin ?? (typeof c.blob === "string" ? c.blob : null),
358
+ reasons: [
359
+ ...(earlier?.reasons ?? []),
360
+ ...(typeof c.reason === "string" ? [c.reason] : []),
361
+ ],
362
+ });
363
+ }
364
+ }
365
+ }
366
+ // A test no line names (block null) is locked by its whole file, against the file's newest red blob.
367
+ for (const b of out.values()) {
368
+ const blob = newestBlob.get(b.test);
369
+ if (b.fromChange || b.block !== null || blob === undefined || b.blob === null)
370
+ continue;
371
+ b.blob = blob;
372
+ b.text = blob;
373
+ b.origin = blob;
374
+ }
375
+ return out;
376
+ }
377
+ /** The code steps whose `changedTests` records move the lock's baseline. */
378
+ const CODE_STEPS = new Set([
379
+ "build-plan-tasks",
380
+ "build-plan-gaps-remediate",
381
+ "build-plan-gaps-remediate-holistic",
382
+ ]);
383
+ /** The status rows of one workflow. */
384
+ export const workflowRows = (file, workflow) => fs.existsSync(file)
385
+ ? readStatusRows(file).filter((r) => r.workflow === workflow)
386
+ : [];
387
+ /** The key set of the tests a plan's `TEST FIRST` lines name (done tasks included), or null with no plan. */
388
+ function plannedKeys(plan) {
389
+ return plan === undefined
390
+ ? null
391
+ : new Set(readTestFirst(plan).flatMap((s) => s.kind === "test" ? s.tests.map((t) => redKey(s.task, t.test, t.name)) : []));
392
+ }
393
+ /**
394
+ * The planned tests (every group) a code step changed since their baseline (`lockBaselines`): a
395
+ * test whose own lines (`testBlock`) no longer hash to the recorded block. A record with no
396
+ * block (written before per-test locking, or when no line carried the name) derives the block
397
+ * from the recorded blob; when that holds no block either, the whole file's blob is compared.
398
+ * Other edits to a test file are free. With `plan` (the plan's text), only tests a `TEST FIRST`
399
+ * line still names are checked: a name the plan dropped locks nothing. Each result carries the
400
+ * test's task, its current block and the reasons already recorded, for `finish`.
223
401
  */
224
- export function touchedTests(top, file, workflow, group) {
402
+ export function touchedTests(top, file, workflow, plan) {
225
403
  const touched = [];
226
404
  const texts = new Map();
227
405
  const textOf = (test) => {
@@ -231,20 +409,51 @@ export function touchedTests(top, file, workflow, group) {
231
409
  }
232
410
  return texts.get(test);
233
411
  };
234
- for (const t of redEntries(file, workflow, group).values()) {
412
+ for (const t of lockBaselines(workflowRows(file, workflow), plannedKeys(plan)).values()) {
413
+ const now = blockHash(textOf(t.test), t.testName);
414
+ const hit = (wholeFile) => touched.push({
415
+ test: t.test,
416
+ name: t.testName,
417
+ task: t.task,
418
+ block: now,
419
+ reasons: t.reasons,
420
+ text: t.text,
421
+ origin: t.origin,
422
+ fromChange: t.fromChange,
423
+ wholeFile,
424
+ });
235
425
  let block = t.block ?? null;
236
426
  if (block === null)
237
427
  block = blockHash(blobText(top, t.blob), t.testName);
238
428
  if (block === null) {
429
+ if (t.blob === null && t.fromChange) {
430
+ if (now !== null && t.reasons.length > 0)
431
+ hit(true);
432
+ continue;
433
+ }
239
434
  if (git(top, ["hash-object", "--", t.test]) !== t.blob)
240
- touched.push({ test: t.test, name: t.testName });
435
+ hit(true);
241
436
  continue;
242
437
  }
243
- if (blockHash(textOf(t.test), t.testName) !== block)
244
- touched.push({ test: t.test, name: t.testName });
438
+ if (now !== block)
439
+ hit(false);
245
440
  }
246
441
  return touched;
247
442
  }
443
+ /**
444
+ * The line diff of the test's own lines from the baseline text `blob` to the file now, and
445
+ * whether it only adds lines; null when either side cannot be read.
446
+ */
447
+ export function baselineDiff(top, blob, test, name) {
448
+ // A null blob is a red that recorded the file `missing`: every line of the test is added.
449
+ const was = blob === null ? "" : testBlock(blobText(top, blob), name);
450
+ const abs = path.join(top, test);
451
+ const now = fs.existsSync(abs) ? testBlock(fs.readFileSync(abs, "utf-8"), name) : null;
452
+ if (was === null || now === null)
453
+ return null;
454
+ const d = lineDiff(was, now);
455
+ return { additive: d.removed === 0, diff: d.text };
456
+ }
248
457
  /** The text a recorded blob holds, untrimmed; null when the object store lacks it. */
249
458
  function blobText(top, blob) {
250
459
  if (blob === null)
@@ -342,7 +551,7 @@ export function testSpan(text, name) {
342
551
  * which only a read of the added lines tells.
343
552
  */
344
553
  export function lineDiff(before, after) {
345
- const a = before.split("\n");
554
+ const a = before === "" ? [] : before.split("\n");
346
555
  const b = after.split("\n");
347
556
  const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
348
557
  for (let i = a.length - 1; i >= 0; i--)
@@ -393,45 +602,6 @@ function groupStartSha(file, workflow, group) {
393
602
  const NO_TEST_FILE_HINT = `declare "${BKIT_TEST_FILE_SCRIPT}" in package.json: it runs the one test file passed as its ` +
394
603
  `argument and writes a JUnit report to $${REPORT_ENV} ` +
395
604
  "(.bkit/workflows.md § Local gate scripts)";
396
- const XML_ENTITIES = {
397
- amp: "&",
398
- lt: "<",
399
- gt: ">",
400
- quot: '"',
401
- apos: "'",
402
- };
403
- function decodeXml(s) {
404
- return s.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, e) => {
405
- if (!e.startsWith("#"))
406
- return XML_ENTITIES[e.toLowerCase()] ?? whole;
407
- const cp = /^#x/i.test(e) ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
408
- return cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : whole;
409
- });
410
- }
411
- const ATTRS = String.raw `((?:\s+[\w:.-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)`;
412
- function attr(attrs, name) {
413
- const m = new RegExp(String.raw `\s${name}\s*=\s*(?:"([^"]*)"|'([^']*)')`).exec(attrs);
414
- return m ? decodeXml(m[1] ?? m[2] ?? "") : undefined;
415
- }
416
- /** CDATA text as escaped character data, so a tag inside it never ends an element early. */
417
- const escapeCdata = (xml) => xml.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"));
418
- /** Every `<testcase>` in a JUnit report: its name, outcome, first failure message and detail. */
419
- export function parseJunit(xml) {
420
- const body = escapeCdata(xml).replace(/<!--[\s\S]*?-->/g, "");
421
- const cases = [];
422
- const testcase = new RegExp(String.raw `<testcase${ATTRS}\s*(?:\/>|>([\s\S]*?)<\/testcase>)`, "g");
423
- const outcome = new RegExp(String.raw `<(failure|error|skipped)${ATTRS}\s*(?:\/>|>([\s\S]*?)<\/\1>)`);
424
- for (const m of body.matchAll(testcase)) {
425
- const child = outcome.exec(m[2] ?? "");
426
- cases.push({
427
- name: attr(m[1] ?? "", "name") ?? "",
428
- state: child ? child[1] : "passed",
429
- message: child ? (attr(child[2] ?? "", "message") ?? "") : "",
430
- detail: child ? decodeXml((child[3] ?? "").replace(/<[^>]*>/g, "")).trim() : "",
431
- });
432
- }
433
- return cases;
434
- }
435
605
  /** A report case is the named test when its name is the name, or ends with it as the last segment. */
436
606
  export const isNamedCase = (caseName, want) => caseName === want || caseName.endsWith(` ${want}`);
437
607
  const caseNames = (cases) => cases.length === 0
@@ -492,16 +662,77 @@ export const TEST_FIRST = "**TEST FIRST:**";
492
662
  export const TEST_EXCEPTION = "**TEST EXCEPTION:**";
493
663
  /** The plan caps `package.json` `bkit.workflows.tasks` sets for the checkout `cwd` sits in. */
494
664
  export const planCaps = (cwd) => readBkitConfig(toplevel(cwd)).tasks;
665
+ /** `ledgers check` on the plan text as plan-check problems: the line absent or unfilled, or each key with no row. */
666
+ function ledgerRowProblems(root, text) {
667
+ const r = readPlanRows(root, text);
668
+ if (r.unreadable !== undefined)
669
+ return [
670
+ {
671
+ line: r.line,
672
+ kind: "ledger",
673
+ message: `${r.unreadable} — list each decision / deferral row key written for this plan, or write None`,
674
+ },
675
+ ];
676
+ if (r.missing.length === 0)
677
+ return [];
678
+ return [
679
+ {
680
+ line: r.line,
681
+ kind: "ledger",
682
+ 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`,
683
+ },
684
+ ];
685
+ }
495
686
  /** The caps as the plan-check report and help state them. */
496
687
  export const capsText = (c) => `${c.maxPerGroup} tasks and ${c.maxTestsPerGroup} TEST FIRST tests per group; ${c.maxTestsPerTask} tests across ${c.maxTestFilesPerTask} test files per task`;
497
- /** A task block's TEST FIRST read as one `TestFirst`; a TEST EXCEPTION with no TEST FIRST is its `n/a`. */
688
+ /** The test a JUnit-style suite path (`suite > test`) names: its last segment. */
689
+ const lastSegment = (name) => name.split(" > ").pop().trim();
690
+ /**
691
+ * Two planned test names name one test: equal, or, when one of them has no ` > ` (a bare
692
+ * test name against a suite path), equal in their last segment. Two suite paths must match
693
+ * whole: `a > works` and `b > works` are two tests.
694
+ */
695
+ export const sameTestName = (a, b) => a === b || ((!a.includes(" > ") || !b.includes(" > ")) && lastSegment(a) === lastSegment(b));
696
+ /**
697
+ * Every planned test a later task names that an earlier task (plan order, done tasks
698
+ * included) also names in the same file: the later task takes the test over. `from` is
699
+ * the nearest earlier task naming it. Paths compare posix-normalized; names compare per
700
+ * `sameTestName`.
701
+ */
702
+ export function planTakeovers(text) {
703
+ const seen = [];
704
+ const out = [];
705
+ for (const t of parsePlanBlocks(text).tasks) {
706
+ const mine = t.testFirst?.tests ?? [];
707
+ for (const x of mine) {
708
+ const test = path.posix.normalize(x.test);
709
+ const owner = [...seen]
710
+ .reverse()
711
+ .find((s) => s.test === test && sameTestName(s.name, x.name));
712
+ if (owner !== undefined)
713
+ out.push({
714
+ task: t.task,
715
+ from: owner.task,
716
+ test,
717
+ name: x.name,
718
+ line: x.line,
719
+ sameGroup: owner.group === t.group,
720
+ });
721
+ }
722
+ for (const x of mine)
723
+ seen.push({ task: t.task, group: t.group, test: path.posix.normalize(x.test), name: x.name });
724
+ }
725
+ return out;
726
+ }
498
727
  /**
499
728
  * Planned tests of open tasks whose name a test in their file already carries: the tests
500
729
  * step cannot write a new test under that name, so it either updates the existing one or
501
- * finds it passing. Reported only — the plan names the update, or a new name.
730
+ * finds it passing. Reported only — the plan names the update, or a new name. A test the
731
+ * task takes over from an earlier task (`planTakeovers`) is left out.
502
732
  */
503
733
  function existingTestNames(text, top) {
504
734
  const out = [];
735
+ const takenOver = new Set(planTakeovers(text).map((k) => redKey(k.task, k.test, k.name)));
505
736
  for (const t of parsePlanBlocks(text).tasks) {
506
737
  if (t.done)
507
738
  continue;
@@ -509,6 +740,8 @@ function existingTestNames(text, top) {
509
740
  if (s.kind !== "test")
510
741
  continue;
511
742
  for (const x of s.tests) {
743
+ if (takenOver.has(redKey(t.task, x.test, x.name)))
744
+ continue;
512
745
  const abs = path.join(top, x.test);
513
746
  if (!fs.existsSync(abs))
514
747
  continue;
@@ -518,6 +751,7 @@ function existingTestNames(text, top) {
518
751
  }
519
752
  return out;
520
753
  }
754
+ /** A task block's TEST FIRST read as one `TestFirst`; a TEST EXCEPTION with no TEST FIRST is its `n/a`. */
521
755
  function testFirstOf(t) {
522
756
  const { task, testFirst: tf, testException: exc } = t;
523
757
  const plain = (tests) => tests.map(({ test, name }) => ({ test, name }));
@@ -641,17 +875,32 @@ export function checkPlanText(text, caps = CONFIG_DEFAULTS.tasks) {
641
875
  // matrix section yields no problem: the refusal is on a row, and issue-form plans carry none.
642
876
  const matrix = derivedTestMatrix(text);
643
877
  if (matrix !== null) {
644
- if (matrix.taskColumn === null)
878
+ const expected = "Test description | Type | Target file | Task";
879
+ const header = (matrix.head[0] ?? "")
880
+ .split("|")
881
+ .slice(1, -1)
882
+ .map((c) => c.trim().toLowerCase())
883
+ .join(" | ");
884
+ if (header !== expected.toLowerCase())
645
885
  problems.push({
646
886
  line: matrix.line,
647
887
  kind: "matrix",
648
- message: "the Derived Test Matrix header has no `Task` column; add one naming the task each row's test belongs to",
888
+ message: `the Derived Test Matrix header must be exactly \`${expected}\`, in that order with no other columns`,
649
889
  });
650
- else {
890
+ if (matrix.taskColumn !== null) {
651
891
  const mapped = new Set();
652
892
  for (const row of matrix.rows) {
653
893
  const named = row.tasks.map((n) => `TASK ${n}`);
654
- if (row.tasks.length === 0)
894
+ const taskCell = (row.cells[matrix.taskColumn] ?? "").trim();
895
+ if (row.cells.length !== 4 ||
896
+ (taskCell !== "" &&
897
+ !/^(?:task\s*)?\d+(?:\s*(?:,|and)\s*(?:task\s*)?\d+)*$/i.test(taskCell)))
898
+ problems.push({
899
+ line: row.number,
900
+ kind: "matrix",
901
+ 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`,
902
+ });
903
+ else if (row.tasks.length === 0)
655
904
  problems.push({
656
905
  line: row.number,
657
906
  kind: "matrix",
@@ -847,17 +1096,6 @@ export function planExistence(text, root) {
847
1096
  }
848
1097
  return out.sort((a, b) => a.line - b.line);
849
1098
  }
850
- /** Run one test file through `bkit:test:file`; the report is read and removed. */
851
- function runTestFile(top, test, log) {
852
- const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bkit-test-report-"));
853
- const report = path.join(dir, "junit.xml");
854
- const exitCode = runToLog([...scriptCommand(BKIT_TEST_FILE_SCRIPT), test], top, log, {
855
- [REPORT_ENV]: report,
856
- });
857
- const cases = fs.existsSync(report) ? parseJunit(fs.readFileSync(report, "utf-8")) : null;
858
- fs.rmSync(dir, { recursive: true, force: true });
859
- return { exitCode, cases };
860
- }
861
1099
  const couldNotRunMessage = (exitCode) => `${gateScope(BKIT_TEST_FILE_SCRIPT)} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no test executed`;
862
1100
  const toplevel = (cwd) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
863
1101
  /** A fence longer than any backtick run in `text`. */
@@ -1066,6 +1304,31 @@ function updatedEntry(top, task, t, base) {
1066
1304
  const d = lineDiff(was, now);
1067
1305
  return { ...entry, additive: d.removed === 0, diff: d.text };
1068
1306
  }
1307
+ /** The `TakenOver` entry for a red entry carrying `from`: its lines at the owner's red against now. */
1308
+ function takenOverEntry(top, reds, red) {
1309
+ const owner = [...reds.values()].find((r) => r.task === red.from && r.test === red.test && sameTestName(r.testName, red.testName));
1310
+ const d = owner === undefined ? null : baselineDiff(top, owner.blob, red.test, red.testName);
1311
+ return {
1312
+ task: red.task,
1313
+ from: red.from,
1314
+ test: red.test,
1315
+ name: red.testName,
1316
+ state: red.state,
1317
+ additive: d?.additive ?? null,
1318
+ diff: d?.diff ?? null,
1319
+ };
1320
+ }
1321
+ /** Every BLOCKED line of a code step's log that names a planned test, with its reason. */
1322
+ export function blockedTests(log) {
1323
+ return [
1324
+ ...log.matchAll(/^BLOCKED\s*[—–-]+\s*(TASK|Gap)\s+(\d+):\s*test\s+`([^`]+)`\s+`([^`]+)`\s*[—–-]+\s*(.+)$/gm),
1325
+ ].map((m) => ({
1326
+ test: m[3].trim(),
1327
+ name: m[4].trim(),
1328
+ reason: m[5].trim(),
1329
+ task: m[1] === "TASK" ? Number(m[2]) : null,
1330
+ }));
1331
+ }
1069
1332
  /** Every PASSES line of a tests step's log: the tests the writer saw passing and vouches for. */
1070
1333
  function passesLines(log) {
1071
1334
  return [
@@ -1150,7 +1413,7 @@ function writeAuditReport(log, o) {
1150
1413
  if (o.gaps.length === 0)
1151
1414
  out.push("None.");
1152
1415
  for (const g of o.gaps)
1153
- out.push(`- ${g.task === null ? "Plan" : `Task ${g.task}`} \`${g.kind}\` — ${g.detail} — Fixable: ${g.fixable} — log: ${g.logLine}`);
1416
+ out.push(`- ${g.task === null ? "Plan" : `Task ${g.task}`} \`${g.kind}\` — ${oneLine(g.detail)} — Fixable: ${g.fixable} — log: ${g.logLine}`);
1154
1417
  if (o.exceptions.length > 0)
1155
1418
  out.push("", "## Test exceptions", "");
1156
1419
  for (const e of o.exceptions)
@@ -1176,10 +1439,31 @@ function writeAuditReport(log, o) {
1176
1439
  out.push("", ` ${fence}diff`, ...u.diff.split("\n").map((l) => ` ${l}`), ` ${fence}`, "");
1177
1440
  }
1178
1441
  }
1442
+ if (o.takenOver.length > 0)
1443
+ out.push("", "## Taken over", "");
1444
+ for (const t of o.takenOver) {
1445
+ const judged = t.state === "taken-over"
1446
+ ? "changed hands and passes after the rewrite: not proven failing, and never a gap"
1447
+ : `recorded \`${t.state}\` after the rewrite`;
1448
+ out.push(`- Task ${t.task} \`${t.test}\` "${t.name}" — taken over from Task ${t.from}; ${judged}`);
1449
+ if (t.diff !== null) {
1450
+ const fence = fenceFor(t.diff);
1451
+ out.push("", ` ${fence}diff`, ...t.diff.split("\n").map((l) => ` ${l}`), ` ${fence}`, "");
1452
+ }
1453
+ }
1179
1454
  if (o.unproven.length > 0)
1180
1455
  out.push("", "## Unproven", "");
1181
1456
  for (const u of o.unproven)
1182
1457
  out.push(`- Task ${u.task} \`${u.test}\` "${u.name}" — ${u.detail}; the owner answers it at the end of the build`);
1458
+ if (o.changed.length > 0)
1459
+ out.push("", "## Changed by a code step", "");
1460
+ for (const c of o.changed) {
1461
+ out.push(`- 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`);
1462
+ if (c.diff !== null) {
1463
+ const fence = fenceFor(c.diff);
1464
+ out.push("", ` ${fence}diff`, ...c.diff.split("\n").map((l) => ` ${l}`), ` ${fence}`, "");
1465
+ }
1466
+ }
1183
1467
  for (const t of o.outputs) {
1184
1468
  const fence = fenceFor(t.tail);
1185
1469
  out.push("", `## Runner output — \`${t.test}\``, "", fence, t.tail, fence);
@@ -1191,9 +1475,11 @@ export const testsCommand = {
1191
1475
  noun: "tests",
1192
1476
  summary: "Run the deepest declared local gate, or one test file to record a red and audit a green.",
1193
1477
  verbs: {
1478
+ base: testsBaseVerb,
1194
1479
  changed: testsChangedVerb,
1480
+ jump: testsJumpVerb,
1195
1481
  run: {
1196
- summary: "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.",
1482
+ summary: "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).",
1197
1483
  use: "by-hand",
1198
1484
  flags: [
1199
1485
  {
@@ -1241,6 +1527,16 @@ export const testsCommand = {
1241
1527
  help: "status.jsonl: append one test-run row for this run, pass or fail; needs --workflow and --step",
1242
1528
  },
1243
1529
  { name: "workflow", type: "string", help: "--file: workflow name, for the test-run row" },
1530
+ {
1531
+ name: "changed-since",
1532
+ type: "string",
1533
+ 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`,
1534
+ },
1535
+ {
1536
+ name: "since-pass-of",
1537
+ type: "string",
1538
+ 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`,
1539
+ },
1244
1540
  { name: "ci-run", type: "string", help: "selected GitHub evidence run ID" },
1245
1541
  { name: "ci-url", type: "string", help: "selected GitHub evidence attempt URL" },
1246
1542
  ],
@@ -1258,13 +1554,13 @@ export const testsCommand = {
1258
1554
  exitCode: "the gate's exit code",
1259
1555
  gate: "the script that ran",
1260
1556
  scope: "the command that ran, as status rows record it",
1261
- 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)`,
1557
+ 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`,
1262
1558
  reports: `{log}.reports — emptied before the run and passed to the gate as $${REPORT_DIR_ENV}`,
1263
1559
  log: "where the full output was saved (as given); the untouched original",
1264
1560
  logBytes: "size of the saved output",
1265
1561
  artifact: "--artifact as given, else null",
1266
1562
  clamp: "the artifact's clamp record (raw = the log, source = scope), else null",
1267
- 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`,
1563
+ 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`,
1268
1564
  lockHolder: "tests-lock holder when the wait gave up, else null",
1269
1565
  },
1270
1566
  textOmit: ["clamp", "row"],
@@ -1357,18 +1653,19 @@ export const testsCommand = {
1357
1653
  source: "ci",
1358
1654
  verdict: "FAIL",
1359
1655
  exitCode: null,
1360
- failures: null,
1656
+ failures: selection.failedJobCount ?? null,
1361
1657
  scope,
1362
1658
  log: logArg,
1363
1659
  artifact,
1364
1660
  evidence,
1661
+ ...failedTestsField((selection.failedJobs ?? []).map((job) => `job:${job}`)),
1365
1662
  });
1366
1663
  ctx.emit({
1367
1664
  source: "ci",
1368
1665
  verdict: "FAIL",
1369
1666
  scope,
1370
1667
  exitCode: null,
1371
- failures: null,
1668
+ failures: selection.failedJobCount ?? null,
1372
1669
  ...evidence,
1373
1670
  artifact,
1374
1671
  log: logArg,
@@ -1387,7 +1684,48 @@ export const testsCommand = {
1387
1684
  // Gates are declared and run at the top of the checkout being tested (the
1388
1685
  // feature worktree), wherever in it the caller happens to stand.
1389
1686
  const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1390
- const gate = resolveGate(top, candidates);
1687
+ const passSteps = str(ctx.flags.sincePassOf)
1688
+ ?.split(",")
1689
+ .map((s) => s.trim())
1690
+ .filter(Boolean);
1691
+ if (passSteps !== undefined &&
1692
+ (status === undefined || ctx.flags.changedSince === undefined || passSteps.length === 0))
1693
+ throw new CommandError(EXIT.USAGE, "--since-pass-of needs one or more steps, --file, --workflow and --changed-since");
1694
+ const sinceRaw = sinceBase(top, str(ctx.flags.changedSince), ctx.log);
1695
+ if (sinceRaw !== undefined &&
1696
+ git(top, ["rev-parse", "-q", "--verify", `${sinceRaw}^{commit}`]) === null)
1697
+ throw new CommandError(EXIT.USAGE, `--changed-since ${sinceRaw} names no commit`);
1698
+ // The tree this run tests, taken before the gate starts.
1699
+ const tested = status === undefined ? null : snapshotTree(top);
1700
+ if (status !== undefined && tested === null)
1701
+ ctx.log("could not snapshot the working tree — the test-run row records no tested");
1702
+ // With --since-pass-of: the files that differ from the newest passing run's snapshot.
1703
+ const passDiff = () => {
1704
+ if (passSteps === undefined)
1705
+ return null;
1706
+ const pass = newestPass(top, status, workflow, passSteps, ctx.log);
1707
+ if (pass === null) {
1708
+ ctx.log(`no passing run of ${passSteps.join(", ")} to measure from — testing from --changed-since ${sinceRaw}`);
1709
+ return null;
1710
+ }
1711
+ const diff = changedBetween(top, pass, tested);
1712
+ if (diff === null) {
1713
+ ctx.log(`could not list the files changed since the passing run at ${pass} — testing from --changed-since ${sinceRaw}`);
1714
+ return null;
1715
+ }
1716
+ return { base: pass, ...diff };
1717
+ };
1718
+ let scoped = null;
1719
+ if (sinceRaw !== undefined && declares(top, BKIT_GATE_CHANGED_SCRIPT)) {
1720
+ const fromPass = passDiff();
1721
+ scoped =
1722
+ fromPass === null
1723
+ ? changedScope(top, sinceRaw, candidates, ctx.log)
1724
+ : changedScope(top, fromPass.base, candidates, ctx.log, fromPass);
1725
+ }
1726
+ const useChanged = scoped !== null;
1727
+ const changed = scoped?.files ?? [];
1728
+ const gate = useChanged ? BKIT_GATE_CHANGED_SCRIPT : resolveGate(top, candidates);
1391
1729
  if (gate === null) {
1392
1730
  const read = readPackageJson(top);
1393
1731
  if (!read.ok)
@@ -1395,21 +1733,70 @@ export const testsCommand = {
1395
1733
  ctx.log(`no bkit:gate:* script declared (looked for ${candidates.join(", ")}) — ${NO_GATE_HINT}`);
1396
1734
  return EXIT_NO_GATE;
1397
1735
  }
1398
- const scope = gateScope(gate);
1736
+ const scope = useChanged
1737
+ ? `${gateScope(gate)} (${changed.length} changed file${changed.length === 1 ? "" : "s"})`
1738
+ : gateScope(gate);
1399
1739
  const log = path.resolve(ctx.cwd, logArg);
1740
+ if (scoped !== null && changed.length === 0) {
1741
+ ctx.log(scoped.deleted.length === 0
1742
+ ? `no files changed since ${sinceRaw} — nothing to run`
1743
+ : `only deleted files that no file mentions changed since ${sinceRaw} — nothing to run`);
1744
+ const row = status === undefined
1745
+ ? null
1746
+ : appendTestRun(status, {
1747
+ workflow: workflow,
1748
+ step: step,
1749
+ attempt,
1750
+ verdict: "PASS",
1751
+ exitCode: 0,
1752
+ failures: 0,
1753
+ scope,
1754
+ log: logArg,
1755
+ artifact: undefined,
1756
+ source: "local",
1757
+ tested,
1758
+ });
1759
+ ctx.emit({
1760
+ source: "local",
1761
+ verdict: "PASS",
1762
+ exitCode: 0,
1763
+ gate,
1764
+ scope,
1765
+ failures: 0,
1766
+ reports: null,
1767
+ log: logArg,
1768
+ logBytes: 0,
1769
+ artifact: null,
1770
+ clamp: null,
1771
+ row,
1772
+ lockHolder: null,
1773
+ });
1774
+ return EXIT.OK;
1775
+ }
1400
1776
  const reports = freshReportDir(log);
1401
1777
  ctx.log(`running ${scope} — full output in ${logArg}`);
1402
1778
  const fetchedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
1403
1779
  const who = ["bkit tests run", gate, fid, step].filter(Boolean).join(" ");
1404
- const exitCode = runToLog(scriptCommand(gate), top, log, {
1405
- [REPORT_DIR_ENV]: reports,
1406
- LOCAL_STACK_LOCK_WAIT_S: String(waitS),
1407
- LOCAL_STACK_LOCK_WHO: who,
1408
- });
1780
+ // The gate's run under the tests lock, kept for the receipt's lock-wait check.
1781
+ const lock = {};
1782
+ const runGate = () => {
1783
+ lock.run = runGateUnderLock(useChanged ? [...scriptCommand(gate), ...changed] : scriptCommand(gate), top, log, {
1784
+ [REPORT_DIR_ENV]: reports,
1785
+ LOCAL_STACK_LOCK_WAIT_S: String(waitS),
1786
+ LOCAL_STACK_LOCK_WHO: who,
1787
+ });
1788
+ return lock.run.exitCode;
1789
+ };
1790
+ // The required full gate leaves a push receipt, so the branch's first push
1791
+ // reuses it; bookkeeping paths may be uncommitted, as every engine call writes one.
1792
+ const exitCode = sinceRaw === undefined && gate === requiredPushGate(top)
1793
+ ? runWithReceipt(top, gate, minPushPathspecs(readBkitConfig(top)), runGate, ctx.log, () => lock.run?.lock === "lock-wait")
1794
+ : runGate();
1409
1795
  const logText = fs.readFileSync(log, "utf-8");
1410
- const lockExit = classifyLockExit({ exitCode, log: logText, who });
1796
+ // runWithReceipt always runs the gate, so lock.run is set here.
1797
+ const lockExit = lock.run?.lock ?? "gate";
1411
1798
  const lockWait = lockExit === "lock-wait";
1412
- const lockHolder = lockWait ? testsLockHolder(logText, who) : null;
1799
+ const lockHolder = lockWait ? (lock.run?.status?.holder ?? null) : null;
1413
1800
  const lines = lockExit === "gate"
1414
1801
  ? Number(tailRaw) > 0
1415
1802
  ? tailLines(log, Number(tailRaw))
@@ -1419,7 +1806,8 @@ export const testsCommand = {
1419
1806
  ctx.log(line);
1420
1807
  const couldNotRun = lockExit === "could-not-run" || COULD_NOT_RUN_EXIT_CODES.has(exitCode);
1421
1808
  const verdict = couldNotRun || lockWait ? null : exitCode === 0 ? "PASS" : "FAIL";
1422
- const counted = lockExit === "gate" ? countReportFailures(reports) : null;
1809
+ const failing = lockExit === "gate" ? reportFailures(reports) : null;
1810
+ const counted = failing?.length ?? null;
1423
1811
  if (counted === null && lockExit === "gate")
1424
1812
  ctx.log(NO_REPORT_HINT);
1425
1813
  else if (verdict === "FAIL" && counted === 0)
@@ -1462,6 +1850,8 @@ export const testsCommand = {
1462
1850
  log: logArg,
1463
1851
  artifact,
1464
1852
  source: "local",
1853
+ tested,
1854
+ ...failedTestsField(verdict === "FAIL" ? (failing ?? []).map(caseLabel) : []),
1465
1855
  });
1466
1856
  ctx.emit({
1467
1857
  source: "local",
@@ -1485,7 +1875,9 @@ export const testsCommand = {
1485
1875
  if (lockWait)
1486
1876
  return EXIT.AGENT_WAIT;
1487
1877
  if (couldNotRun) {
1488
- ctx.log(`${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`);
1878
+ ctx.log(lock.run?.status?.outcome === "held-too-long"
1879
+ ? `${scope} could not finish (exit ${exitCode}: stopped at the tests-lock hold limit) — its tests have no result; this is not a FAIL verdict`
1880
+ : `${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`);
1489
1881
  return EXIT_COULD_NOT_RUN;
1490
1882
  }
1491
1883
  ctx.log(`verdict ${verdict} (exit ${exitCode})`);
@@ -1493,7 +1885,7 @@ export const testsCommand = {
1493
1885
  },
1494
1886
  },
1495
1887
  red: {
1496
- summary: "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.",
1888
+ summary: "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.",
1497
1889
  use: "workflow",
1498
1890
  flags: [
1499
1891
  FILE_FLAG,
@@ -1526,9 +1918,9 @@ export const testsCommand = {
1526
1918
  enforced: "false when bkit:test:file is not declared (the row records the blobs, every state unknown, exit 3) or the plan could not be read (no row, exit 1)",
1527
1919
  reason: "why test-first is not enforced",
1528
1920
  attempt: "this group's build-tests-red rows so far, this one included",
1529
- tests: "[{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",
1921
+ tests: "[{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)",
1530
1922
  skipped: "planned tests an earlier row of the group proved red, their file unchanged since: not run again, and not on this row",
1531
- gaps: "[{task, test, name, kind, detail}]: every planned test whose state is not red, red-not-loaded or passed-accepted; kind is the state",
1923
+ 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",
1532
1924
  row: "the build-tests-red row written",
1533
1925
  log: "where the report was written (as given)",
1534
1926
  },
@@ -1577,7 +1969,7 @@ export const testsCommand = {
1577
1969
  // retry, a handover or a task added to the group runs only what is left, and an edit
1578
1970
  // to another test of the same file costs no proof. A test whose lines could not be
1579
1971
  // found, and rows from before per-test locking, stand while the whole file is unchanged.
1580
- const proven = redEntries(status, workflow, group);
1972
+ const proven = lockBaselines(workflowRows(status, workflow), null);
1581
1973
  const textOf = (test) => {
1582
1974
  const abs = path.join(top, test);
1583
1975
  return fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
@@ -1598,18 +1990,40 @@ export const testsCommand = {
1598
1990
  const shown = runGit(top, ["show", `${startSha}:${t.test}`]);
1599
1991
  return shown.ok ? blockHash(shown.stdout, t.testName) : null;
1600
1992
  };
1993
+ // A takeover whose earlier task has a baseline carries `from`; a passing one is judged
1994
+ // against the run start, not the group start.
1995
+ const takeovers = new Map(planTakeovers(planText).map((k) => [redKey(k.task, k.test, k.name), k]));
1996
+ const baselines = [...proven.values()];
1997
+ const fromOf = (task, test, name) => {
1998
+ const k = takeovers.get(redKey(task, test, name));
1999
+ if (k === undefined)
2000
+ return undefined;
2001
+ const owned = baselines.some((b) => b.task === k.from && b.test === k.test && sameTestName(b.testName, k.name));
2002
+ return owned ? k.from : undefined;
2003
+ };
2004
+ const runStartRaw = activeRunStart(status, workflow)?.parentSha;
2005
+ const runStart = typeof runStartRaw === "string" ? runStartRaw : undefined;
2006
+ /** The test's lines at the run's start commit: it existed before this build. */
2007
+ const blockAtRunStart = (t) => {
2008
+ if (runStart === undefined)
2009
+ return null;
2010
+ const shown = runGit(top, ["show", `${runStart}:${t.test}`]);
2011
+ return shown.ok ? blockHash(shown.stdout, t.testName) : null;
2012
+ };
1601
2013
  const tests = [];
1602
2014
  let skipped = 0;
1603
2015
  for (const s of readTestFirst(planText, group)) {
1604
2016
  if (s.kind !== "test" || done.has(s.task))
1605
2017
  continue;
1606
2018
  for (const t of s.tests) {
2019
+ const from = fromOf(s.task, t.test, t.name);
1607
2020
  const planned = {
1608
2021
  task: s.task,
1609
2022
  test: t.test,
1610
2023
  testName: t.name,
1611
2024
  state: "unknown",
1612
2025
  blob: null,
2026
+ ...(from === undefined ? {} : { from }),
1613
2027
  };
1614
2028
  if (standing(planned))
1615
2029
  skipped += 1;
@@ -1681,6 +2095,20 @@ export const testsCommand = {
1681
2095
  }
1682
2096
  for (const t of mine) {
1683
2097
  const judged = judgeRed(cases, t.testName, file);
2098
+ if (t.from !== undefined && judged.state === "vacuous") {
2099
+ const pre = blockAtRunStart(t);
2100
+ if (pre === null) {
2101
+ t.state = "taken-over";
2102
+ details.set(t, `taken over from TASK ${t.from} and passing after its rewrite: changed hands, not proven failing`);
2103
+ continue;
2104
+ }
2105
+ if (pre !== t.block) {
2106
+ t.state = "updated";
2107
+ t.base = runStart;
2108
+ details.set(t, `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`);
2109
+ continue;
2110
+ }
2111
+ }
1684
2112
  const accepted = judged.state === "vacuous"
1685
2113
  ? passes.find((p) => p.task === t.task && p.test === t.test && p.name === t.testName)
1686
2114
  : undefined;
@@ -1756,7 +2184,7 @@ export const testsCommand = {
1756
2184
  },
1757
2185
  },
1758
2186
  green: {
1759
- summary: "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.",
2187
+ summary: "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.",
1760
2188
  use: "workflow",
1761
2189
  flags: [
1762
2190
  FILE_FLAG,
@@ -1784,6 +2212,8 @@ export const testsCommand = {
1784
2212
  gaps: "[{task, kind, detail, fixable, logLine}]: no-test-first | test-first-malformed | test-first-unread (task null: a plan-level format problem) | not-green | exception-refused (a task whose only test field is a TEST EXCEPTION not honoured) | delete-still-referenced (a DELETE line's file still exists, or its name is still found in the tree); fixable is null when the gap needs a diff read; logLine is the line the verifier appends",
1785
2213
  alreadyLanded: "[{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",
1786
2214
  unproven: "[{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",
2215
+ changed: "[{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",
2216
+ takenOver: "[{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",
1787
2217
  updated: "[{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",
1788
2218
  log: "where the report was written (as given)",
1789
2219
  },
@@ -1817,6 +2247,20 @@ export const testsCommand = {
1817
2247
  (resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
1818
2248
  ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
1819
2249
  : undefined);
2250
+ const changed = [
2251
+ ...lockBaselines(workflowRows(statusFile(ctx), workflow), plannedKeys(planText)).values(),
2252
+ ]
2253
+ .filter((b) => b.fromChange && b.reasons.length > 0)
2254
+ .map((b) => ({
2255
+ task: b.task,
2256
+ test: b.test,
2257
+ name: b.testName,
2258
+ reason: b.reasons.join("; "),
2259
+ ...(() => {
2260
+ const d = baselineDiff(top, b.origin, b.test, b.testName);
2261
+ return { diff: d?.diff ?? null, additive: d?.additive ?? null };
2262
+ })(),
2263
+ }));
1820
2264
  const empty = {
1821
2265
  verdict: null,
1822
2266
  rows: [],
@@ -1825,6 +2269,8 @@ export const testsCommand = {
1825
2269
  landed: [],
1826
2270
  unproven: [],
1827
2271
  updated: [],
2272
+ takenOver: [],
2273
+ changed,
1828
2274
  outputs: [],
1829
2275
  };
1830
2276
  if (reason !== undefined) {
@@ -1838,6 +2284,8 @@ export const testsCommand = {
1838
2284
  alreadyLanded: [],
1839
2285
  unproven: [],
1840
2286
  updated: [],
2287
+ takenOver: [],
2288
+ changed,
1841
2289
  log: logArg,
1842
2290
  });
1843
2291
  ctx.log(`test-first not enforced: ${reason}`);
@@ -1848,6 +2296,7 @@ export const testsCommand = {
1848
2296
  const landed = [];
1849
2297
  const unproven = [];
1850
2298
  const updated = [];
2299
+ const takenOver = [];
1851
2300
  const statusRel = repoRel(top, ctx.cwd, statusFile(ctx));
1852
2301
  const exceptions = [];
1853
2302
  const gaps = [];
@@ -1931,6 +2380,8 @@ export const testsCommand = {
1931
2380
  }
1932
2381
  else if (RED_PROVEN.has(red.state)) {
1933
2382
  row.red = red.state;
2383
+ if (red.from !== undefined)
2384
+ takenOver.push(takenOverEntry(top, reds, red));
1934
2385
  if (red.state === "updated")
1935
2386
  updated.push(updatedEntry(top, s.task, t, red.base ?? null));
1936
2387
  }
@@ -1969,6 +2420,8 @@ export const testsCommand = {
1969
2420
  landed,
1970
2421
  unproven,
1971
2422
  updated,
2423
+ takenOver,
2424
+ changed,
1972
2425
  outputs,
1973
2426
  });
1974
2427
  ctx.emit({
@@ -1979,6 +2432,8 @@ export const testsCommand = {
1979
2432
  alreadyLanded: landed,
1980
2433
  unproven,
1981
2434
  updated,
2435
+ takenOver,
2436
+ changed,
1982
2437
  log: logArg,
1983
2438
  });
1984
2439
  ctx.log(`test-first audit: ${gaps.length} gap(s), ${unproven.length} unproven — report in ${logArg}`);
@@ -1986,7 +2441,7 @@ export const testsCommand = {
1986
2441
  },
1987
2442
  },
1988
2443
  "plan-check": {
1989
- 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.`,
2444
+ 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.`,
1990
2445
  use: "by-hand",
1991
2446
  flags: [
1992
2447
  {
@@ -2006,14 +2461,20 @@ export const testsCommand = {
2006
2461
  required: true,
2007
2462
  help: "file the report is written to, `Problems:` header first (directories are created)",
2008
2463
  },
2464
+ {
2465
+ name: "ledger-rows",
2466
+ type: "boolean",
2467
+ 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)",
2468
+ },
2009
2469
  ],
2010
2470
  output: {
2011
2471
  plan: "the plan file checked (as given)",
2012
2472
  groups: "[{group, title, tasks, tests, kb}]: each group's tasks, planned TEST FIRST tests and size",
2013
2473
  tasks: "[{task, group, tests, files}]: each task's planned tests and distinct test files",
2014
- problems: "[{line, kind, message}]: format | stray | field | depends | cap | inventory | matrix | supersession | markers — each refuses the plan",
2474
+ problems: "[{line, kind, message}]: format | stray | field | depends | cap | inventory | matrix | supersession | markers | ledger (--ledger-rows only) — each refuses the plan",
2015
2475
  existence: "[{line, task, message}]: READ / UPDATE / DELETE files or symbols not found; refuses only with --existence=refuse",
2016
- existing: "[{line, task, test, name}]: planned tests of open tasks whose name a test in their file already carries; reported only, never refuses",
2476
+ existing: "[{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",
2477
+ takeovers: "[{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",
2017
2478
  log: "where the report was written (as given)",
2018
2479
  },
2019
2480
  run: (ctx) => {
@@ -2030,8 +2491,11 @@ export const testsCommand = {
2030
2491
  const text = fs.readFileSync(planAbs, "utf-8");
2031
2492
  const caps = planCaps(ctx.cwd);
2032
2493
  const { groups, sizes, problems } = checkPlanText(text, caps);
2494
+ if (ctx.flags.ledgerRows === true)
2495
+ problems.push(...ledgerRowProblems(toplevel(ctx.cwd), text));
2033
2496
  const existence = planExistence(text, toplevel(ctx.cwd));
2034
2497
  const existing = existingTestNames(text, toplevel(ctx.cwd));
2498
+ const takeovers = planTakeovers(text);
2035
2499
  const refused = problems.length > 0 || (existenceArg === "refuse" && existence.length > 0);
2036
2500
  const out = [
2037
2501
  `Problems: ${problems.length}`,
@@ -2072,10 +2536,23 @@ export const testsCommand = {
2072
2536
  out.push("", "## Planned test names already in use (reported only)", "");
2073
2537
  for (const e of existing)
2074
2538
  out.push(`- \`${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`);
2539
+ if (takeovers.length > 0)
2540
+ out.push("", "## Tests that change hands (reported only)", "");
2541
+ for (const k of takeovers)
2542
+ out.push(`- \`${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"}`);
2075
2543
  const log = path.resolve(ctx.cwd, logArg);
2076
2544
  fs.mkdirSync(path.dirname(log), { recursive: true });
2077
2545
  fs.writeFileSync(log, `${out.join("\n")}\n`);
2078
- ctx.emit({ plan, groups, tasks: sizes, problems, existence, existing, log: logArg });
2546
+ ctx.emit({
2547
+ plan,
2548
+ groups,
2549
+ tasks: sizes,
2550
+ problems,
2551
+ existence,
2552
+ existing,
2553
+ takeovers,
2554
+ log: logArg,
2555
+ });
2079
2556
  ctx.log(`plan check: ${problems.length} problem(s), ${existence.length} existence finding(s)${refused ? " — refused" : ""}; report in ${logArg}`);
2080
2557
  return refused ? EXIT.NO : EXIT.OK;
2081
2558
  },