@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
@@ -24,10 +24,11 @@ import * as fs from "node:fs";
24
24
  import * as path from "node:path";
25
25
  import { appendLine, statusTimestamp } from "../../ledgers/status.js";
26
26
  import { CommandError, DEV, EXIT, git, runGit } from "../lib.js";
27
- import { DIFF_BASE, EXIT_BASE, diffNumstat } from "./context.js";
28
- import { parseDecisionItems } from "./decisions.js";
27
+ import { EXIT_BASE, diffNumstat } from "./context.js";
28
+ import { defaultRange } from "./feature-base.js";
29
+ import { parseDecisionItems } from "./open-decision.js";
29
30
  import { EXIT_ROW_REFUSED, EXIT_STAGE, appendLedgerRows } from "./ledgers.js";
30
- import { derivedTestMatrix, parsePlanBlocks } from "./plan-blocks.js";
31
+ import { derivedTestMatrix, parsePlanBlocks, testTier } from "./plan-blocks.js";
31
32
  import { readBkitConfig } from "../../shared/settings.js";
32
33
  import { grantCount } from "./counters.js";
33
34
  import { checkPlanText, planCaps, readTestFirst } from "./tests.js";
@@ -211,12 +212,62 @@ const taskBlock = (n, f, round) => [
211
212
  ...f.tests.map((e) => ` - ${e}`),
212
213
  `<!-- bkit:task ${n} end -->`,
213
214
  ];
