@cbartens/bkit 5.5.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -6,6 +6,8 @@
6
6
  // order is the contract). Nothing declared is its own exit code, never an empty
7
7
  // command that exits 0 and reads as a clean run. A gate that exits 126 / 127 never
8
8
  // ran (not executable / not found), so it is not recorded as a failing test.
9
+ // The failure count comes from the JUnit reports the gate's runners write into
10
+ // `{log}.reports/` (`BKIT_TEST_REPORT_DIR`), never from reading the log.
9
11
  //
10
12
  // bkit tests red / green — test-first evidence for build tasks. Both run one test
11
13
  // file through the consumer's `bkit:test:file` script and judge its JUnit report,
@@ -19,24 +21,44 @@ import * as os from "node:os";
19
21
  import * as path from "node:path";
20
22
 
21
23
  import { BKIT_TEST_FILE_SCRIPT } from "../../install/manifest.js";
22
- import { CommandError, EXIT, git, type CommandSpec } from "../lib.js";
24
+ import { clampLogPath } from "../../ledgers/clamp-log.js";
25
+ import { CommandError, EXIT, git, runGit, type CommandSpec } from "../lib.js";
26
+ import { parseJson } from "../../shared/json.js";
23
27
  import { readPackageJson } from "../../shared/package-json.js";
24
28
  import { COULD_NOT_RUN_EXIT_CODES, scriptCommand } from "../../shared/package-manager.js";
29
+ import { CONFIG_DEFAULTS, readBkitConfig, type TaskCaps } from "../../shared/settings.js";
25
30
  import {
26
31
  FILE_FLAG,
27
- SUB_PLAN_FLAG,
32
+ GROUP_FLAG,
28
33
  WORKFLOW_FLAG,
29
34
  positiveInt,
30
35
  readStatusRows,
31
36
  statusFile,
32
37
  str,
33
38
  } from "./status.js";
39
+ import {
40
+ fenceNeverClosed,
41
+ parsePlanBlocks,
42
+ reuseInventory,
43
+ type PlanTaskBlock,
44
+ } from "./plan-blocks.js";
34
45
  import { writeStepRow } from "./steps.js";
46
+ import { appendRecord, clampFile, type ClampRecord } from "./context.js";
35
47
 
36
48
  /** Exit code: no candidate gate is declared in package.json. */
37
49
  export const EXIT_NO_GATE = 3;
38
50
  /** Exit code: the gate could not run (exit 126 / 127, or the package runner is missing). */
39
51
  export const EXIT_COULD_NOT_RUN = 4;
52
+ /** Exit code: --artifact could not be written, trimmed or recorded. */
53
+ export const EXIT_ARTIFACT_STEP = 5;
54
+
55
+ /** The env var naming the folder every runner a gate calls writes its JUnit XML into. */
56
+ export const REPORT_DIR_ENV = "BKIT_TEST_REPORT_DIR";
57
+
58
+ const NO_REPORT_HINT =
59
+ `no JUnit report in $${REPORT_DIR_ENV} — failures unknown; turn on each test runner's JUnit ` +
60
+ `reporter in the gate and point its output into $${REPORT_DIR_ENV} ` +
61
+ "(.bkit/workflows.md § Local gate scripts)";
40
62
 
41
63
  const DEFAULT_TAIL = 40;
42
64
 
@@ -90,8 +112,31 @@ export function runToLog(
90
112
  return 128 + ((res.signal ? os.constants.signals[res.signal] : undefined) ?? 1);
91
113
  }
92
114
 
115
+ /** `{log}.reports`, emptied: a previous attempt's reports never count toward this one. */
116
+ function freshReportDir(log: string): string {
117
+ const dir = `${log}.reports`;
118
+ fs.rmSync(dir, { recursive: true, force: true });
119
+ fs.mkdirSync(dir, { recursive: true });
120
+ return dir;
121
+ }
122
+
123
+ /** Failing plus erroring test cases across every `*.xml` under `dir`; null when there is none. */
124
+ export function countReportFailures(dir: string): number | null {
125
+ const xml = (fs.readdirSync(dir, { recursive: true }) as string[]).filter(
126
+ (f) => f.endsWith(".xml") && fs.statSync(path.join(dir, f)).isFile(),
127
+ );
128
+ if (xml.length === 0) return null;
129
+ return xml
130
+ .flatMap((f) => parseJunit(fs.readFileSync(path.join(dir, f), "utf-8")))
131
+ .filter((c) => c.state === "failure" || c.state === "error").length;
132
+ }
133
+
93
134
  const tailLines = (file: string, n: number) =>
94
- fs.readFileSync(file, "utf-8").replace(/\n$/, "").split("\n").slice(-n);
135
+ fs
136
+ .readFileSync(file, "utf-8")
137
+ .replace(/\r?\n$/, "")
138
+ .split(/\r?\n/)
139
+ .slice(-n);
95
140
 
96
141
  // ---------------------------------------------------------------------------
97
142
  // Test-first: JUnit reading, plan `Test first:` lines, red / green judgement
@@ -215,68 +260,374 @@ export interface PlannedTest {
215
260
  name: string;
216
261
  }
217
262
 
263
+ /** A human-recorded acceptance of a task's test-order gaps: the tests it covers, its 1-based plan lines. */
264
+ export interface TestOrderException {
265
+ tests: PlannedTest[];
266
+ lines: number[];
267
+ }
268
+
218
269
  export type TestFirst =
219
- | { task: number; kind: "test"; tests: PlannedTest[] }
270
+ | { task: number; kind: "test"; tests: PlannedTest[]; exception?: TestOrderException }
220
271
  | { task: number; kind: "na"; reason: string }
221
272
  | { task: number; kind: "missing" | "malformed" };
222
273
 
