@cbartens/bkit 6.1.1 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (313) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +42 -32
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -14,10 +14,13 @@ import * as path from "node:path";
14
14
 
15
15
  import {
16
16
  activeDoneSteps,
17
+ activeDoneStepsSinceClean,
17
18
  allRunsDoneSteps,
18
19
  appendLine,
20
+ cleanRound,
21
+ CORRECTION_CANDIDATE_ROW,
19
22
  lastDoneStepAllRuns,
20
- nextStrategy,
23
+ repeatStrategy,
21
24
  runNumber,
22
25
  statusTimestamp,
23
26
  type Step,
@@ -28,6 +31,8 @@ import {
28
31
  type AskPoint,
29
32
  type AskSetting,
30
33
  } from "../../shared/settings.js";
34
+ import { oneLine } from "../../shared/text.js";
35
+ import { fixTestStep, gatedCheckStep } from "./loops.js";
31
36
  import { headlessRun } from "./runtime.js";
32
37
  import {
33
38
  CommandError,
@@ -37,6 +42,7 @@ import {
37
42
  type CommandSpec,
38
43
  type FlagValue,
39
44
  type RunContext,
45
+ wholeNumber,
40
46
  } from "../lib.js";
41
47
  import {
42
48
  EXIT_NO_STATUS,
@@ -51,6 +57,10 @@ import {
51
57
  str,
52
58
  } from "./status.js";
53
59
 
60
+ /** A round's free-text scope for the owner's loop question: one line, so it cannot add lines to it. */
61
+ const scopeText = (scope: unknown): string =>
62
+ typeof scope === "string" && oneLine(scope) !== "" ? oneLine(scope, 120) : "unscoped";
63
+
54
64
  /** An ask point by name (`build.verify`); an unknown name is a usage error. */
55
65
  export function askPoint(name: string): AskPoint {
56
66
  if (!(ASK_POINTS as readonly string[]).includes(name))
@@ -104,7 +114,8 @@ function derivedOf(ctx: RunContext): number {
104
114
  throw new CommandError(EXIT.USAGE, "--of needs --file and --workflow");
105
115
  const runs = readRuns(statusFile(ctx));
106
116
  const group = positiveInt(ctx.flags.group, "group");
107
- const doneSteps = ctx.flags.allRuns === true ? allRunsDoneSteps : activeDoneSteps;
117
+ const doneSteps: typeof activeDoneSteps =
118
+ ctx.flags.allRuns === true ? allRunsDoneSteps : activeDoneSteps;
108
119
  const count = steps.reduce(
109
120
  (n, step) => n + doneSteps(runs, String(ctx.flags.workflow), { step, group }).length,
110
121
  0,
@@ -162,6 +173,78 @@ function typedRowCount(file: string, workflow: string, type: string): number {
162
173
  .filter((r) => r.type === type && (r.workflow === undefined || r.workflow === workflow)).length;
163
174
  }
164
175
 
176
+ /** Corrected retries a rejected sub-step gets unless its route names a stricter limit. */
177
+ export const CORRECTION_LIMIT = 2;
178
+
179
+ export interface CorrectionSpend {
180
+ allowed: boolean;
181
+ used: number;
182
+ limit: number;
183
+ remaining: number;
184
+ /** The operation was already counted: nothing was spent. */
185
+ replayed: boolean;
186
+ /** The operation was counted for another request: refused, nothing written. */
187
+ conflict?: boolean;
188
+ }
189
+
190
+ /**
191
+ * Spend one corrected retry of `scope` for `operation` in `workflow`'s active run. The budget is
192
+ * per scope and survives tools, helpers, resumes and any other counter call; a new operation id
193
+ * gains nothing, and asking again for a counted one spends nothing. `extra` joins the row.
194
+ */
195
+ export function spendCorrection(
196
+ file: string,
197
+ workflow: string,
198
+ scope: string,
199
+ operation: string,
200
+ limit: number,
201
+ extra: Record<string, unknown> = {},
202
+ ): CorrectionSpend {
203
+ const rows = readStatusRows(file);
204
+ let start = -1;
205
+ rows.forEach((r, i) => {
206
+ if (r.type === "workflow-started" && r.workflow === workflow) start = i;
207
+ });
208
+ const counted = rows
209
+ .slice(start + 1)
210
+ .filter(
211
+ (r) => r.type === CORRECTION_CANDIDATE_ROW && r.workflow === workflow && r.scope === scope,
212
+ );
213
+ const spent = new Set<string>(counted.map((r) => String(r.operation)));
214
+ const asked = typeof extra.requestHash === "string" ? extra.requestHash : undefined;
215
+ const verdict = (allowed: boolean, replayed: boolean): CorrectionSpend => ({
216
+ allowed,
217
+ used: spent.size,
218
+ limit,
219
+ remaining: Math.max(0, limit - spent.size),
220
+ replayed,
221
+ });
222
+ if (spent.has(operation)) {
223
+ // A known id is a free replay only for the request it was counted for.
224
+ const hashes = counted
225
+ .filter((r) => String(r.operation) === operation)
226
+ .map((r) => r.requestHash)
227
+ .filter((h): h is string => typeof h === "string");
228
+ if (asked !== undefined && hashes.length > 0 && !hashes.includes(asked))
229
+ return { ...verdict(false, false), conflict: true };
230
+ return verdict(true, true);
231
+ }
232
+ if (spent.size >= limit) return verdict(false, false);
233
+ fs.appendFileSync(
234
+ file,
235
+ appendLine({
236
+ type: CORRECTION_CANDIDATE_ROW,
237
+ workflow,
238
+ at: statusTimestamp(),
239
+ scope,
240
+ operation,
241
+ ...extra,
242
+ }),
243
+ );
244
+ spent.add(operation);
245
+ return verdict(true, false);
246
+ }
247
+
165
248
  /** The row `counters grant` writes: the owner gave one loop one more full allowance. */
166
249
  export const ALLOWANCE_ROW = "allowance-granted";
167
250
 
@@ -225,35 +308,87 @@ function checkoutOf(file: string, cwd: string): string {
225
308
  return at < 0 ? cwd : abs.slice(0, at);
226
309
  }
227
310
 
228
- export type LoopTrend = "first-round" | "closing" | "stuck" | "worse";
311
+ export type LoopTrend = "first-round" | "closing" | "stuck" | "worse" | "unknown";
229
312
 
230
313
  /**
231
314
  * The loop's direction from its check rounds: `worse` when the problem count rose,
232
- * `closing` when it fell and the rounds changed code, `stuck` otherwise.
315
+ * `closing` when it fell and the rounds changed code, `stuck` otherwise, and `unknown` when
316
+ * the first or last round recorded no count.
233
317
  */
234
318
  export function loopTrend(rounds: Step[], codeChanged: boolean | null): LoopTrend {
235
319
  if (rounds.length < 2) return "first-round";
236
320
  const first = rounds[0]?.failures;
237
321
  const last = rounds.at(-1)?.failures;
238
- if (first === undefined || last === undefined) return "stuck";
322
+ if (first === undefined || last === undefined) return "unknown";
239
323
  if (last > first) return "worse";
240
324
  if (last < first && codeChanged !== false) return "closing";
241
325
  return "stuck";
242
326
  }
243
327
 
328
+ /**
329
+ * The failing tests of the latest `test-run` row for `step` and `attempt` in `workflow`'s
330
+ * active run: 0 with no row, null when unknown (no count, or red with 0 counted failures).
331
+ */
332
+ function gateFailuresOf(
333
+ file: string,
334
+ workflow: string,
335
+ step: string,
336
+ attempt: number | undefined,
337
+ ): number | null {
338
+ const rows = readStatusRows(file);
339
+ let start = -1;
340
+ rows.forEach((r, i) => {
341
+ if (r.type === "workflow-started" && r.workflow === workflow) start = i;
342
+ });
343
+ const row = rows
344
+ .slice(start + 1)
345
+ .filter(
346
+ (r) =>
347
+ r.type === "test-run" &&
348
+ (r.workflow === undefined || r.workflow === workflow) &&
349
+ r.step === step &&
350
+ r.attempt === attempt,
351
+ )
352
+ .at(-1);
353
+ if (row === undefined) return 0;
354
+ const failures = row.failures;
355
+ if (typeof failures !== "number") return null;
356
+ if (row.verdict === "FAIL" && failures === 0) return null;
357
+ return failures;
358
+ }
359
+
244
360
  export interface LoopProgress {
245
- rounds: { attempt: number | null; failures: number | null; at: string }[];
361
+ rounds: {
362
+ attempt: number | null;
363
+ failures: number | null;
364
+ /** The gate's failing tests for this round; null when unknown. Absent with no gate. */
365
+ gateFailures?: number | null;
366
+ /** What the round ran, e.g. `ci:123`; null when the row has no scope. */
367
+ scope: string | null;
368
+ at: string;
369
+ }[];
246
370
  counts: string;
371
+ /** The gate's failing tests after each round, e.g. `3 → 3`; absent with no gate. */
372
+ gateCounts?: string;
247
373
  codeChanged: boolean | null;
248
374
  lastStrategy: string | null;
249
375
  nextStrategy: string;
250
376
  finalSpent: boolean;
251
377
  minutesPerRound: number | null;
252
378
  trend: LoopTrend;
379
+ /** One plain sentence on what the counts show; names no unit. */
380
+ trendLine: string;
253
381
  recommend: "try-again" | "stop" | null;
254
382
  }
255
383
 
256
- /** A fix loop's progress in the active run: `check` counts problems, `fix` fixes them. */
384
+ /**
385
+ * A fix loop's progress in the active run: `check` counts problems, `fix` fixes them. With
386
+ * `sinceClean`, only the rounds after `check`'s last clean round: a loop that reopens. With
387
+ * `gate` (a step prefix, e.g. `build-group-gate`), each round also counts the failing tests
388
+ * of the latest same-attempt test-run row of `{gate}-{group}`, or of `{gate}` with no group:
389
+ * 0 with no row, and unknown (null) when that row's count is null or the row is red with 0
390
+ * counted failures. A round is clean only when its gate also counted 0.
391
+ */
257
392
  export function loopProgress(
258
393
  file: string,
259
394
  cwd: string,
@@ -261,12 +396,30 @@ export function loopProgress(
261
396
  check: string,
262
397
  fix: string,
263
398
  group: number | undefined,
399
+ sinceClean = false,
400
+ gate?: string,
264
401
  ): LoopProgress {
265
402
  const runs = readRuns(file);
266
- const rounds = activeDoneSteps(runs, workflow, { step: check, group });
267
- const fixes = activeDoneSteps(runs, workflow, { step: fix, group });
268
- const first = rounds[0];
403
+ const gateStep = gate === undefined || group === undefined ? gate : `${gate}-${group}`;
404
+ const gateOf = (r: Step) =>
405
+ gateStep === undefined ? undefined : gateFailuresOf(file, workflow, gateStep, r.attempt);
406
+ const clean = (r: Step) => cleanRound(r) && (gateStep === undefined || gateOf(r) === 0);
407
+ const done = (step: string) =>
408
+ sinceClean
409
+ ? activeDoneStepsSinceClean(runs, workflow, { step, group }, check, clean)
410
+ : activeDoneSteps(runs, workflow, { step, group });
411
+ const checked = done(check);
412
+ const gateFailures = checked.map(gateOf);
413
+ const rounds = checked.map((r, i) => {
414
+ const g = gateFailures[i];
415
+ if (g === undefined) return r;
416
+ const failures = g === null || r.failures === undefined ? undefined : r.failures + g;
417
+ return { ...r, failures };
418
+ });
419
+ const fixes = done(fix);
269
420
  const last = rounds.at(-1);
421
+ // Only rounds that ran the same tests are compared: the earliest round with the last round's scope.
422
+ const first = last === undefined ? undefined : rounds.find((r) => r.scope === last.scope);
270
423
  let codeChanged: boolean | null = null;
271
424
  if (first && last && first !== last && first.parentSha && last.parentSha) {
272
425
  const diff = runGit(checkoutOf(file, cwd), [
@@ -281,26 +434,80 @@ export function loopProgress(
281
434
  if (diff.ok) codeChanged = false;
282
435
  else if (diff.stderr === "") codeChanged = true;
283
436
  }
284
- const ladder = lastDoneStepAllRuns(runs, workflow, { step: fix, group })?.strategy;
285
- const trend = loopTrend(rounds, codeChanged);
437
+ const prior = lastDoneStepAllRuns(runs, workflow, { step: fix, group })?.strategy;
438
+ // The same label `status route` gives the fix step: from the tests failing now.
439
+ const testStep = fixTestStep(fix, group);
440
+ const gated = gatedCheckStep(fix);
441
+ const current =
442
+ gated === undefined
443
+ ? undefined
444
+ : activeDoneSteps(runs, workflow, { step: gated, group }).length;
445
+ const next =
446
+ testStep === undefined
447
+ ? "STANDARD"
448
+ : repeatStrategy(readStatusRows(file), workflow, testStep, current).strategy;
449
+ const sameScope = first !== undefined && last !== undefined && first !== last;
450
+ const differentScopes = rounds.length >= 2 && !sameScope;
451
+ const trend: LoopTrend =
452
+ rounds.length < 2
453
+ ? "first-round"
454
+ : differentScopes
455
+ ? "unknown"
456
+ : loopTrend([first as Step, last as Step], codeChanged);
457
+ const countOf = (r: Step | undefined) => (r?.failures === undefined ? "?" : String(r.failures));
458
+ const pairCounts = `${countOf(first)} → ${countOf(last)}`;
459
+ const firstFailures = first?.failures;
460
+ const lastFailures = last?.failures;
461
+ let trendLine: string;
462
+ if (trend === "first-round") trendLine = "This was the first round, so there is no trend yet.";
463
+ else if (differentScopes)
464
+ trendLine = `The rounds ran different tests (${scopeText(rounds[0]?.scope)}, then ${scopeText(last?.scope)}), so their counts cannot be compared.`;
465
+ else if (trend === "unknown")
466
+ trendLine = `A round recorded no count (${rounds.map(countOf).join(" → ")}), so progress cannot be judged.`;
467
+ else if (trend === "closing")
468
+ trendLine = `The count fell between the first and the last round (${pairCounts}), and the code changed.`;
469
+ else if (trend === "worse")
470
+ trendLine = `The count rose between the first and the last round (${pairCounts}).`;
471
+ else if (
472
+ firstFailures !== undefined &&
473
+ lastFailures !== undefined &&
474
+ lastFailures < firstFailures
475
+ )
476
+ trendLine = `The count fell (${pairCounts}), but no source code changed between the rounds.`;
477
+ else trendLine = `The count did not fall between the first and the last round (${pairCounts}).`;
286
478
  const span =
287
- first && last && rounds.length > 1
288
- ? (Date.parse(last.at) - Date.parse(first.at)) / 60000 / (rounds.length - 1)
479
+ rounds[0] && last && rounds.length > 1
480
+ ? (Date.parse(last.at) - Date.parse(rounds[0].at)) / 60000 / (rounds.length - 1)
289
481
  : null;
290
482
  return {
291
- rounds: rounds.map((r) => ({
483
+ rounds: rounds.map((r, i) => ({
292
484
  attempt: r.attempt ?? null,
293
485
  failures: r.failures ?? null,
486
+ ...(gateFailures[i] === undefined ? {} : { gateFailures: gateFailures[i] }),
487
+ scope: r.scope ?? null,
294
488
  at: r.at,
295
489
  })),
296
490
  counts: rounds.map((r) => (r.failures === undefined ? "?" : String(r.failures))).join(" → "),
491
+ ...(gateStep === undefined
492
+ ? {}
493
+ : {
494
+ gateCounts: gateFailures
495
+ .map((g) => (g === null || g === undefined ? "?" : String(g)))
496
+ .join(" → "),
497
+ }),
297
498
  codeChanged,
298
499
  lastStrategy: fixes.at(-1)?.strategy ?? null,
299
- nextStrategy: nextStrategy(ladder),
300
- finalSpent: fixes.some((r) => r.strategy === "FINAL") || ladder === "FINAL",
500
+ nextStrategy: next,
501
+ finalSpent: fixes.some((r) => r.strategy === "FINAL") || prior === "FINAL",
301
502
  minutesPerRound: span === null || Number.isNaN(span) ? null : Math.round(span),
302
503
  trend,
303
- recommend: trend === "first-round" ? null : trend === "closing" ? "try-again" : "stop",
504
+ trendLine,
505
+ recommend:
506
+ trend === "first-round" || trend === "unknown"
507
+ ? null
508
+ : trend === "closing"
509
+ ? "try-again"
510
+ : "stop",
304
511
  };
305
512
  }
306
513
 
@@ -544,6 +751,61 @@ export const countersCommand: CommandSpec = {
544
751
  return EXIT.OK;
545
752
  },
546
753
  },
754
+ correction: {
755
+ summary:
756
+ "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.",
757
+ use: "workflow",
758
+ flags: [
759
+ FILE_FLAG,
760
+ WORKFLOW_FLAG,
761
+ {
762
+ name: "scope",
763
+ type: "string",
764
+ required: true,
765
+ help: "the engine-derived correction scope",
766
+ },
767
+ {
768
+ name: "operation",
769
+ type: "string",
770
+ required: true,
771
+ help: "the corrected candidate's fresh operation id",
772
+ },
773
+ {
774
+ name: "request-hash",
775
+ type: "string",
776
+ help: "the candidate's canonical request hash: a known operation replays free only for the same hash, and a different one is refused",
777
+ },
778
+ {
779
+ name: "limit",
780
+ type: "string",
781
+ help: `corrected retries this route allows (default ${CORRECTION_LIMIT}); a smaller one wins`,
782
+ },
783
+ ],
784
+ output: {
785
+ allowed: "true when the correction may run",
786
+ used: "operations counted in this scope",
787
+ limit: "retries this route allows",
788
+ remaining: "retries left",
789
+ replayed: "true when the operation was already counted: nothing was spent",
790
+ },
791
+ exitCodes: { [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON" },
792
+ run: (ctx) => {
793
+ const file = statusFile(ctx);
794
+ if (!fs.existsSync(file)) throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
795
+ const spend = spendCorrection(
796
+ file,
797
+ String(ctx.flags.workflow),
798
+ String(ctx.flags.scope),
799
+ String(ctx.flags.operation),
800
+ wholeNumber(ctx.flags.limit, "limit", CORRECTION_LIMIT),
801
+ str(ctx.flags.requestHash) === undefined
802
+ ? {}
803
+ : { requestHash: str(ctx.flags.requestHash) },
804
+ );
805
+ ctx.emit({ ...spend });
806
+ return spend.allowed ? EXIT.OK : EXIT.NO;
807
+ },
808
+ },
547
809
  max: {
548
810
  summary: "The ask points' limits and ask settings: one by --point, or all.",
549
811
  use: "workflow",
@@ -599,18 +861,30 @@ export const countersCommand: CommandSpec = {
599
861
  help: "the step that fixes them, e.g. build-plan-gaps-remediate",
600
862
  },
601
863
  GROUP_FLAG,
864
+ {
865
+ name: "since-clean",
866
+ type: "boolean",
867
+ help: "only the rounds after --check's last clean round (PASS, or CONCERNS with 0 failures)",
868
+ },
602
869
  ],
603
870
  output: {
604
- rounds: "the check rounds counted: attempt, failures, at",
605
- counts: "problem count after each round, e.g. 5 → 2",
871
+ rounds:
872
+ "the check rounds counted: attempt, failures, gateFailures, scope (what the round ran), at",
873
+ counts:
874
+ "problem count after each round, e.g. 5 → 2 (with a gate, the gate's failing tests are added)",
875
+ gateCounts:
876
+ "the group gate's failing tests after each round, e.g. 3 → 3 (absent without a gate)",
606
877
  codeChanged:
607
- "source changed between the first and last check round (null when git cannot tell)",
878
+ "source changed between the compared rounds, the earliest and the last that ran the same tests (same scope) (null when git cannot tell)",
608
879
  lastStrategy: "strategy of the last fix round (null when none ran)",
609
880
  nextStrategy: "strategy the next fix round would use",
610
881
  finalSpent: "true when a fix round already ran FINAL",
611
882
  minutesPerRound: "average minutes between check rounds (null under two rounds)",
612
- trend: "first-round | closing | stuck | worse",
613
- recommend: "try-again when closing, else stop (null on the first round)",
883
+ trend:
884
+ "first-round | closing | stuck | worse | unknown (a missing count, or rounds of different scopes)",
885
+ trendLine: "one plain sentence on what the counts show, with the counts and the reason",
886
+ recommend:
887
+ "try-again when closing, stop when stuck or worse (null on the first round or an unknown trend)",
614
888
  },
615
889
  exitCodes: { [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON" },
616
890
  run: (ctx) => {
@@ -622,6 +896,7 @@ export const countersCommand: CommandSpec = {
622
896
  String(ctx.flags.check),
623
897
  String(ctx.flags.fix),
624
898
  positiveInt(ctx.flags.group, "group"),
899
+ ctx.flags.sinceClean === true,
625
900
  ),
626
901
  });
627
902
  return EXIT.OK;