214
- /** The test tier `docs/testing.md` records for a test file's name. */
215
- const testTier = (file) => /\.integration\.test\./.test(file)
216
- ? "Integration"
217
- : /\.live\.test\./.test(file)
218
- ? "@live (golden)"
219
- : "Unit";
215
+ /**
216
+ * Findings given as structured data (a step result file), checked by the rules
217
+ * {@link parseFindings} applies to a written report. Severity, fixable, location and
218
+ * done-when are the reviewer's judgments: a missing one is refused, never defaulted.
219
+ * Throws a CommandError (EXIT_OLD_FORMAT) naming the finding and field.
220
+ */
221
+ export function structuredFindings(input, cwd) {
222
+ if (!Array.isArray(input))
223
+ throw new CommandError(EXIT_OLD_FORMAT, "findings must be an array");
224
+ return input.map((raw, i) => {
225
+ const refuse = (why) => new CommandError(EXIT_OLD_FORMAT, `finding ${i + 1} ${why}`);
226
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw))
227
+ throw refuse("is not an object");
228
+ const f = raw;
229
+ if (!SEVERITY_ORDER.includes(f["severity"]))
230
+ throw refuse("has no severity CRITICAL|HIGH|MEDIUM|LOW");
231
+ if (typeof f["fixable"] !== "boolean")
232
+ throw refuse("has no fixable true|false");
233
+ const location = normalizeLocation(typeof f["location"] === "string" ? f["location"] : "", cwd);
234
+ if (location === null)
235
+ throw refuse("has no location path:line");
236
+ if (typeof f["doneWhen"] !== "string" || f["doneWhen"].trim() === "")
237
+ throw refuse("has no doneWhen");
238
+ const tests = f["tests"] ?? [];
239
+ if (!Array.isArray(tests) || tests.some((t) => typeof t !== "string"))
240
+ throw refuse("has tests that are not an array of strings");
241
+ if (f["cls"] !== undefined && typeof f["cls"] !== "string")
242
+ throw refuse("has a non-text cls");
243
+ // Each value renders into one line of the task block: a line break would forge plan lines.
244
+ const lineBreak = /[\r\n]/;
245
+ for (const field of ["title", "cls", "doneWhen"]) {
246
+ const v = f[field];
247
+ if (typeof v === "string" && lineBreak.test(v))
248
+ throw refuse(`has a ${field} that must be a single line`);
249
+ }
250
+ const brokenTest = tests.findIndex((t) => lineBreak.test(t));
251
+ if (brokenTest !== -1)
252
+ throw refuse(`has tests entry ${brokenTest + 1} that must be a single line`);
253
+ const title = typeof f["title"] === "string" && f["title"] !== "" ? f["title"] : "";
254
+ return {
255
+ severity: f["severity"],
256
+ ...(typeof f["cls"] === "string" && f["cls"] !== "" ? { cls: f["cls"] } : {}),
257
+ fixable: f["fixable"],
258
+ location,
259
+ title: title || `Challenge finding at ${location}`,
260
+ doneWhen: f["doneWhen"],
261
+ tests: tests,
262
+ };
263
+ });
264
+ }
265
+ /** The `## Findings Log` section for `findings`, in the task-block form {@link parseFindings} reads. */
266
+ export function renderFindingsLog(findings, round = 1) {
267
+ return ["## Findings Log", "", ...findings.flatMap((f, i) => [...taskBlock(i + 1, f, round), ""])]
268
+ .join("\n")
269
+ .replace(/\n+$/, "");
270
+ }
220
271
  /**
221
272
  * One `Derived Test Matrix` row per test a finding task appends: the test's own name and
222
273
  * file from its `TEST FIRST` entry, its tier from the file's name, and the task number.
@@ -405,7 +456,7 @@ export const challengeCommand = {
405
456
  {
406
457
  name: "base",
407
458
  type: "string",
408
- help: `merge base (default ${DIFF_BASE}, fetched first; a failed fetch is logged, not fatal)`,
459
+ help: "merge base (default: the feature base, after fetching origin dev; a failed fetch is logged, not fatal)",
409
460
  },
410
461
  ],
411
462
  output: {
@@ -418,15 +469,17 @@ export const challengeCommand = {
418
469
  },
419
470
  exitCodes: { [EXIT_BASE]: "--base does not name a commit" },
420
471
  run: (ctx) => {
421
- const base = typeof ctx.flags.base === "string" ? ctx.flags.base : DIFF_BASE;
422
- if (base === DIFF_BASE) {
472
+ const explicitBase = typeof ctx.flags.base === "string" ? ctx.flags.base : undefined;
473
+ if (explicitBase === undefined) {
423
474
  const res = runGit(ctx.cwd, ["fetch", "origin", DEV]);
424
475
  if (!res.ok)
425
476
  ctx.log(`git fetch origin dev failed — measuring against the last fetch: ${res.stderr}`);
426
477
  }
478
+ const fallback = explicitBase === undefined ? defaultRange(ctx.cwd, ctx.log) : null;
479
+ const base = explicitBase ?? fallback.base;
427
480
  if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null)
428
481
  throw new CommandError(EXIT_BASE, `--base ${base} does not name a commit (fetch origin)`);
429
- const range = `${base}...HEAD`;
482
+ const range = fallback?.range ?? `${base}...HEAD`;
430
483
  const { stat } = diffNumstat(ctx.cwd, range);
431
484
  const gate = challengeGate(stat);
432
485
  const file = path.resolve(ctx.cwd, String(ctx.flags.file));
@@ -35,12 +35,15 @@ import { CommandError, EXIT, git, outboxRel, outboxRoot, } from "../lib.js";
35
35
  import { gitEnv, resolveRepoSlug } from "../../ledgers/telemetry.js";
36
36
  import { parseJson } from "../../shared/json.js";
37
37
  import { checkedTable } from "../../shared/text.js";
38
+ import { defaultRange } from "./feature-base.js";
39
+ export { defaultRange, featureBase } from "./feature-base.js";
38
40
  import { buildComment } from "./issues.js";
39
41
  import { derivedTestMatrix, parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
40
42
  import { COMMENT_FILE_OUTPUT, commentFileOf } from "./tracker.js";
41
43
  import { EXIT_NO_STATUS, FILE_FLAG, positiveInt, readRuns, str } from "./status.js";
42
44
  import { EXIT_COMMIT, writeStepRow } from "./steps.js";
43
- import { RED_PROVEN, doneTasks, redEntries, redKey, testSpan } from "./tests.js";
45
+ import { activeRunStart } from "./counters.js";
46
+ import { RED_PROVEN, doneTasks, planTakeovers, redEntries, redKey, testBlock, testSpan, } from "./tests.js";
44
47
  /** Exit code: the artifact to clamp is missing, unreadable, or could not be replaced. */
45
48
  export const EXIT_ARTIFACT = 4;
46
49
  // ---------------------------------------------------------------------------