223
- const TASK_LINE = /^\s*- \[[ xX]\] \*\*Task (\d+):\*\*/;
224
- const TEST_FIRST = "**Test first:**";
225
-
226
- /** `text` split on `;` outside backticks. */
227
- function splitEntries(text: string): string[] {
228
- const out: string[] = [];
229
- let cur = "";
230
- let quoted = false;
231
- for (const ch of text) {
232
- if (ch === "`") quoted = !quoted;
233
- if (ch === ";" && !quoted) {
234
- out.push(cur);
235
- cur = "";
236
- } else cur += ch;
274
+ /** The task field naming a task's tests, and the one recording an accepted test-order gap. */
275
+ export const TEST_FIRST = "**TEST FIRST:**";
276
+ export const TEST_EXCEPTION = "**TEST EXCEPTION:**";
277
+ /** Why `tests green` refuses a plan with no group and task blocks. */
278
+ export const NO_MARKERS_REASON =
279
+ "this plan has no task markers; run /bkit-build again to convert it";
280
+
281
+ /** The plan caps `package.json` `bkit.workflows.tasks` sets for the checkout `cwd` sits in. */
282
+ export const planCaps = (cwd: string): TaskCaps => readBkitConfig(toplevel(cwd)).tasks;
283
+
284
+ /** The caps as the plan-check report and help state them. */
285
+ export const capsText = (c: TaskCaps) =>
286
+ `${c.maxPerGroup} tasks and ${c.maxTestsPerGroup} TEST FIRST tests per group; ${c.maxTestsPerTask} tests across ${c.maxTestFilesPerTask} test files per task`;
287
+
288
+ /** A task block's TEST FIRST read as one `TestFirst`; a TEST EXCEPTION with no TEST FIRST is its `n/a`. */
289
+ function testFirstOf(t: PlanTaskBlock): TestFirst {
290
+ const { task, testFirst: tf, testException: exc } = t;
291
+ const plain = (tests: PlannedTest[]) => tests.map(({ test, name }) => ({ test, name }));
292
+ if (tf === undefined)
293
+ return exc === undefined ? { task, kind: "missing" } : { task, kind: "na", reason: exc.text };
294
+ if (tf.malformed.length > 0 || (tf.tests.length === 0 && tf.na === undefined))
295
+ return { task, kind: "malformed" };
296
+ if (tf.tests.length === 0) return { task, kind: "na", reason: tf.na! };
297
+ const tests = plain(tf.tests);
298
+ return exc === undefined || exc.tests.length === 0
299
+ ? { task, kind: "test", tests }
300
+ : { task, kind: "test", tests, exception: { tests: plain(exc.tests), lines: exc.lines } };
301
+ }
302
+
303
+ /**
304
+ * Each task block's TEST FIRST field (`plan-blocks.ts`): one test per sub-bullet (first
305
+ * backticked span = file, second = test name), `n/a — {reason}`, missing, or malformed
306
+ * (an entry with fewer than two spans, or no entry). A TEST EXCEPTION field names, in
307
+ * the same entry form, the tests whose test-order gaps it accepts. `group` narrows to
308
+ * one group's tasks.
309
+ */
310
+ export function readTestFirst(plan: string, group?: number): TestFirst[] {
311
+ return parsePlanBlocks(plan)
312
+ .tasks.filter((t) => group === undefined || t.group === group)
313
+ .map(testFirstOf);
314
+ }
315
+
316
+ export interface TaskSize {
317
+ task: number;
318
+ group: number;
319
+ tests: number;
320
+ files: number;
321
+ }
322
+
323
+ /** Per task, the planned tests and distinct test files it names (`n/a`, missing and malformed count 0). */
324
+ export const taskSizes = (specs: TestFirst[]): Array<Omit<TaskSize, "group">> =>
325
+ specs.map((s) =>
326
+ s.kind === "test"
327
+ ? { task: s.task, tests: s.tests.length, files: new Set(s.tests.map((t) => t.test)).size }
328
+ : { task: s.task, tests: 0, files: 0 },
329
+ );
330
+
331
+ export interface GroupSize {
332
+ group: number;
333
+ title: string;
334
+ tasks: number;
335
+ /** Planned TEST FIRST tests, summed over the group's tasks. */
336
+ tests: number;
337
+ /** The group block's size, KB to one decimal. */
338
+ kb: number;
339
+ }
340
+
341
+ export interface PlanProblem {
342
+ /** 1-based plan line. */
343
+ line: number;
344
+ kind: "format" | "stray" | "field" | "depends" | "cap" | "inventory" | "markers";
345
+ message: string;
346
+ }
347
+
348
+ export interface PlanCheck {
349
+ groups: GroupSize[];
350
+ sizes: TaskSize[];
351
+ /** Tasks naming more than `maxTestsPerTask` tests or `maxTestFilesPerTask` test files. */
352
+ overCap: TaskSize[];
353
+ /** Every reason the plan is refused, in line order; the existence check is `planExistence`. */
354
+ problems: PlanProblem[];
355
+ }
356
+
357
+ /**
358
+ * Files with a NEW row in the plan's Reuse Inventory table (`reuseInventory`): the
359
+ * paths in the `File` cell of each row whose `Decision` cell reads NEW.
360
+ */
361
+ export function inventoryNewFiles(text: string): Set<string> {
362
+ const rows = reuseInventory(text)?.rows ?? [];
363
+ return new Set(rows.filter((r) => /^\**new\b/i.test(r.decision)).flatMap((r) => r.files));
364
+ }
365
+
366
+ const kb1 = (bytes: number) => Math.round((bytes / 1024) * 10) / 10;
367
+
368
+ /**
369
+ * One plan's groups and tasks against the caps and the block format: parse errors and
370
+ * task-like text outside every block, a task without DONE WHEN or without TEST FIRST and
371
+ * TEST EXCEPTION, a malformed TEST FIRST, a DEPENDS ON naming a missing task or one in a
372
+ * later group, a group or task over a cap in `caps`, a CREATE file with no NEW Reuse
373
+ * Inventory row.
374
+ */
375
+ export function checkPlanText(text: string, caps: TaskCaps = CONFIG_DEFAULTS.tasks): PlanCheck {
376
+ const blocks = parsePlanBlocks(text);
377
+ const lines = text.split(/\r?\n/);
378
+ const problems: PlanProblem[] = blocks.errors.map((e) => ({
379
+ line: e.line,
380
+ kind: e.kind,
381
+ message: e.message,
382
+ }));
383
+ if (blocks.tasks.length === 0 && blocks.fenceOpen === undefined)
384
+ problems.push({
385
+ line: 1,
386
+ kind: "markers",
387
+ message:
388
+ "no task markers: write each task as a `<!-- bkit:task N start -->` block inside a `<!-- bkit:group N start -->` block",
389
+ });
390
+ const specs = new Map(blocks.tasks.map((t) => [t.task, testFirstOf(t)]));
391
+ const sizes: TaskSize[] = blocks.tasks.map((t) => {
392
+ const s = specs.get(t.task)!;
393
+ const tests = s.kind === "test" ? s.tests : [];
394
+ return {
395
+ task: t.task,
396
+ group: t.group,
397
+ tests: tests.length,
398
+ files: new Set(tests.map((x) => x.test)).size,
399
+ };
400
+ });
401
+ const overCap = sizes.filter(
402
+ (t) => t.tests > caps.maxTestsPerTask || t.files > caps.maxTestFilesPerTask,
403
+ );
404
+ const byTask = new Map(blocks.tasks.map((t) => [t.task, t]));
405
+ const newFiles = inventoryNewFiles(text);
406
+ for (const t of blocks.tasks) {
407
+ const field = (message: string, line = t.line) =>
408
+ problems.push({ line, kind: "field", message: `TASK ${t.task}: ${message}` });
409
+ if (t.doneWhen === undefined || t.doneWhen === "") field("has no **DONE WHEN:** field");
410
+ const s = specs.get(t.task)!;
411
+ if (s.kind === "missing") field("has neither **TEST FIRST:** nor **TEST EXCEPTION:**");
412
+ for (const line of t.testFirst?.malformed ?? [])
413
+ field("TEST FIRST entry is neither `test file` `test name` nor `n/a — {reason}`", line);
414
+ if (s.kind === "malformed" && (t.testFirst?.malformed.length ?? 0) === 0)
415
+ field("TEST FIRST names no test", t.testFirst!.line);
416
+ for (const d of t.dependsOn) {
417
+ const dep = byTask.get(d);
418
+ const message =
419
+ d === t.task
420
+ ? `TASK ${t.task} depends on itself`
421
+ : dep === undefined
422
+ ? `TASK ${t.task} depends on TASK ${d}, but TASK ${d} does not exist`
423
+ : dep.group > t.group
424
+ ? `TASK ${t.task} depends on TASK ${d}, which is in a later group (GROUP ${dep.group}); groups build in order`
425
+ : undefined;
426
+ if (message !== undefined) problems.push({ line: t.line, kind: "depends", message });
427
+ }
428
+ const size = sizes.find((x) => x.task === t.task)!;
429
+ if (size.tests > caps.maxTestsPerTask)
430
+ problems.push({
431
+ line: t.line,
432
+ kind: "cap",
433
+ message: `TASK ${t.task} names ${size.tests} TEST FIRST tests, over the cap of ${caps.maxTestsPerTask}`,
434
+ });
435
+ if (size.files > caps.maxTestFilesPerTask)
436
+ problems.push({
437
+ line: t.line,
438
+ kind: "cap",
439
+ message: `TASK ${t.task} names ${size.files} test files, over the cap of ${caps.maxTestFilesPerTask}`,
440
+ });
441
+ for (const c of t.create)
442
+ if (!newFiles.has(path.posix.normalize(c.file)))
443
+ problems.push({
444
+ line: c.line,
445
+ kind: "inventory",
446
+ message: `TASK ${t.task}: CREATE in \`${c.file}\` has no NEW row naming it in the Reuse Inventory's File column`,
447
+ });
237
448
  }
238
- return [...out, cur];
449
+ const groups: GroupSize[] = blocks.groups.map((g) => {
450
+ const tests = sizes.filter((s) => s.group === g.group).reduce((n, s) => n + s.tests, 0);
451
+ const bytes = Buffer.byteLength(lines.slice(g.line - 1, g.end).join("\n"));
452
+ return { group: g.group, title: g.title, tasks: g.tasks.length, tests, kb: kb1(bytes) };
453
+ });
454
+ for (const g of groups) {
455
+ const at = blocks.groups.find((x) => x.group === g.group)!.line;
456
+ if (g.tasks > caps.maxPerGroup)
457
+ problems.push({
458
+ line: at,
459
+ kind: "cap",
460
+ message: `GROUP ${g.group} has ${g.tasks} tasks, over the cap of ${caps.maxPerGroup}`,
461
+ });
462
+ if (g.tests > caps.maxTestsPerGroup)
463
+ problems.push({
464
+ line: at,
465
+ kind: "cap",
466
+ message: `GROUP ${g.group} has ${g.tests} TEST FIRST tests, over the cap of ${caps.maxTestsPerGroup}`,
467
+ });
468
+ }
469
+ problems.sort((a, b) => a.line - b.line);
470
+ return { groups, sizes, overCap, problems };
471
+ }
472
+
473
+ export interface ExistenceFinding {
474
+ line: number;
475
+ task: number;
476
+ message: string;
477
+ }
478
+
479
+ const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
480
+
481
+ const wordIn = (body: string, word: string) =>
482
+ new RegExp(`(?<![\\w$])${escapeRe(word)}(?![\\w$])`).test(body);
483
+
484
+ /** The 1-based lines of `body` that are a Markdown heading reading exactly `heading`. */
485
+ const headingLines = (body: string, heading: string): number[] =>
486
+ body.split(/\r?\n/).flatMap((l, i) => {
487
+ const h = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/.exec(l);
488
+ return h !== null && h[1]!.trim() === heading ? [i + 1] : [];
489
+ });
490
+
491
+ /** A key path's segments nested in indented `key:` lines (YAML): each one inside the block of the one before. */
492
+ function nestedKeys(body: string, segs: string[]): boolean {
493
+ const lines = body.split(/\r?\n/);
494
+ const indent = (l: string) => /^\s*/.exec(l)![0].length;
495
+ const walk = (from: number, to: number, k: number, above: number): boolean => {
496
+ const key = new RegExp(`^\\s*["']?${escapeRe(segs[k]!)}["']?\\s*:`);
497
+ for (let i = from; i < to; i++) {
498
+ const l = lines[i]!;
499
+ if (l.trim() === "" || indent(l) <= above || !key.test(l)) continue;
500
+ if (k === segs.length - 1) return true;
501
+ let end = i + 1;
502
+ while (end < to && (lines[end]!.trim() === "" || indent(lines[end]!) > indent(l))) end++;
503
+ if (walk(i + 1, end, k + 1, indent(l))) return true;
504
+ }
505
+ return false;
506
+ };
507
+ return walk(0, lines.length, 0, -1);
508
+ }
509
+
510
+ /** A key path as a `[table]` header holding its first segments and a `key =` line for the rest (TOML). */
511
+ function tableKey(body: string, segs: string[]): boolean {
512
+ const lines = body.split(/\r?\n/);
513
+ for (let k = 1; k < segs.length; k++) {
514
+ const table = segs.slice(0, k).join(".");
515
+ const key = segs.slice(k).join(".");
516
+ const start = lines.findIndex((l) => l.trim() === `[${table}]`);
517
+ if (start < 0) continue;
518
+ const end = lines.findIndex((l, i) => i > start && /^\s*\[/.test(l));
519
+ const keyRe = new RegExp(`^\\s*${escapeRe(key)}\\s*=`);
520
+ if (lines.slice(start + 1, end < 0 ? undefined : end).some((l) => keyRe.test(l))) return true;
521
+ }
522
+ return false;
523
+ }
524
+
525
+ /** Config files whose dotted keys must be there as the whole key path. */
526
+ const CONFIG_EXTS = new Set([".json", ".jsonc", ".yaml", ".yml", ".toml"]);
527
+
528
+ /** Whether parsed JSON `value` holds `segs` as nested object keys. */
529
+ function jsonPath(value: unknown, segs: string[]): boolean {
530
+ let at = value;
531
+ for (const s of segs) {
532
+ if (typeof at !== "object" || at === null || Array.isArray(at) || !Object.hasOwn(at, s))
533
+ return false;
534
+ at = (at as Record<string, unknown>)[s];
535
+ }
536
+ return true;
239
537
  }
240
538
 
241
539
  /**
242
- * Each runbook task's `Test first:` line: one or more tests separated by `;` (per entry,
243
- * first backticked span = file, second = test name), `n/a — {reason}`, missing, or
244
- * malformed (an entry with one span, or no test at all). A task's text runs from its
245
- * bullet to the next bullet or heading.
540
+ * Whether config `body` of `file` holds the dotted key `bare` as the whole key path: a
541
+ * `.json` file that parses is walked as JSON; otherwise the key is written whole, nested
542
+ * in indented `key:` / `"key":` lines (YAML, indented JSON), or a `[table]` and its
543
+ * `key =` line (TOML).
246
544
  */
247
- export function readTestFirst(plan: string): TestFirst[] {
248
- const out: TestFirst[] = [];
249
- const lines = plan.split("\n");
250
- for (let i = 0; i < lines.length; i++) {
251
- const head = TASK_LINE.exec(lines[i]!);
252
- if (!head) continue;
253
- let text = lines[i]!;
254
- for (let j = i + 1; j < lines.length && !/^\s*(- |#)/.test(lines[j]!); j++)
255
- text += ` ${lines[j]}`;
256
- const task = Number(head[1]);
257
- const at = text.indexOf(TEST_FIRST);
258
- if (at < 0) {
259
- out.push({ task, kind: "missing" });
260
- continue;
545
+ function hasDottedKey(file: string, body: string, bare: string): boolean {
546
+ const segs = bare.split(".");
547
+ const json =
548
+ path.posix.extname(file).toLowerCase() === ".json" ? parseJson(body) : { ok: false as const };
549
+ if (json.ok) return jsonPath(json.value, segs);
550
+ return wordIn(body, bare) || nestedKeys(body, segs) || tableKey(body, segs);
551
+ }
552
+
553
+ /**
554
+ * Each READ / UPDATE / DELETE line of an unticked task whose file or symbol is not
555
+ * there, read from `root`: a plain word-boundary search in the named file. `§ heading`
556
+ * must equal one of the file's heading lines; a dotted key in a config file (`CONFIG_EXTS`)
557
+ * must be there as the whole key path, and in any other file matches on its last segment;
558
+ * a file-only line checks the file exists. A line naming
559
+ * what the task itself or a task it DEPENDS ON creates is not checked: it does not
560
+ * exist yet.
561
+ */
562
+ export function planExistence(text: string, root: string): ExistenceFinding[] {
563
+ const blocks = parsePlanBlocks(text);
564
+ const byTask = new Map(blocks.tasks.map((t) => [t.task, t]));
565
+ const out: ExistenceFinding[] = [];
566
+ const cache = new Map<string, string | null>();
567
+ const read = (file: string) => {
568
+ if (!cache.has(file)) {
569
+ const abs = path.resolve(root, file);
570
+ const inside = !path.relative(root, abs).startsWith("..");
571
+ cache.set(
572
+ file,
573
+ inside && fs.statSync(abs, { throwIfNoEntry: false })?.isFile()
574
+ ? fs.readFileSync(abs, "utf-8")
575
+ : null,
576
+ );
261
577
  }
262
- const rest = text.slice(at + TEST_FIRST.length).trim();
263
- if (/^n\/a\b/i.test(rest)) {
264
- out.push({ task, kind: "na", reason: rest.replace(/^n\/a\s*[—–-]?\s*/i, "") });
265
- continue;
578
+ return cache.get(file)!;
579
+ };
580
+ for (const t of blocks.tasks) {
581
+ if (t.done) continue;
582
+ const created = [t, ...t.dependsOn.map((d) => byTask.get(d)).filter((d) => d !== undefined)]
583
+ .flatMap((d) => d.create)
584
+ .map((c) => ({ file: path.posix.normalize(c.file), symbol: c.symbol }));
585
+ for (const ref of [...t.read, ...t.update, ...t.delete]) {
586
+ const file = path.posix.normalize(ref.file);
587
+ if (
588
+ created.some((c) => c.file === file && (c.symbol === undefined || c.symbol === ref.symbol))
589
+ )
590
+ continue;
591
+ const body = read(file);
592
+ const miss = (message: string) => out.push({ line: ref.line, task: t.task, message });
593
+ if (body === null) {
594
+ miss(`TASK ${t.task}: \`${ref.file}\` does not exist`);
595
+ continue;
596
+ }
597
+ if (ref.symbol === undefined) continue;
598
+ if (ref.symbol.startsWith("§")) {
599
+ const heading = ref.symbol.replace(/^§\s*/, "").trim();
600
+ if (headingLines(body, heading).length === 0)
601
+ miss(`TASK ${t.task}: no heading \`${heading}\` in \`${ref.file}\``);
602
+ continue;
603
+ }
604
+ const bare = ref.symbol.replace(/\(\)$/, "");
605
+ const key = bare.split(".").at(-1)!;
606
+ if (bare.includes(".") && CONFIG_EXTS.has(path.posix.extname(file).toLowerCase())) {
607
+ if (!hasDottedKey(file, body, bare))
608
+ miss(`TASK ${t.task}: \`${bare}\` is not in \`${ref.file}\``);
609
+ } else if (!wordIn(body, key))
610
+ miss(
611
+ key === bare
612
+ ? `TASK ${t.task}: \`${key}\` is not in \`${ref.file}\``
613
+ : `TASK ${t.task}: \`${key}\` (last segment of \`${ref.symbol}\`) is not in \`${ref.file}\``,
614
+ );
266
615
  }
267
- const entries = splitEntries(rest).map((e) =>
268
- [...e.matchAll(/`([^`]+)`/g)].map((m) => m[1]!.trim()),
269
- );
270
- const tests = entries
271
- .filter((spans) => spans.length >= 2)
272
- .map((spans) => ({ test: path.posix.normalize(spans[0]!), name: spans[1]! }));
273
- out.push(
274
- tests.length > 0 && !entries.some((spans) => spans.length === 1)
275
- ? { task, kind: "test", tests }
276
- : { task, kind: "malformed" },
277
- );
278
616
  }
279
- return out;
617
+ return out.sort((a, b) => a.line - b.line);
618
+ }
619
+
620
+ /** True when `after` keeps every non-blank line of `before`, in order, ignoring whitespace: lines were only added. */
621
+ export function onlyAddsLines(before: string, after: string): boolean {
622
+ const norm = (text: string) =>
623
+ text
624
+ .split("\n")
625
+ .map((l) => l.replace(/\s+/g, ""))
626
+ .filter(Boolean);
627
+ const want = norm(before);
628
+ let kept = 0;
629
+ for (const line of norm(after)) if (kept < want.length && line === want[kept]) kept++;
630
+ return kept === want.length;
280
631
  }
281
632
 
282
633
  /** `test` as a repo-relative path inside `top`; usage error when absolute, outside, or absent. */
@@ -318,11 +669,234 @@ const fenceFor = (text: string) =>
318
669
  "`".repeat(Math.max(3, ...[...text.matchAll(/`+/g)].map((m) => m[0].length + 1)));
319
670
 
320
671
  interface Gap {
321
- task: number;
672
+ /** null for a plan-level gap (`test-first-unread`). */
673
+ task: number | null;
322
674
  kind: string;
323
675
  detail: string;
324
676
  }
325
677
 
678
+ /** Gaps about when a test was seen failing; no edit made after the task's code can close one. */
679
+ export const TEST_ORDER_GAPS: ReadonlySet<string> = new Set([
680
+ "no-red",
681
+ "late-red",
682
+ "red-mismatch",
683
+ "red-evidence-missing",
684
+ "test-changed",
685
+ ]);
686
+
687
+ /** The gap for a task whose only test field is a TEST EXCEPTION that is not honoured. */
688
+ export const EXCEPTION_REFUSED = "exception-refused";
689
+
690
+ /** The status row step plan-execute's finish writes; its commit carries the code of each task its log records DONE. */
691
+ export const PLAN_EXECUTE_STEP = "build-plan-execute";
692
+
693
+ const repoRel = (top: string, cwd: string, p: string) =>
694
+ path.relative(top, path.resolve(cwd, p)).split(path.sep).join("/");
695
+
696
+ /**
697
+ * Per task, the first plan-execute step commit whose log records the task `DONE` — the
698
+ * commit that first holds the task's code. `steps finish` writes the row then commits
699
+ * everything, so a row's commit is the first commit after its `parentSha` touching the status file.
700
+ */
701
+ function taskCodeCommits(
702
+ top: string,
703
+ cwd: string,
704
+ file: string,
705
+ workflow: string,
706
+ ): Map<number, string> {
707
+ const statusRel = repoRel(top, cwd, file);
708
+ const commits = new Map<number, string>();
709
+ for (const r of readStatusRows(file) as Array<Record<string, unknown>>) {
710
+ if (r.type !== "step-done" || r.workflow !== workflow || r.step !== PLAN_EXECUTE_STEP) continue;
711
+ const log = Array.isArray(r.artifacts) ? r.artifacts.map(String)[0] : undefined;
712
+ if (typeof r.parentSha !== "string" || log === undefined) continue;
713
+ const range = `${r.parentSha}..HEAD`;
714
+ const commit = git(top, ["rev-list", "--reverse", "--ancestry-path", range, "--", statusRel])
715
+ ?.split("\n")
716
+ .find(Boolean);
717
+ const text =
718
+ commit === undefined ? null : git(top, ["show", `${commit}:${repoRel(top, cwd, log)}`]);
719
+ if (commit === undefined || text === null) continue;
720
+ for (const n of doneTasks(text)) if (!commits.has(n)) commits.set(n, commit);
721
+ }
722
+ return commits;
723
+ }
724
+
725
+ /** The task numbers a plan-execute log records `DONE — TASK N` for, in log order. */
726
+ export function doneTasks(log: string): number[] {
727
+ return [...log.matchAll(/^DONE\s*[—–-]+\s*TASK\s+(\d+)\b/gim)].map((m) => Number(m[1]));
728
+ }
729
+
730
+ /**
731
+ * Why a task's `TEST EXCEPTION` lines do not count, or null when they do: every
732
+ * line committed, and last changed by a commit that does not write the status file.
733
+ * Every workflow step commit writes it, so a line riding one is refused; agents are
734
+ * barred from committing, so the remaining commits are human-made.
735
+ */
736
+ function exceptionRefusal(
737
+ top: string,
738
+ plan: string,
739
+ lines: number[],
740
+ statusRel: string,
741
+ ): string | null {
742
+ const blame = git(top, ["blame", "--porcelain", "-L", `${lines[0]},${lines.at(-1)}`, "--", plan]);
743
+ if (blame === null) return "the plan file is not committed";
744
+ const shas = new Set([...blame.matchAll(/^([0-9a-f]{40}) \d+ \d+/gm)].map((m) => m[1]!));
745
+ if ([...shas].some((s) => /^0+$/.test(s)))
746
+ return "the line is not committed — a human commits it before the build re-runs";
747
+ for (const sha of shas) {
748
+ const files = git(top, ["show", "--name-only", "--format=", sha])?.split("\n") ?? [];
749
+ if (files.includes(statusRel))
750
+ return `last changed by ${sha.slice(0, 7)}, a workflow step commit (it also writes \`${statusRel}\`) — commit the line in a commit that does not touch it`;
751
+ }
752
+ return null;
753
+ }
754
+
755
+ const withoutExt = (p: string) => p.replace(/\.[^./]*$/, "");
756
+
757
+ /**
758
+ * Whether a grep hit for `stem` in `file` refers to something other than the files of
759
+ * `targets` (repo-relative): false for a hit inside a target, or a line whose every
760
+ * path-like mention of `stem` resolves to a target. A `./` or `../` path resolves
761
+ * against `file`'s folder; any other path with a `/` matches a target ending in it.
762
+ */
763
+ function namesOldPath(stem: string, targets: string[]) {
764
+ const bare = targets.map(withoutExt);
765
+ const isTarget = (token: string, file: string) => {
766
+ const t = withoutExt(token);
767
+ if (t.startsWith("./") || t.startsWith("../"))
768
+ return bare.includes(path.posix.join(path.posix.dirname(file), t));
769
+ return t.includes("/") && bare.some((b) => b === t || b.endsWith(`/${t}`));
770
+ };
771
+ return (file: string, text: string) => {
772
+ if (targets.includes(file)) return false;
773
+ const mentions = text
774
+ .split(/[^\w./@-]+/)
775
+ .filter((tok) => path.posix.basename(withoutExt(tok)) === stem);
776
+ return mentions.length === 0 || mentions.some((tok) => !isTarget(tok, file));
777
+ };
778
+ }
779
+
780
+ /** The gap for a DELETE line whose file or symbol the tree still holds or refers to. */
781
+ export const DELETE_STILL_REFERENCED = "delete-still-referenced";
782
+
783
+ /**
784
+ * One `delete-still-referenced` gap per DELETE line of `tasks` the tree at `top` still
785
+ * holds: a file-only line whose file exists, or whose file name (no extension) a tracked
786
+ * or untracked file names as a word; a symbol (a dotted key's last segment) named as a
787
+ * word; a `§ heading` written as `§ heading`, or still a heading of its file. The plan
788
+ * file and the folder it sits in are not searched. A line naming what a task of
789
+ * `planTasks` CREATEs is a move, not checked. A file-only line whose file name a CREATE
790
+ * of `planTasks` reuses is a file move: the created file, and lines whose every mention
791
+ * of the name is a path to the created file, are not references. A word search hits
792
+ * other things of the same name, so this is a gap for verify to judge, never a refusal.
793
+ */
794
+ function deleteGaps(
795
+ top: string,
796
+ planRel: string,
797
+ tasks: PlanTaskBlock[],
798
+ planTasks: PlanTaskBlock[],
799
+ ): Gap[] {
800
+ const created = planTasks.flatMap((t) => t.create);
801
+ const planDir = path.posix.dirname(planRel);
802
+ const excludes = [`:(exclude)${planRel}`, ...(planDir === "." ? [] : [`:(exclude)${planDir}`])];
803
+ const grep = (term: string, word: boolean, keep?: (file: string, text: string) => boolean) => {
804
+ const res = spawnSync(
805
+ "git",
806
+ [
807
+ "grep",
808
+ "-n",
809
+ "-z",
810
+ "-I",
811
+ "--untracked",
812
+ ...(word ? ["-w"] : []),
813
+ "-F",
814
+ "-e",
815
+ term,
816
+ "--",
817
+ ".",
818
+ ...excludes,
819
+ ],
820
+ { cwd: top, encoding: "utf-8" },
821
+ );
822
+ if (res.status === 1) return { hits: [] as string[] };
823
+ if (res.status !== 0)
824
+ return {
825
+ failed: `git grep exited ${res.status ?? res.signal}: ${(res.stderr ?? "").trim()}`,
826
+ };
827
+ const hits = res.stdout
828
+ .split("\n")
829
+ .filter(Boolean)
830
+ .map((l) => l.split("\0"))
831
+ .filter(([file, , text]) => keep === undefined || keep(file!, text ?? ""))
832
+ .map((parts) => parts.slice(0, 2).join(":"));
833
+ return { hits };
834
+ };
835
+ const listed = (hits: string[]) =>
836
+ hits
837
+ .slice(0, 5)
838
+ .map((h) => `\`${h}\``)
839
+ .join(", ") + (hits.length > 5 ? `, and ${hits.length - 5} more` : "");
840
+ const gaps: Gap[] = [];
841
+ for (const t of tasks)
842
+ for (const ref of t.delete) {
843
+ const file = path.posix.normalize(ref.file);
844
+ const moved = created.some((c) =>
845
+ ref.symbol === undefined ? path.posix.normalize(c.file) === file : c.symbol === ref.symbol,
846
+ );
847
+ if (moved) continue;
848
+ const movedTo =
849
+ ref.symbol === undefined
850
+ ? created
851
+ .filter(
852
+ (c) =>
853
+ c.symbol === undefined &&
854
+ path.posix.basename(path.posix.normalize(c.file)) === path.posix.basename(file),
855
+ )
856
+ .map((c) => path.posix.normalize(c.file))
857
+ : [];
858
+ const gap = (detail: string) =>
859
+ gaps.push({ task: t.task, kind: DELETE_STILL_REFERENCED, detail });
860
+ const abs = path.join(top, file);
861
+ const exists = fs.statSync(abs, { throwIfNoEntry: false })?.isFile() === true;
862
+ let what: string;
863
+ let found: { hits?: string[]; failed?: string };
864
+ if (ref.symbol === undefined) {
865
+ if (exists) {
866
+ gap(`DELETE \`${ref.file}\`: the file still exists`);
867
+ continue;
868
+ }
869
+ const stem = path.posix.basename(file).replace(/\.[^.]*$/, "");
870
+ what = `DELETE \`${ref.file}\` is still referenced as \`${stem}\``;
871
+ found = grep(stem, true, movedTo.length === 0 ? undefined : namesOldPath(stem, movedTo));
872
+ } else if (ref.symbol.startsWith("§")) {
873
+ const heading = ref.symbol.replace(/^§\s*/, "").trim();
874
+ what = `DELETE ${ref.symbol} in \`${ref.file}\` is still referenced`;
875
+ found = grep(`§ ${heading}`, false);
876
+ if (exists && found.hits !== undefined)
877
+ found.hits.push(
878
+ ...headingLines(fs.readFileSync(abs, "utf-8"), heading).map((n) => `${file}:${n}`),
879
+ );
880
+ } else {
881
+ const bare = ref.symbol.replace(/\(\)$/, "");
882
+ what = `DELETE \`${ref.symbol}\` in \`${ref.file}\` is still referenced`;
883
+ found = grep(bare.split(".").at(-1)!, true);
884
+ }
885
+ if (found.failed !== undefined)
886
+ gap(
887
+ `${what.replace(/ is still referenced.*$/, "")}: references not checked — ${found.failed}`,
888
+ );
889
+ else if (found.hits!.length > 0) gap(`${what}: ${listed([...new Set(found.hits)].sort())}`);
890
+ }
891
+ return gaps;
892
+ }
893
+
894
+ interface ExceptionResult {
895
+ task: number;
896
+ refusal: string | null;
897
+ cleared: string[];
898
+ }
899
+
326
900
  interface AuditRow {
327
901
  task: number;
328
902
  test: string;
@@ -331,16 +905,14 @@ interface AuditRow {
331
905
  green: string;
332
906
  }
333
907
 
334
- /** The red rows of status.jsonl for this workflow and sub-plan, oldest first. */
335
- function redRows(file: string, workflow: string, subPlan: number | undefined) {
908
+ /**
909
+ * The red rows of status.jsonl for this workflow, oldest first. Task numbers are unique
910
+ * across the plan, so a red matches its task by number whatever group recorded it.
911
+ */
912
+ export function redRows(file: string, workflow: string) {
336
913
  return readStatusRows(file).filter((r) => {
337
914
  const row = r as Record<string, unknown>;
338
- return (
339
- row.type === "step-done" &&
340
- row.workflow === workflow &&
341
- row.step === RED_STEP &&
342
- (subPlan === undefined || row.subPlan === subPlan)
343
- );
915
+ return row.type === "step-done" && row.workflow === workflow && row.step === RED_STEP;
344
916
  }) as Array<Record<string, unknown>>;
345
917
  }
346
918
 
@@ -352,11 +924,21 @@ function writeAuditReport(
352
924
  plan?: string;
353
925
  rows: AuditRow[];
354
926
  gaps: Gap[];
927
+ testOrderOnly: boolean;
928
+ exceptions: ExceptionResult[];
929
+ lateUnchecked: number[];
355
930
  diffs: Array<{ task: number; test: string; diff: string }>;
356
931
  outputs: Array<{ test: string; tail: string }>;
357
932
  },
358
933
  ): void {
359
- const out = [`Enforced: ${o.enforced}`, `Gaps: ${o.gaps.length}`, "", "<!-- verdict:end -->", ""];
934
+ const out = [
935
+ `Enforced: ${o.enforced}`,
936
+ `Gaps: ${o.gaps.length}`,
937
+ `Test order only: ${o.testOrderOnly}`,
938
+ "",
939
+ "<!-- verdict:end -->",
940
+ "",
941
+ ];
360
942
  out.push("# Test-First Audit", "");
361
943
  if (o.plan) out.push(`Plan: \`${o.plan}\``, "");
362
944
  if (!o.enforced) out.push(`Not enforced: ${o.reason}.`, "");
@@ -371,7 +953,20 @@ function writeAuditReport(
371
953
  }
372
954
  out.push("## Gaps", "");
373
955
  if (o.gaps.length === 0) out.push("None.");
374
- for (const g of o.gaps) out.push(`- Task ${g.task} \`${g.kind}\` — ${g.detail}`);
956
+ for (const g of o.gaps)
957
+ out.push(`- ${g.task === null ? "Plan" : `Task ${g.task}`} \`${g.kind}\` — ${g.detail}`);
958
+ if (o.exceptions.length > 0) out.push("", "## Test exceptions", "");
959
+ for (const e of o.exceptions)
960
+ out.push(
961
+ e.refusal === null
962
+ ? `- Task ${e.task} — honoured; cleared ${e.cleared.length > 0 ? e.cleared.join(", ") : "nothing"}`
963
+ : `- Task ${e.task} — not honoured: ${e.refusal}`,
964
+ );
965
+ if (o.lateUnchecked.length > 0) out.push("", "## Late-red check", "");
966
+ for (const task of o.lateUnchecked)
967
+ out.push(
968
+ `- Task ${task} — not checked: no plan-execute step commit's log records \`DONE — TASK ${task}\`, so when its code landed is unknown`,
969
+ );
375
970
  for (const d of o.diffs) {
376
971
  const fence = fenceFor(d.diff);
377
972
  out.push(
@@ -417,24 +1012,43 @@ export const testsCommand: CommandSpec = {
417
1012
  type: "string",
418
1013
  help: `lines of the log echoed to stderr afterwards (default ${DEFAULT_TAIL}; 0 for none)`,
419
1014
  },
1015
+ {
1016
+ name: "artifact",
1017
+ type: "string",
1018
+ help: "copy the log here, trim the copy (debug-evidence) and record the clamp; needs --fid and --step",
1019
+ },
1020
+ { name: "fid", type: "string", help: "--artifact: feature id, for the clamp log" },
1021
+ { name: "step", type: "string", help: "--artifact: step name, for the clamp log" },
1022
+ { name: "attempt", type: "string", help: "--artifact: attempt, for the clamp log" },
420
1023
  ],
421
1024
  output: {
422
1025
  verdict: "PASS | FAIL (null when the gate could not run)",
423
1026
  exitCode: "the gate's exit code",
424
1027
  gate: "the script that ran",
425
1028
  scope: "the command that ran, as status rows record it",
426
- failures: "0 on PASS; null otherwise — count failing suites from the log",
427
- log: "where the full output was saved (as given)",
1029
+ 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)`,
1030
+ reports: `{log}.reports — emptied before the run and passed to the gate as $${REPORT_DIR_ENV}`,
1031
+ log: "where the full output was saved (as given); the untouched original",
428
1032
  logBytes: "size of the saved output",
1033
+ artifact: "--artifact as given, else null",
1034
+ clamp: "the artifact's clamp record (raw = the log, source = scope), else null",
429
1035
  },
1036
+ textOmit: ["clamp"],
430
1037
  exitCodes: {
431
1038
  [EXIT_NO_GATE]: "no candidate gate is declared in package.json",
432
1039
  [EXIT_COULD_NOT_RUN]: "the gate could not run (exit 126 / 127): not a test failure",
1040
+ [EXIT_ARTIFACT_STEP]: "--artifact could not be written, trimmed or recorded",
433
1041
  },
434
1042
  run: (ctx) => {
435
1043
  const candidates = ctx.flags.gate as string[];
436
1044
  const logArg = String(ctx.flags.log);
437
1045
  if (logArg === "") throw new CommandError(EXIT.USAGE, "--log must be non-empty");
1046
+ const artifact = str(ctx.flags.artifact);
1047
+ const fid = str(ctx.flags.fid);
1048
+ const step = str(ctx.flags.step);
1049
+ const attempt = positiveInt(ctx.flags.attempt, "attempt");
1050
+ if (artifact !== undefined && (!fid || !step))
1051
+ throw new CommandError(EXIT.USAGE, "--artifact needs --fid and --step");
438
1052
  const tailRaw = str(ctx.flags.tail) ?? String(DEFAULT_TAIL);
439
1053
  if (!/^[0-9]+$/.test(tailRaw)) {
440
1054
  throw new CommandError(
@@ -456,21 +1070,60 @@ export const testsCommand: CommandSpec = {
456
1070
  }
457
1071
  const scope = gateScope(gate);
458
1072
  const log = path.resolve(ctx.cwd, logArg);
1073
+ const reports = freshReportDir(log);
459
1074
  ctx.log(`running ${scope} — full output in ${logArg}`);
460
- const exitCode = runToLog(scriptCommand(gate), top, log);
1075
+ const fetchedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
1076
+ const exitCode = runToLog(scriptCommand(gate), top, log, { [REPORT_DIR_ENV]: reports });
461
1077
  for (const line of Number(tailRaw) > 0 ? tailLines(log, Number(tailRaw)) : [])
462
1078
  ctx.log(line);
463
1079
  const couldNotRun = COULD_NOT_RUN_EXIT_CODES.has(exitCode);
464
1080
  const verdict = couldNotRun ? null : exitCode === 0 ? "PASS" : "FAIL";
1081
+ const counted = countReportFailures(reports);
1082
+ if (counted === null) ctx.log(NO_REPORT_HINT);
1083
+ else if (verdict === "FAIL" && counted === 0)
1084
+ ctx.log(
1085
+ `the JUnit reports in $${REPORT_DIR_ENV} hold no failing case — the gate failed outside its reported tests; failures unknown`,
1086
+ );
1087
+ const failures = verdict === "PASS" ? 0 : counted !== null && counted > 0 ? counted : null;
1088
+ let clamp: ClampRecord | null = null;
1089
+ let artifactFailed: string | null = null;
1090
+ if (artifact !== undefined) {
1091
+ try {
1092
+ const out = path.resolve(ctx.cwd, artifact);
1093
+ fs.mkdirSync(path.dirname(out), { recursive: true });
1094
+ fs.copyFileSync(log, out);
1095
+ const clampLog = clampLogPath(ctx.cwd, fid!, step!, attempt);
1096
+ fs.mkdirSync(path.dirname(clampLog), { recursive: true });
1097
+ fs.writeFileSync(clampLog, "");
1098
+ clamp = clampFile(out, "debug-evidence", artifact, {
1099
+ rawDir: null,
1100
+ source: scope,
1101
+ fetchedAt,
1102
+ original: log,
1103
+ });
1104
+ appendRecord(clampLog, clamp);
1105
+ } catch (err) {
1106
+ // The verdict stands; the step's artifact is what failed.
1107
+ clamp = null;
1108
+ artifactFailed = (err as Error).message;
1109
+ }
1110
+ }
465
1111
  ctx.emit({
466
1112
  verdict,
467
1113
  exitCode,
468
1114
  gate,
469
1115
  scope,
470
- failures: verdict === "PASS" ? 0 : null,
1116
+ failures,
1117
+ reports: `${logArg}.reports`,
471
1118
  log: logArg,
472
1119
  logBytes: fs.statSync(log).size,
1120
+ artifact: artifact ?? null,
1121
+ clamp,
473
1122
  });
1123
+ if (artifactFailed !== null) {
1124
+ ctx.log(`--artifact ${artifact}: ${artifactFailed}`);
1125
+ return EXIT_ARTIFACT_STEP;
1126
+ }
474
1127
  if (couldNotRun) {
475
1128
  ctx.log(
476
1129
  `${scope} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no tests executed; this is not a FAIL verdict`,
@@ -487,7 +1140,7 @@ export const testsCommand: CommandSpec = {
487
1140
  flags: [
488
1141
  FILE_FLAG,
489
1142
  WORKFLOW_FLAG,
490
- SUB_PLAN_FLAG,
1143
+ GROUP_FLAG,
491
1144
  {
492
1145
  name: "task",
493
1146
  type: "string",
@@ -529,7 +1182,7 @@ export const testsCommand: CommandSpec = {
529
1182
  },
530
1183
  run: (ctx) => {
531
1184
  const workflow = String(ctx.flags.workflow);
532
- const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
1185
+ const group = positiveInt(ctx.flags.group, "group");
533
1186
  const task = positiveInt(ctx.flags.task, "task")!;
534
1187
  const name = String(ctx.flags.name).trim();
535
1188
  if (name === "") throw new CommandError(EXIT.USAGE, "--name must be non-empty");
@@ -544,7 +1197,7 @@ export const testsCommand: CommandSpec = {
544
1197
  const blob = git(top, ["hash-object", "--", test]);
545
1198
  const status = statusFile(ctx);
546
1199
  const prior = fs.existsSync(status)
547
- ? redRows(status, workflow, subPlan)
1200
+ ? redRows(status, workflow)
548
1201
  .reverse()
549
1202
  .find((r) => r.task === task && r.test === test && r.testName === name)
550
1203
  : undefined;
@@ -581,7 +1234,7 @@ export const testsCommand: CommandSpec = {
581
1234
  file: statusFile(ctx),
582
1235
  workflow,
583
1236
  step: RED_STEP,
584
- subPlan,
1237
+ group,
585
1238
  artifacts: [path.relative(ctx.cwd, log), path.relative(ctx.cwd, snapshot)],
586
1239
  extras: {
587
1240
  task,
@@ -602,11 +1255,11 @@ export const testsCommand: CommandSpec = {
602
1255
  },
603
1256
  green: {
604
1257
  summary:
605
- "Audit a sub-plan's test-first evidence (a red per planned test, the test unchanged since, the named test passing now); exit 0 no gaps, 1 gaps.",
1258
+ "Audit a plan's test-first evidence (a red per TEST FIRST test recorded before the task's code commit, the test only added to since, the named test passing now); exit 0 no gaps, 1 gaps or a plan with no task markers.",
606
1259
  flags: [
607
1260
  FILE_FLAG,
608
1261
  WORKFLOW_FLAG,
609
- SUB_PLAN_FLAG,
1262
+ { ...GROUP_FLAG, help: "audit only this plan group's tasks (positive integer)" },
610
1263
  {
611
1264
  name: "plan",
612
1265
  type: "string",
@@ -614,11 +1267,6 @@ export const testsCommand: CommandSpec = {
614
1267
  repeatable: true,
615
1268
  help: "candidate plan file; the first that exists is audited",
616
1269
  },
617
- {
618
- name: "brief",
619
- type: "string",
620
- help: "the build input, audited when no plan file exists and it carries `**Task N:**` lines with `Test first:`",
621
- },
622
1270
  {
623
1271
  name: "log",
624
1272
  type: "string",
@@ -627,10 +1275,15 @@ export const testsCommand: CommandSpec = {
627
1275
  },
628
1276
  ],
629
1277
  output: {
630
- enforced: "false when there is nothing to audit (reason says why)",
1278
+ enforced:
1279
+ "false when the audit could not run: no plan file, a plan with no task markers (exit 1), or the test-file script undeclared (exit 0)",
631
1280
  reason: "why test-first is not enforced",
632
- plan: "the plan file audited (the brief when no plan file exists and it carries Test first lines)",
633
- gaps: "[{task, kind, detail}]: no-test-first | test-first-malformed | no-red | red-mismatch | red-evidence-missing | test-changed | not-green",
1281
+ plan: "the plan file audited",
1282
+ gaps: "[{task, kind, detail}]: no-test-first | test-first-malformed | test-first-unread (task null: a plan-level format problem) | no-red | late-red | red-mismatch | red-evidence-missing | test-changed | 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)",
1283
+ testOrderOnly:
1284
+ "true when there are gaps and every one is a test-order gap (no-red | late-red | red-mismatch | red-evidence-missing | test-changed)",
1285
+ lateRedUnchecked:
1286
+ "tasks with a red but no plan-execute step commit whose log records `DONE — TASK N`: the late-red check could not run for them",
634
1287
  log: "where the report was written (as given)",
635
1288
  },
636
1289
  exitCodes: {
@@ -638,41 +1291,66 @@ export const testsCommand: CommandSpec = {
638
1291
  },
639
1292
  run: (ctx) => {
640
1293
  const workflow = String(ctx.flags.workflow);
641
- const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
1294
+ const group = positiveInt(ctx.flags.group, "group");
642
1295
  const logArg = String(ctx.flags.log);
643
1296
  if (logArg === "") throw new CommandError(EXIT.USAGE, "--log must be non-empty");
644
1297
  const log = path.resolve(ctx.cwd, logArg);
645
1298
  const top = toplevel(ctx.cwd);
646
1299
  const exists = (p: string) => fs.existsSync(path.resolve(ctx.cwd, p));
647
- const planFile = (ctx.flags.plan as string[]).find(exists);
648
- const briefArg = str(ctx.flags.brief);
649
- const brief =
650
- planFile === undefined && briefArg !== undefined && exists(briefArg)
651
- ? briefArg
652
- : undefined;
653
- const plan = planFile ?? brief;
654
- const specs = plan
655
- ? readTestFirst(fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8"))
656
- : [];
657
- const reason =
1300
+ const plan = (ctx.flags.plan as string[]).find(exists);
1301
+ const planText = plan ? fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8") : "";
1302
+ const parsed = parsePlanBlocks(planText);
1303
+ const specs = readTestFirst(planText, group);
1304
+ // A plan with no task markers is an old-format plan: nothing it says can be audited,
1305
+ // and passing it would let its tests go unchecked.
1306
+ const refusal =
658
1307
  plan === undefined
659
- ? "no plan file — the build runs from its brief"
660
- : !specs.some((s) => s.kind !== "missing")
661
- ? brief !== undefined
662
- ? "no plan file, and the brief has no `**Task N:**` lines with `Test first:`"
663
- : "the plan has no `Test first:` lines"
664
- : resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
665
- ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
666
- : undefined;
667
- const empty = { rows: [], gaps: [], diffs: [], outputs: [] };
1308
+ ? `no plan file; ${NO_MARKERS_REASON}`
1309
+ : parsed.tasks.length === 0
1310
+ ? parsed.fenceOpen === undefined
1311
+ ? NO_MARKERS_REASON
1312
+ : fenceNeverClosed(parsed.fenceOpen)
1313
+ : undefined;
1314
+ if (refusal === undefined && group !== undefined) {
1315
+ const g = parsed.groups.find((x) => x.group === group);
1316
+ if (g === undefined) throw new CommandError(EXIT.USAGE, `the plan has no GROUP ${group}`);
1317
+ if (g.tasks.length === 0)
1318
+ throw new CommandError(EXIT.USAGE, `GROUP ${group} has no tasks; nothing to audit`);
1319
+ }
1320
+ const reason =
1321
+ refusal ??
1322
+ (resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
1323
+ ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
1324
+ : undefined);
1325
+ const empty = {
1326
+ rows: [],
1327
+ gaps: [],
1328
+ testOrderOnly: false,
1329
+ exceptions: [],
1330
+ lateUnchecked: [],
1331
+ diffs: [],
1332
+ outputs: [],
1333
+ };
668
1334
  if (reason !== undefined) {
669
1335
  writeAuditReport(log, { enforced: false, reason, plan, ...empty });
670
- ctx.emit({ enforced: false, reason, plan: plan ?? null, gaps: [], log: logArg });
1336
+ ctx.emit({
1337
+ enforced: false,
1338
+ reason,
1339
+ plan: plan ?? null,
1340
+ gaps: [],
1341
+ testOrderOnly: false,
1342
+ lateRedUnchecked: [],
1343
+ log: logArg,
1344
+ });
671
1345
  ctx.log(`test-first not enforced: ${reason}`);
672
- return EXIT.OK;
1346
+ return refusal === undefined ? EXIT.OK : EXIT.NO;
673
1347
  }
674
1348
 
675
- const reds = redRows(statusFile(ctx), workflow, subPlan);
1349
+ const reds = redRows(statusFile(ctx), workflow);
1350
+ const statusRel = repoRel(top, ctx.cwd, statusFile(ctx));
1351
+ const codeCommits = taskCodeCommits(top, ctx.cwd, statusFile(ctx), workflow);
1352
+ const exceptions: ExceptionResult[] = [];
1353
+ const lateUnchecked = new Set<number>();
676
1354
  const gaps: Gap[] = [];
677
1355
  const rows: AuditRow[] = [];
678
1356
  const diffs: Array<{ task: number; test: string; diff: string }> = [];
@@ -696,18 +1374,54 @@ export const testsCommand: CommandSpec = {
696
1374
  return run;
697
1375
  };
698
1376
  for (const s of specs) {
699
- if (s.kind === "na") continue;
1377
+ if (s.kind === "na") {
1378
+ const block = parsed.tasks.find((t) => t.task === s.task)!;
1379
+ if (block.testFirst !== undefined || block.testException === undefined) continue;
1380
+ const refused = exceptionRefusal(
1381
+ top,
1382
+ repoRel(top, ctx.cwd, plan!),
1383
+ block.testException.lines,
1384
+ statusRel,
1385
+ );
1386
+ exceptions.push({
1387
+ task: s.task,
1388
+ refusal: refused,
1389
+ cleared: refused === null ? ["the task's `TEST FIRST` check"] : [],
1390
+ });
1391
+ if (refused !== null)
1392
+ gaps.push({
1393
+ task: s.task,
1394
+ kind: EXCEPTION_REFUSED,
1395
+ detail: `the task's only test field is a \`**TEST EXCEPTION:**\`, not honoured: ${refused}`,
1396
+ });
1397
+ continue;
1398
+ }
700
1399
  if (s.kind !== "test") {
701
1400
  gaps.push({
702
1401
  task: s.task,
703
1402
  kind: s.kind === "missing" ? "no-test-first" : "test-first-malformed",
704
1403
  detail:
705
1404
  s.kind === "missing"
706
- ? "the task has no `Test first:` line"
707
- : "`Test first:` is neither `n/a — {reason}` nor `;`-separated entries of a backticked test file and test name",
1405
+ ? "the task has neither a `**TEST FIRST:**` nor a `**TEST EXCEPTION:**` field"
1406
+ : "`**TEST FIRST:**` is neither `n/a — {reason}` nor one sub-bullet per test naming a backticked test file and test name",
708
1407
  });
709
1408
  continue;
710
1409
  }
1410
+ const excepted = s.exception;
1411
+ const exception: ExceptionResult | undefined =
1412
+ excepted === undefined
1413
+ ? undefined
1414
+ : {
1415
+ task: s.task,
1416
+ refusal: exceptionRefusal(
1417
+ top,
1418
+ repoRel(top, ctx.cwd, plan!),
1419
+ excepted.lines,
1420
+ statusRel,
1421
+ ),
1422
+ cleared: [],
1423
+ };
1424
+ if (exception !== undefined) exceptions.push(exception);
711
1425
  const taskReds = reds.filter((r) => r.task === s.task);
712
1426
  const planned = (r: Record<string, unknown>) =>
713
1427
  s.tests.some((t) => t.test === r.test && t.name === r.testName);
@@ -720,6 +1434,16 @@ export const testsCommand: CommandSpec = {
720
1434
  green: "—",
721
1435
  };
722
1436
  rows.push(row);
1437
+ const clearing =
1438
+ exception?.refusal === null &&
1439
+ excepted!.tests.some((e) => e.test === t.test && e.name === t.name)
1440
+ ? exception
1441
+ : undefined;
1442
+ const gap = (kind: string, detail: string) => {
1443
+ if (clearing !== undefined && TEST_ORDER_GAPS.has(kind))
1444
+ clearing.cleared.push(`\`${kind}\` for \`${t.test}\` "${t.name}"`);
1445
+ else gaps.push({ task: s.task, kind, detail });
1446
+ };
723
1447
  const red = [...taskReds]
724
1448
  .reverse()
725
1449
  .find((r) => r.test === t.test && r.testName === t.name);
@@ -738,19 +1462,27 @@ export const testsCommand: CommandSpec = {
738
1462
  }
739
1463
  recorded.push(`\`${rTest}\` "${rName}" (${now})`);
740
1464
  }
741
- gaps.push({
742
- task: s.task,
743
- kind: "red-mismatch",
744
- detail: `no red for \`${t.test}\` "${t.name}"; reds recorded for ${recorded.join(", ")}`,
745
- });
1465
+ gap(
1466
+ "red-mismatch",
1467
+ `no red for \`${t.test}\` "${t.name}"; reds recorded for ${recorded.join(", ")}`,
1468
+ );
746
1469
  } else if (red === undefined) {
747
- gaps.push({
748
- task: s.task,
749
- kind: "no-red",
750
- detail: `no red recorded for "${t.name}" — the test was never seen failing before the code`,
751
- });
1470
+ gap(
1471
+ "no-red",
1472
+ `no red recorded for "${t.name}" — the test was never seen failing before the code`,
1473
+ );
752
1474
  } else {
753
1475
  row.red = `recorded ${String(red.at)}`;
1476
+ const code = codeCommits.get(s.task);
1477
+ const on = typeof red.parentSha === "string" ? red.parentSha : undefined;
1478
+ if (code === undefined || on === undefined) lateUnchecked.add(s.task);
1479
+ else if (runGit(top, ["merge-base", "--is-ancestor", code, on]).ok) {
1480
+ row.red = `late — ${row.red}`;
1481
+ gap(
1482
+ "late-red",
1483
+ `the red for "${t.name}" was recorded on ${on.slice(0, 7)}, on or after ${code.slice(0, 7)}, the first commit whose plan-execute log records TASK ${s.task} DONE — the task's code already existed`,
1484
+ );
1485
+ }
754
1486
  const snap = (Array.isArray(red.artifacts) ? red.artifacts : [])
755
1487
  .map(String)
756
1488
  .find((a) => a.endsWith(".snapshot"));
@@ -758,41 +1490,39 @@ export const testsCommand: CommandSpec = {
758
1490
  const testAbs = path.join(top, t.test);
759
1491
  if (snapAbs === undefined || !fs.existsSync(snapAbs)) {
760
1492
  row.changed = "unknown";
761
- gaps.push({
762
- task: s.task,
763
- kind: "red-evidence-missing",
764
- detail: `the red's test snapshot ${snap ?? "(none recorded)"} is missing`,
765
- });
1493
+ gap(
1494
+ "red-evidence-missing",
1495
+ `the red's test snapshot ${snap ?? "(none recorded)"} is missing`,
1496
+ );
766
1497
  } else if (!fs.existsSync(testAbs)) {
767
1498
  row.changed = "deleted";
768
- gaps.push({
769
- task: s.task,
770
- kind: "test-changed",
771
- detail: `\`${t.test}\` no longer exists`,
772
- });
1499
+ gap("test-changed", `\`${t.test}\` no longer exists`);
773
1500
  } else if (!fs.readFileSync(snapAbs).equals(fs.readFileSync(testAbs))) {
774
- row.changed = "yes";
775
- gaps.push({
776
- task: s.task,
777
- kind: "test-changed",
778
- detail: `\`${t.test}\` differs from its red snapshot for "${t.name}" (diff below)`,
779
- });
780
- const diff = spawnSync(
781
- "git",
782
- ["diff", "--no-index", "--no-color", "--", path.relative(top, snapAbs), t.test],
783
- { cwd: top, encoding: "utf-8" },
1501
+ const added = onlyAddsLines(
1502
+ fs.readFileSync(snapAbs, "utf-8"),
1503
+ fs.readFileSync(testAbs, "utf-8"),
784
1504
  );
785
- diffs.push({ task: s.task, test: t.test, diff: diff.stdout.trimEnd() });
1505
+ row.changed = added ? "added lines only" : "yes";
1506
+ if (!added)
1507
+ gap(
1508
+ "test-changed",
1509
+ `\`${t.test}\` differs from its red snapshot for "${t.name}" (diff below)`,
1510
+ );
1511
+ const diff = runGit(top, [
1512
+ "diff",
1513
+ "--no-index",
1514
+ "--no-color",
1515
+ "--",
1516
+ path.relative(top, snapAbs),
1517
+ t.test,
1518
+ ]);
1519
+ diffs.push({ task: s.task, test: t.test, diff: diff.stdout });
786
1520
  } else row.changed = "no";
787
1521
  }
788
1522
 
789
1523
  if (!fs.existsSync(path.join(top, t.test))) {
790
1524
  row.green = "file missing";
791
- gaps.push({
792
- task: s.task,
793
- kind: "not-green",
794
- detail: `\`${t.test}\` does not exist`,
795
- });
1525
+ gap("not-green", `\`${t.test}\` does not exist`);
796
1526
  continue;
797
1527
  }
798
1528
  const green = greenRun(t.test);
@@ -800,17 +1530,152 @@ export const testsCommand: CommandSpec = {
800
1530
  const why = judgeGreen(green.cases, t.name);
801
1531
  row.green = why === null ? "passed" : "not passed";
802
1532
  if (why !== null) {
803
- gaps.push({ task: s.task, kind: "not-green", detail: why });
1533
+ gap("not-green", why);
804
1534
  if (!outputs.some((o) => o.test === t.test))
805
1535
  outputs.push({ test: t.test, tail: green.tail });
806
1536
  }
807
1537
  }
808
1538
  }
809
- writeAuditReport(log, { enforced: true, plan, rows, gaps, diffs, outputs });
810
- ctx.emit({ enforced: true, plan, gaps, log: logArg });
1539
+ gaps.push(
1540
+ ...deleteGaps(
1541
+ top,
1542
+ repoRel(top, ctx.cwd, plan!),
1543
+ parsed.tasks.filter((t) => group === undefined || t.group === group),
1544
+ parsed.tasks,
1545
+ ),
1546
+ );
1547
+ for (const e of parsed.errors)
1548
+ gaps.push({
1549
+ task: null,
1550
+ kind: "test-first-unread",
1551
+ detail: `\`${plan}:${e.line}\` ${e.message} — tests there were not audited; the plan's blocks need fixing`,
1552
+ });
1553
+ const testOrderOnly = gaps.length > 0 && gaps.every((g) => TEST_ORDER_GAPS.has(g.kind));
1554
+ writeAuditReport(log, {
1555
+ enforced: true,
1556
+ plan,
1557
+ rows,
1558
+ gaps,
1559
+ testOrderOnly,
1560
+ exceptions,
1561
+ lateUnchecked: [...lateUnchecked].sort((a, b) => a - b),
1562
+ diffs,
1563
+ outputs,
1564
+ });
1565
+ ctx.emit({
1566
+ enforced: true,
1567
+ plan,
1568
+ gaps,
1569
+ testOrderOnly,
1570
+ lateRedUnchecked: [...lateUnchecked].sort((a, b) => a - b),
1571
+ log: logArg,
1572
+ });
811
1573
  ctx.log(`test-first audit: ${gaps.length} gap(s) — report in ${logArg}`);
812
1574
  return gaps.length === 0 ? EXIT.OK : EXIT.NO;
813
1575
  },
814
1576
  },
1577
+ "plan-check": {
1578
+ 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, and that each READ / UPDATE / DELETE file and symbol exists; exit 0 no problems, 1 refused.`,
1579
+ flags: [
1580
+ {
1581
+ name: "plan",
1582
+ type: "string",
1583
+ required: true,
1584
+ help: "the plan file checked",
1585
+ },
1586
+ {
1587
+ name: "existence",
1588
+ type: "string",
1589
+ help: "refuse (default): a missing READ / UPDATE / DELETE file or symbol refuses the plan; report: it is listed only",
1590
+ },
1591
+ {
1592
+ name: "log",
1593
+ type: "string",
1594
+ required: true,
1595
+ help: "file the report is written to, `Problems:` header first (directories are created)",
1596
+ },
1597
+ ],
1598
+ output: {
1599
+ plan: "the plan file checked (as given)",
1600
+ groups:
1601
+ "[{group, title, tasks, tests, kb}]: each group's tasks, planned TEST FIRST tests and size",
1602
+ tasks: "[{task, group, tests, files}]: each task's planned tests and distinct test files",
1603
+ problems:
1604
+ "[{line, kind, message}]: format | stray | field | depends | cap | inventory | markers — each refuses the plan",
1605
+ existence:
1606
+ "[{line, task, message}]: READ / UPDATE / DELETE files or symbols not found; refuses only with --existence=refuse",
1607
+ log: "where the report was written (as given)",
1608
+ },
1609
+ run: (ctx) => {
1610
+ const logArg = String(ctx.flags.log);
1611
+ if (logArg === "") throw new CommandError(EXIT.USAGE, "--log must be non-empty");
1612
+ const existenceArg = str(ctx.flags.existence) ?? "refuse";
1613
+ if (existenceArg !== "refuse" && existenceArg !== "report")
1614
+ throw new CommandError(
1615
+ EXIT.USAGE,
1616
+ `--existence must be refuse or report, got "${existenceArg}"`,
1617
+ );
1618
+ const plan = String(ctx.flags.plan);
1619
+ const planAbs = path.resolve(ctx.cwd, plan);
1620
+ if (!fs.statSync(planAbs, { throwIfNoEntry: false })?.isFile())
1621
+ throw new CommandError(EXIT.USAGE, `--plan ${plan} does not exist`);
1622
+ const text = fs.readFileSync(planAbs, "utf-8");
1623
+ const caps = planCaps(ctx.cwd);
1624
+ const { groups, sizes, problems } = checkPlanText(text, caps);
1625
+ const existence = planExistence(text, toplevel(ctx.cwd));
1626
+ const refused = problems.length > 0 || (existenceArg === "refuse" && existence.length > 0);
1627
+
1628
+ const out = [
1629
+ `Problems: ${problems.length}`,
1630
+ `Existence: ${existence.length}`,
1631
+ "",
1632
+ "<!-- verdict:end -->",
1633
+ "",
1634
+ "# Plan Check",
1635
+ "",
1636
+ `Plan: \`${plan}\`. Caps: ${capsText(caps)}.`,
1637
+ "",
1638
+ "## Groups",
1639
+ "",
1640
+ ];
1641
+ if (groups.length === 0) out.push("No group blocks read.");
1642
+ else {
1643
+ out.push(
1644
+ "| Group | Title | Tasks | TEST FIRST tests | KB |",
1645
+ "| --- | --- | --- | --- | --- |",
1646
+ );
1647
+ for (const g of groups)
1648
+ out.push(`| ${g.group} | ${g.title} | ${g.tasks} | ${g.tests} | ${g.kb.toFixed(1)} |`);
1649
+ }
1650
+ if (sizes.length > 0) {
1651
+ out.push(
1652
+ "",
1653
+ "## Tasks",
1654
+ "",
1655
+ "| Task | Group | Tests | Test files |",
1656
+ "| --- | --- | --- | --- |",
1657
+ );
1658
+ for (const t of sizes) out.push(`| ${t.task} | ${t.group} | ${t.tests} | ${t.files} |`);
1659
+ }
1660
+ out.push("", "## Problems", "");
1661
+ if (problems.length === 0) out.push("None.");
1662
+ for (const p of problems) out.push(`- \`${plan}:${p.line}\` \`${p.kind}\` — ${p.message}`);
1663
+ out.push(
1664
+ "",
1665
+ `## Existence (${existenceArg === "refuse" ? "refuses the plan" : "reported only"})`,
1666
+ "",
1667
+ );
1668
+ if (existence.length === 0) out.push("None.");
1669
+ for (const e of existence) out.push(`- \`${plan}:${e.line}\` — ${e.message}`);
1670
+ const log = path.resolve(ctx.cwd, logArg);
1671
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1672
+ fs.writeFileSync(log, `${out.join("\n")}\n`);
1673
+ ctx.emit({ plan, groups, tasks: sizes, problems, existence, log: logArg });
1674
+ ctx.log(
1675
+ `plan check: ${problems.length} problem(s), ${existence.length} existence finding(s)${refused ? " — refused" : ""}; report in ${logArg}`,
1676
+ );
1677
+ return refused ? EXIT.NO : EXIT.OK;
1678
+ },
1679
+ },
815
1680
  },
816
1681
  };