@@ -683,7 +686,6 @@ function asCaptured(out) {
683
686
  // ---------------------------------------------------------------------------
684
687
  /** Exit code: --base does not name a commit. */
685
688
  export const EXIT_BASE = 5;
686
- export const DIFF_BASE = "origin/dev";
687
689
  export const DIFF_EXCLUDES = ["docs/plans/**"];
688
690
  export const PARTIAL_MARK = "partial diff coverage";
689
691
  export const DIFF_GUARD = {
@@ -939,6 +941,25 @@ export function existingPlannedTests(top, open) {
939
941
  }
940
942
  return out;
941
943
  }
944
+ /**
945
+ * The group's takeovers split by the run start: a taken-over test whose block the run-start
946
+ * commit `runStart` already held stays in `existing` (add-only); every other one leaves
947
+ * `existing` and is `takenOver`, which the tests step may rewrite. With no run start, no
948
+ * takeover counts as pre-run.
949
+ */
950
+ export function splitTakeovers(top, existing, takeovers, runStart) {
951
+ const atStart = (k) => {
952
+ if (runStart === undefined)
953
+ return false;
954
+ return testBlock(git(top, ["show", `${runStart}:${k.test}`]), k.name) !== null;
955
+ };
956
+ const takenOver = takeovers.filter((k) => !atStart(k));
957
+ const moved = new Set(takenOver.map((k) => redKey(k.task, k.test, k.name)));
958
+ return {
959
+ existing: existing.filter((e) => !moved.has(redKey(e.task, e.test, e.name))),
960
+ takenOver,
961
+ };
962
+ }
942
963
  /** The brief's text and its work section's size in bytes. */
943
964
  export function briefText(o) {
944
965
  const lines = o.plan.split("\n");
@@ -999,6 +1020,13 @@ export function briefText(o) {
999
1020
  work.push(`- TASK ${e.task} \`${e.test}\` \`${e.name}\` — exists at \`${e.test}:${e.line}\`; update that test in place: add expectations, never remove or loosen one`);
1000
1021
  work.push("");
1001
1022
  }
1023
+ const takenOver = (o.takenOver ?? []).filter((k) => open.some((t) => t.task === k.task));
1024
+ if (takenOver.length > 0) {
1025
+ work.push("### Planned tests taken over from earlier tasks", "");
1026
+ for (const k of takenOver)
1027
+ work.push(`- TASK ${k.task} \`${k.test}\` \`${k.name}\` — taken over from TASK ${k.from}; rewrite that test case so it fails until this task's code exists`);
1028
+ work.push("");
1029
+ }
1002
1030
  }
1003
1031
  else
1004
1032
  work.push(...planEntries(lines, open, work, o.planFile));
@@ -1214,7 +1242,7 @@ export const contextCommand = {
1214
1242
  {
1215
1243
  name: "base",
1216
1244
  type: "string",
1217
- help: `merge base or a group's start commit (default ${DIFF_BASE})`,
1245
+ help: "merge base or a group's start commit (default: the feature base, where the branch's own work starts)",
1218
1246
  },
1219
1247
  ...LOG_FLAGS,
1220
1248
  {
@@ -1242,7 +1270,9 @@ export const contextCommand = {
1242
1270
  [EXIT_ARTIFACT]: "the artifact could not be written",
1243
1271
  },
1244
1272
  run: (ctx) => {
1245
- const base = str(ctx.flags.base) ?? DIFF_BASE;
1273
+ const explicitBase = str(ctx.flags.base);
1274
+ const fallback = explicitBase === undefined ? defaultRange(ctx.cwd, ctx.log) : null;
1275
+ const base = explicitBase ?? fallback.base;
1246
1276
  if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null) {
1247
1277
  throw new CommandError(EXIT_BASE, `--base ${base} does not name a commit (fetch origin, or pass the group's start sha)`);
1248
1278
  }
@@ -1254,7 +1284,7 @@ export const contextCommand = {
1254
1284
  fs.mkdirSync(path.dirname(log), { recursive: true });
1255
1285
  fs.writeFileSync(log, "");
1256
1286
  }
1257
- const written = tryWriteDiffArtifact(ctx.cwd, path.resolve(ctx.cwd, artifact), artifact, `${base}...HEAD`, DIFF_GUARD, { rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)) });
1287
+ const written = tryWriteDiffArtifact(ctx.cwd, path.resolve(ctx.cwd, artifact), artifact, fallback?.range ?? `${base}...HEAD`, DIFF_GUARD, { rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)) });
1258
1288
  if (!written.ok)
1259
1289
  throw new CommandError(EXIT_ARTIFACT, `${artifact}: ${written.error}`);
1260
1290
  const result = written.result;
@@ -1277,7 +1307,7 @@ export const contextCommand = {
1277
1307
  },
1278
1308
  },
1279
1309
  brief: {
1280
- summary: "Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes; --tests-only writes the tests step's brief as build-brief-tests-{group}-{n}.md, with the Derived Test Matrix rows for the group's tests in place of the inventory and architecture entries.",
1310
+ summary: "Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes; --tests-only writes the tests step's brief as build-brief-tests-{group}-{n}.md, with the Derived Test Matrix rows for the group's tests in place of the inventory and architecture entries, and the tests the group takes over from earlier tasks under their own section.",
1281
1311
  use: "workflow",
1282
1312
  flags: [
1283
1313
  { name: "plan", type: "string", required: true, help: "the plan file" },
@@ -1381,6 +1411,13 @@ export const contextCommand = {
1381
1411
  const noteFile = noteFlag === undefined ? undefined : path.resolve(ctx.cwd, noteFlag);
1382
1412
  if (noteFile !== undefined && !fs.existsSync(noteFile))
1383
1413
  throw new CommandError(EXIT_ARTIFACT, `${noteFlag} does not exist`);
1414
+ const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1415
+ const runStart = statusArg === undefined
1416
+ ? undefined
1417
+ : activeRunStart(path.resolve(ctx.cwd, statusArg), "build")?.parentSha;
1418
+ const split = testsOnly
1419
+ ? splitTakeovers(top, existingPlannedTests(top, open), planTakeovers(plan).filter((k) => open.some((t) => t.task === k.task)), typeof runStart === "string" ? runStart : undefined)
1420
+ : undefined;
1384
1421
  const { text, workBytes } = briefText({
1385
1422
  plan,
1386
1423
  planFile: String(ctx.flags.plan),
@@ -1388,9 +1425,8 @@ export const contextCommand = {
1388
1425
  groups: blocks.groups,
1389
1426
  isDone: (t) => isDone(t) || (group.tasks.includes(t) && !open.includes(t)),
1390
1427
  testsOnly,
1391
- existing: testsOnly
1392
- ? existingPlannedTests(git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd, open)
1393
- : undefined,
1428
+ existing: split?.existing,
1429
+ takenOver: split?.takenOver,
1394
1430
  note: noteFile === undefined ? undefined : fs.readFileSync(noteFile, "utf-8"),
1395
1431
  });
1396
1432
  const out = nextBriefPath(dir, group.group, testsOnly ? "build-brief-tests" : undefined);
@@ -1613,7 +1649,7 @@ export const contextCommand = {
1613
1649
  commit: written.commit,
1614
1650
  ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
1615
1651
  comment,
1616
- commentFile: commentFileOf(ctx.cwd, comment),
1652
+ commentFile: commentFileOf(ctx.cwd, comment, ctx),
1617
1653
  });
1618
1654
  return written.code;
1619
1655
  },
@@ -10,11 +10,15 @@
10
10
  // 0 is a legal answer (that step simply has not run).
11
11
  import * as fs from "node:fs";
12
12
  import * as path from "node:path";
13
- import { activeDoneSteps, allRunsDoneSteps, appendLine, lastDoneStepAllRuns, nextStrategy, runNumber, statusTimestamp, } from "../../ledgers/status.js";
13
+ import { activeDoneSteps, activeDoneStepsSinceClean, allRunsDoneSteps, appendLine, cleanRound, CORRECTION_CANDIDATE_ROW, lastDoneStepAllRuns, repeatStrategy, runNumber, statusTimestamp, } from "../../ledgers/status.js";
14
14
  import { ASK_POINTS, readBkitConfig, } from "../../shared/settings.js";
15
+ import { oneLine } from "../../shared/text.js";
16
+ import { fixTestStep, gatedCheckStep } from "./loops.js";
15
17
  import { headlessRun } from "./runtime.js";
16
- import { CommandError, EXIT, git, runGit, } from "../lib.js";
18
+ import { CommandError, EXIT, git, runGit, wholeNumber, } from "../lib.js";
17
19
  import { EXIT_NO_STATUS, FILE_FLAG, GROUP_FLAG, STEP_FLAG, WORKFLOW_FLAG, positiveInt, readRuns, readStatusRows, statusFile, str, } from "./status.js";
20
+ /** A round's free-text scope for the owner's loop question: one line, so it cannot add lines to it. */
21
+ const scopeText = (scope) => typeof scope === "string" && oneLine(scope) !== "" ? oneLine(scope, 120) : "unscoped";
18
22
  /** An ask point by name (`build.verify`); an unknown name is a usage error. */
19
23
  export function askPoint(name) {
20
24
  if (!ASK_POINTS.includes(name))
@@ -105,6 +109,55 @@ function typedRowCount(file, workflow, type) {
105
109
  .slice(start + 1)
106
110
  .filter((r) => r.type === type && (r.workflow === undefined || r.workflow === workflow)).length;
107
111
  }
112
+ /** Corrected retries a rejected sub-step gets unless its route names a stricter limit. */
113
+ export const CORRECTION_LIMIT = 2;
114
+ /**
115
+ * Spend one corrected retry of `scope` for `operation` in `workflow`'s active run. The budget is
116
+ * per scope and survives tools, helpers, resumes and any other counter call; a new operation id
117
+ * gains nothing, and asking again for a counted one spends nothing. `extra` joins the row.
118
+ */
119
+ export function spendCorrection(file, workflow, scope, operation, limit, extra = {}) {
120
+ const rows = readStatusRows(file);
121
+ let start = -1;
122
+ rows.forEach((r, i) => {
123
+ if (r.type === "workflow-started" && r.workflow === workflow)
124
+ start = i;
125
+ });
126
+ const counted = rows
127
+ .slice(start + 1)
128
+ .filter((r) => r.type === CORRECTION_CANDIDATE_ROW && r.workflow === workflow && r.scope === scope);
129
+ const spent = new Set(counted.map((r) => String(r.operation)));
130
+ const asked = typeof extra.requestHash === "string" ? extra.requestHash : undefined;
131
+ const verdict = (allowed, replayed) => ({
132
+ allowed,
133
+ used: spent.size,
134
+ limit,
135
+ remaining: Math.max(0, limit - spent.size),
136
+ replayed,
137
+ });
138
+ if (spent.has(operation)) {
139
+ // A known id is a free replay only for the request it was counted for.
140
+ const hashes = counted
141
+ .filter((r) => String(r.operation) === operation)
142
+ .map((r) => r.requestHash)
143
+ .filter((h) => typeof h === "string");
144
+ if (asked !== undefined && hashes.length > 0 && !hashes.includes(asked))
145
+ return { ...verdict(false, false), conflict: true };
146
+ return verdict(true, true);
147
+ }
148
+ if (spent.size >= limit)
149
+ return verdict(false, false);
150
+ fs.appendFileSync(file, appendLine({
151
+ type: CORRECTION_CANDIDATE_ROW,
152
+ workflow,
153
+ at: statusTimestamp(),
154
+ scope,
155
+ operation,
156
+ ...extra,
157
+ }));
158
+ spent.add(operation);
159
+ return verdict(true, false);
160
+ }
108
161
  /** The row `counters grant` writes: the owner gave one loop one more full allowance. */
109
162
  export const ALLOWANCE_ROW = "allowance-granted";
110
163
  /**
@@ -152,7 +205,8 @@ function checkoutOf(file, cwd) {
152
205
  }
153
206
  /**
154
207
  * The loop's direction from its check rounds: `worse` when the problem count rose,
155
- * `closing` when it fell and the rounds changed code, `stuck` otherwise.
208
+ * `closing` when it fell and the rounds changed code, `stuck` otherwise, and `unknown` when
209
+ * the first or last round recorded no count.
156
210
  */
157
211
  export function loopTrend(rounds, codeChanged) {
158
212
  if (rounds.length < 2)
@@ -160,20 +214,69 @@ export function loopTrend(rounds, codeChanged) {
160
214
  const first = rounds[0]?.failures;
161
215
  const last = rounds.at(-1)?.failures;
162
216
  if (first === undefined || last === undefined)
163
- return "stuck";
217
+ return "unknown";
164
218
  if (last > first)
165
219
  return "worse";
166
220
  if (last < first && codeChanged !== false)
167
221
  return "closing";
168
222
  return "stuck";
169
223
  }
170
- /** A fix loop's progress in the active run: `check` counts problems, `fix` fixes them. */
171
- export function loopProgress(file, cwd, workflow, check, fix, group) {
224
+ /**
225
+ * The failing tests of the latest `test-run` row for `step` and `attempt` in `workflow`'s
226
+ * active run: 0 with no row, null when unknown (no count, or red with 0 counted failures).
227
+ */
228
+ function gateFailuresOf(file, workflow, step, attempt) {
229
+ const rows = readStatusRows(file);
230
+ let start = -1;
231
+ rows.forEach((r, i) => {
232
+ if (r.type === "workflow-started" && r.workflow === workflow)
233
+ start = i;
234
+ });
235
+ const row = rows
236
+ .slice(start + 1)
237
+ .filter((r) => r.type === "test-run" &&
238
+ (r.workflow === undefined || r.workflow === workflow) &&
239
+ r.step === step &&
240
+ r.attempt === attempt)
241
+ .at(-1);
242
+ if (row === undefined)
243
+ return 0;
244
+ const failures = row.failures;
245
+ if (typeof failures !== "number")
246
+ return null;
247
+ if (row.verdict === "FAIL" && failures === 0)
248
+ return null;
249
+ return failures;
250
+ }
251
+ /**
252
+ * A fix loop's progress in the active run: `check` counts problems, `fix` fixes them. With
253
+ * `sinceClean`, only the rounds after `check`'s last clean round: a loop that reopens. With
254
+ * `gate` (a step prefix, e.g. `build-group-gate`), each round also counts the failing tests
255
+ * of the latest same-attempt test-run row of `{gate}-{group}`, or of `{gate}` with no group:
256
+ * 0 with no row, and unknown (null) when that row's count is null or the row is red with 0
257
+ * counted failures. A round is clean only when its gate also counted 0.
258
+ */
259
+ export function loopProgress(file, cwd, workflow, check, fix, group, sinceClean = false, gate) {
172
260
  const runs = readRuns(file);
173
- const rounds = activeDoneSteps(runs, workflow, { step: check, group });
174
- const fixes = activeDoneSteps(runs, workflow, { step: fix, group });
175
- const first = rounds[0];
261
+ const gateStep = gate === undefined || group === undefined ? gate : `${gate}-${group}`;
262
+ const gateOf = (r) => gateStep === undefined ? undefined : gateFailuresOf(file, workflow, gateStep, r.attempt);
263
+ const clean = (r) => cleanRound(r) && (gateStep === undefined || gateOf(r) === 0);
264
+ const done = (step) => sinceClean
265
+ ? activeDoneStepsSinceClean(runs, workflow, { step, group }, check, clean)
266
+ : activeDoneSteps(runs, workflow, { step, group });
267
+ const checked = done(check);
268
+ const gateFailures = checked.map(gateOf);
269
+ const rounds = checked.map((r, i) => {
270
+ const g = gateFailures[i];
271
+ if (g === undefined)
272
+ return r;
273
+ const failures = g === null || r.failures === undefined ? undefined : r.failures + g;
274
+ return { ...r, failures };
275
+ });
276
+ const fixes = done(fix);
176
277
  const last = rounds.at(-1);
278
+ // Only rounds that ran the same tests are compared: the earliest round with the last round's scope.
279
+ const first = last === undefined ? undefined : rounds.find((r) => r.scope === last.scope);
177
280
  let codeChanged = null;
178
281
  if (first && last && first !== last && first.parentSha && last.parentSha) {
179
282
  const diff = runGit(checkoutOf(file, cwd), [
@@ -190,25 +293,75 @@ export function loopProgress(file, cwd, workflow, check, fix, group) {
190
293
  else if (diff.stderr === "")
191
294
  codeChanged = true;
192
295
  }
193
- const ladder = lastDoneStepAllRuns(runs, workflow, { step: fix, group })?.strategy;
194
- const trend = loopTrend(rounds, codeChanged);
195
- const span = first && last && rounds.length > 1
196
- ? (Date.parse(last.at) - Date.parse(first.at)) / 60000 / (rounds.length - 1)
296
+ const prior = lastDoneStepAllRuns(runs, workflow, { step: fix, group })?.strategy;
297
+ // The same label `status route` gives the fix step: from the tests failing now.
298
+ const testStep = fixTestStep(fix, group);
299
+ const gated = gatedCheckStep(fix);
300
+ const current = gated === undefined
301
+ ? undefined
302
+ : activeDoneSteps(runs, workflow, { step: gated, group }).length;
303
+ const next = testStep === undefined
304
+ ? "STANDARD"
305
+ : repeatStrategy(readStatusRows(file), workflow, testStep, current).strategy;
306
+ const sameScope = first !== undefined && last !== undefined && first !== last;
307
+ const differentScopes = rounds.length >= 2 && !sameScope;
308
+ const trend = rounds.length < 2
309
+ ? "first-round"
310
+ : differentScopes
311
+ ? "unknown"
312
+ : loopTrend([first, last], codeChanged);
313
+ const countOf = (r) => (r?.failures === undefined ? "?" : String(r.failures));
314
+ const pairCounts = `${countOf(first)} → ${countOf(last)}`;
315
+ const firstFailures = first?.failures;
316
+ const lastFailures = last?.failures;
317
+ let trendLine;
318
+ if (trend === "first-round")
319
+ trendLine = "This was the first round, so there is no trend yet.";
320
+ else if (differentScopes)
321
+ trendLine = `The rounds ran different tests (${scopeText(rounds[0]?.scope)}, then ${scopeText(last?.scope)}), so their counts cannot be compared.`;
322
+ else if (trend === "unknown")
323
+ trendLine = `A round recorded no count (${rounds.map(countOf).join(" → ")}), so progress cannot be judged.`;
324
+ else if (trend === "closing")
325
+ trendLine = `The count fell between the first and the last round (${pairCounts}), and the code changed.`;
326
+ else if (trend === "worse")
327
+ trendLine = `The count rose between the first and the last round (${pairCounts}).`;
328
+ else if (firstFailures !== undefined &&
329
+ lastFailures !== undefined &&
330
+ lastFailures < firstFailures)
331
+ trendLine = `The count fell (${pairCounts}), but no source code changed between the rounds.`;
332
+ else
333
+ trendLine = `The count did not fall between the first and the last round (${pairCounts}).`;
334
+ const span = rounds[0] && last && rounds.length > 1
335
+ ? (Date.parse(last.at) - Date.parse(rounds[0].at)) / 60000 / (rounds.length - 1)
197
336
  : null;
198
337
  return {
199
- rounds: rounds.map((r) => ({
338
+ rounds: rounds.map((r, i) => ({
200
339
  attempt: r.attempt ?? null,
201
340
  failures: r.failures ?? null,
341
+ ...(gateFailures[i] === undefined ? {} : { gateFailures: gateFailures[i] }),
342
+ scope: r.scope ?? null,
202
343
  at: r.at,
203
344
  })),
204
345
  counts: rounds.map((r) => (r.failures === undefined ? "?" : String(r.failures))).join(" → "),
346
+ ...(gateStep === undefined
347
+ ? {}
348
+ : {
349
+ gateCounts: gateFailures
350
+ .map((g) => (g === null || g === undefined ? "?" : String(g)))
351
+ .join(" → "),
352
+ }),
205
353
  codeChanged,
206
354
  lastStrategy: fixes.at(-1)?.strategy ?? null,
207
- nextStrategy: nextStrategy(ladder),
208
- finalSpent: fixes.some((r) => r.strategy === "FINAL") || ladder === "FINAL",
355
+ nextStrategy: next,
356
+ finalSpent: fixes.some((r) => r.strategy === "FINAL") || prior === "FINAL",
209
357
  minutesPerRound: span === null || Number.isNaN(span) ? null : Math.round(span),
210
358
  trend,
211
- recommend: trend === "first-round" ? null : trend === "closing" ? "try-again" : "stop",
359
+ trendLine,
360
+ recommend: trend === "first-round" || trend === "unknown"
361
+ ? null
362
+ : trend === "closing"
363
+ ? "try-again"
364
+ : "stop",
212
365
  };
213
366
  }
214
367
  /**
@@ -431,6 +584,54 @@ export const countersCommand = {
431
584
  return EXIT.OK;
432
585
  },
433
586
  },
587
+ correction: {
588
+ summary: "Spend one corrected retry of a rejected sub-step: exit 0 allowed (or a replay of a counted operation), exit 1 the scope's budget is used up. The budget is two per scope in the active run unless a stricter --limit names one.",
589
+ use: "workflow",
590
+ flags: [
591
+ FILE_FLAG,
592
+ WORKFLOW_FLAG,
593
+ {
594
+ name: "scope",
595
+ type: "string",
596
+ required: true,
597
+ help: "the engine-derived correction scope",
598
+ },
599
+ {
600
+ name: "operation",
601
+ type: "string",
602
+ required: true,
603
+ help: "the corrected candidate's fresh operation id",
604
+ },
605
+ {
606
+ name: "request-hash",
607
+ type: "string",
608
+ help: "the candidate's canonical request hash: a known operation replays free only for the same hash, and a different one is refused",
609
+ },
610
+ {
611
+ name: "limit",
612
+ type: "string",
613
+ help: `corrected retries this route allows (default ${CORRECTION_LIMIT}); a smaller one wins`,
614
+ },
615
+ ],
616
+ output: {
617
+ allowed: "true when the correction may run",
618
+ used: "operations counted in this scope",
619
+ limit: "retries this route allows",
620
+ remaining: "retries left",
621
+ replayed: "true when the operation was already counted: nothing was spent",
622
+ },
623
+ exitCodes: { [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON" },
624
+ run: (ctx) => {
625
+ const file = statusFile(ctx);
626
+ if (!fs.existsSync(file))
627
+ throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
628
+ const spend = spendCorrection(file, String(ctx.flags.workflow), String(ctx.flags.scope), String(ctx.flags.operation), wholeNumber(ctx.flags.limit, "limit", CORRECTION_LIMIT), str(ctx.flags.requestHash) === undefined
629
+ ? {}
630
+ : { requestHash: str(ctx.flags.requestHash) });
631
+ ctx.emit({ ...spend });
632
+ return spend.allowed ? EXIT.OK : EXIT.NO;
633
+ },
634
+ },
434
635
  max: {
435
636
  summary: "The ask points' limits and ask settings: one by --point, or all.",
436
637
  use: "workflow",
@@ -482,22 +683,29 @@ export const countersCommand = {
482
683
  help: "the step that fixes them, e.g. build-plan-gaps-remediate",
483
684
  },
484
685
  GROUP_FLAG,
686
+ {
687
+ name: "since-clean",
688
+ type: "boolean",
689
+ help: "only the rounds after --check's last clean round (PASS, or CONCERNS with 0 failures)",
690
+ },
485
691
  ],
486
692
  output: {
487
- rounds: "the check rounds counted: attempt, failures, at",
488
- counts: "problem count after each round, e.g. 5 → 2",
489
- codeChanged: "source changed between the first and last check round (null when git cannot tell)",
693
+ rounds: "the check rounds counted: attempt, failures, gateFailures, scope (what the round ran), at",
694
+ counts: "problem count after each round, e.g. 5 → 2 (with a gate, the gate's failing tests are added)",
695
+ gateCounts: "the group gate's failing tests after each round, e.g. 3 → 3 (absent without a gate)",
696
+ codeChanged: "source changed between the compared rounds, the earliest and the last that ran the same tests (same scope) (null when git cannot tell)",
490
697
  lastStrategy: "strategy of the last fix round (null when none ran)",
491
698
  nextStrategy: "strategy the next fix round would use",
492
699
  finalSpent: "true when a fix round already ran FINAL",
493
700
  minutesPerRound: "average minutes between check rounds (null under two rounds)",
494
- trend: "first-round | closing | stuck | worse",
495
- recommend: "try-again when closing, else stop (null on the first round)",
701
+ trend: "first-round | closing | stuck | worse | unknown (a missing count, or rounds of different scopes)",
702
+ trendLine: "one plain sentence on what the counts show, with the counts and the reason",
703
+ recommend: "try-again when closing, stop when stuck or worse (null on the first round or an unknown trend)",
496
704
  },
497
705
  exitCodes: { [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON" },
498
706
  run: (ctx) => {
499
707
  ctx.emit({
500
- ...loopProgress(statusFile(ctx), ctx.cwd, String(ctx.flags.workflow), String(ctx.flags.check), String(ctx.flags.fix), positiveInt(ctx.flags.group, "group")),
708
+ ...loopProgress(statusFile(ctx), ctx.cwd, String(ctx.flags.workflow), String(ctx.flags.check), String(ctx.flags.fix), positiveInt(ctx.flags.group, "group"), ctx.flags.sinceClean === true),
501
709
  });
502
710
  return EXIT.OK;
503
711
  },