@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
@@ -9,27 +9,30 @@
9
9
  // saying it did. `finish` is the whole step ending in one call: read the verdict
10
10
  // headers, derive the attempt, check what the gate checks, write the row, commit,
11
11
  // and print the step's tracker comment.
12
+ import { createHash } from "node:crypto";
12
13
  import * as fs from "node:fs";
13
14
  import * as path from "node:path";
14
15
  import { actionKey, activeDoneSteps, allRunsDoneSteps, appendLine, ciRoundMatches, runNumber, runOrStepField, statusTimestamp, } from "../../ledgers/status.js";
15
16
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
16
17
  import { appendFrictionRow, frictionRow, journalEnabled } from "../../ledgers/journal.js";
17
- import { resolveRepoSlug } from "../../ledgers/telemetry.js";
18
+ import { queryLedger, resolveRepoSlug } from "../../ledgers/telemetry.js";
18
19
  import { getPromptsRoot } from "../../shared/package-roots.js";
19
20
  import { readTextFile } from "../../shared/json.js";
20
21
  import { CommandError, EXIT, git, isSharedBranch, parseJson, repoRoot, runGit, } from "../lib.js";
21
22
  import { activeRunStart, savedPointLimit } from "./counters.js";
22
23
  import { isResumable, runProgress, WORKFLOW_STEPS } from "./step-table.js";
23
24
  import { planFiles } from "./run-facts.js";
24
- import { mergeFindings, parseFindings } from "./challenge.js";
25
+ import { skipProblem } from "./open-decision.js";
26
+ import { mergeFindings, parseFindings, renderFindingsLog, structuredFindings, } from "./challenge.js";
25
27
  import { fidProblem, normaliseFid, readIssueTracker } from "./fids.js";
26
- import { buildComment } from "./issues.js";
28
+ import { auditEntries, auditFindingsLine, auditLedgerRows, auditTotals, buildComment, parseAuditResult, } from "./issues.js";
27
29
  import { EXIT_FOREIGN_PATH, activeRecord, ownPathCommit, ownSet, } from "./ledgers.js";
28
30
  import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
29
31
  import { EXIT_NO_STATUS, FILE_FLAG, GROUP_FLAG, STEP_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, readStatusRows, readRunsAt, statusFile, str, } from "./status.js";
30
32
  import { COMMENT_FILE_OUTPUT, POST_FLAG, TRACKER_OUTPUT, commentFileOf, postForVerb, } from "./tracker.js";
31
33
  import { parsePlanBlocks } from "./plan-blocks.js";
32
- import { PLAN_TASKS_STEP, readTestFirst, touchedTests } from "./tests.js";
34
+ import { blockedTests, PLAN_TASKS_STEP, readTestFirst, runPlanPath, sameTestName, touchedTests, baselineDiff, } from "./tests.js";
35
+ import { addTakeoverTasks } from "./tasks.js";
33
36
  import { addAllButCopied } from "./worktrees.js";
34
37
  /**
35
38
  * An `agent-rework` friction row for a refused planned-test edit: the step reruns, so
@@ -78,6 +81,8 @@ export const EXIT_SOURCE_TOUCHED = 15;
78
81
  export const PLAN_TESTS_STEP = "build-plan-tests";
79
82
  /** The step whose subagent closes the group's verification gaps: a code step, like plan-execute. */
80
83
  export const PLAN_REMEDIATE_STEP = "build-plan-gaps-remediate";
84
+ /** The step whose subagent closes the whole-feature verification gaps, across every group. */
85
+ export const PLAN_REMEDIATE_HOLISTIC_STEP = "build-plan-gaps-remediate-holistic";
81
86
  /** Where `finish` puts the derived attempt in `--artifact` / `--message` / `--clamp-log`. */
82
87
  export const ATTEMPT_TOKEN = "<attempt>";
83
88
  /** Where `finish` puts the first `DONE` line's description in `--message`. */
@@ -139,6 +144,9 @@ export function readHeader(file, allowed, require = [], declared = []) {
139
144
  if (m && !(m[1] in fields))
140
145
  fields[m[1]] = m[2].trim();
141
146
  }
147
+ const stale = fingerprintProblem(file, lines, end, fields);
148
+ if (stale !== null)
149
+ return { ok: false, code: EXIT_INVALID, problem: stale };
142
150
  const pending = Object.entries(fields).filter(([, v]) => /\bPENDING\b/.test(v));
143
151
  if (pending.length > 0) {
144
152
  return {
@@ -184,6 +192,25 @@ export function readHeader(file, allowed, require = [], declared = []) {
184
192
  }
185
193
  return { ok: true, verdict, fields };
186
194
  }
195
+ /** Header field that fingerprints a generated artifact's header and body. */
196
+ const FINGERPRINT = "Fingerprint";
197
+ /** sha256 of an artifact's header (without its Fingerprint line) and everything below it. */
198
+ export function artifactFingerprint(lines, end) {
199
+ const head = lines.slice(0, end).filter((l) => !l.startsWith(`${FINGERPRINT}:`));
200
+ const body = lines.slice(end + 1);
201
+ return createHash("sha256")
202
+ .update(`${head.join("\n")}\n${VERDICT_END}\n${body.join("\n")}`)
203
+ .digest("hex");
204
+ }
205
+ /** Why a generated artifact no longer matches what the engine rendered, or null (hand-written ones carry no fingerprint). */
206
+ function fingerprintProblem(file, lines, end, fields) {
207
+ const given = fields[FINGERPRINT];
208
+ if (given === undefined)
209
+ return null;
210
+ return artifactFingerprint(lines, end) === given
211
+ ? null
212
+ : `${file}: stale; its header or body changed after the engine rendered it (Fingerprint mismatch) — regenerate it from the result file`;
213
+ }
187
214
  /** Lines left as a stub placeholder: a bare `PENDING`, or a field whose whole value is `PENDING`. */
188
215
  export function placeholderLines(file) {
189
216
  return fs
@@ -277,6 +304,8 @@ export const ROW_FIELDS = {
277
304
  "build/build-group-gate": ["attempt", "scope"],
278
305
  "build/build-plan-gaps-remediate": ["attempt", "strategy"],
279
306
  "build/build-plan-verify-holistic": ["attempt"],
307
+ "build/build-holistic-gate": ["attempt", "scope"],
308
+ "build/build-plan-gaps-remediate-holistic": ["attempt", "strategy"],
280
309
  "build/build-challenge": ["attempt"],
281
310
  "build/build-decision": ["attempt"],
282
311
  "build/build-run-tests": ["attempt", "scope"],
@@ -293,8 +322,6 @@ export const ROW_FIELDS = {
293
322
  "debug/debug-summary": ["attempt"],
294
323
  "ship/ship-summary": ["attempt"],
295
324
  "ship/ship-merge-pr": ["attempt"],
296
- "ship/ship-failure-diagnose": ["attempt"],
297
- "ship/ship-failure-remediate": ["attempt", "strategy"],
298
325
  };
299
326
  /** The required fields missing (absent or empty) from a row. */
300
327
  export function missingRowFields(workflow, step, row) {
@@ -337,8 +364,7 @@ function progressPoint(workflow, step, soak) {
337
364
  if (["debug-run-tests", "debug-failure-diagnose", "debug-failure-remediate"].includes(step))
338
365
  return "debug.fix";
339
366
  }
340
- if (workflow === "ship" &&
341
- ["ship-merge-pr", "ship-failure-diagnose", "ship-failure-remediate"].includes(step))
367
+ if (workflow === "ship" && ["ship-merge-pr"].includes(step))
342
368
  return "ship.merge";
343
369
  return undefined;
344
370
  }
@@ -445,6 +471,12 @@ function restoreIndex(snap) {
445
471
  fs.rmSync(lock, { force: true });
446
472
  return null;
447
473
  }
474
+ /** The `--field` extras; `changedTests` is written by the planned-test lock alone. */
475
+ function fieldExtras(specs) {
476
+ if (specs.some((x) => x.startsWith("changedTests=")))
477
+ throw new CommandError(EXIT.USAGE, "--field cannot set changedTests; only the planned-test lock in `steps finish` writes it");
478
+ return Object.fromEntries(specs.map(extraField));
479
+ }
448
480
  /**
449
481
  * Append one `step-done` row, then commit (parentSha first, the row, then the
450
482
  * commit — the order the fold's de-dup relies on). Returns the row and the new
@@ -816,6 +848,22 @@ const titleCase = (key) => key.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c
816
848
  /** `<attempt>` filled in, once the attempt is known. */
817
849
  const fill = (s, attempt) => attempt === undefined ? s : s.split(ATTEMPT_TOKEN).join(String(attempt));
818
850
  const list = (v) => v ?? [];
851
+ /**
852
+ * A build decision row may say `route=continue` only when `bkit decisions skip` would pass
853
+ * its decision file (the step's first artifact): the same `skipProblem` rule, read here.
854
+ */
855
+ function continueCheck(cwd, decisionFile) {
856
+ const check = "route=continue";
857
+ if (decisionFile === undefined)
858
+ return { check, ok: false, detail: "no decision file: pass it as the first --artifact" };
859
+ const read = readTextFile(path.resolve(cwd, decisionFile));
860
+ if (!read.ok)
861
+ return { check, ok: false, detail: `${decisionFile} is missing or unreadable` };
862
+ const problem = skipProblem(read.text);
863
+ return problem === null
864
+ ? { check, ok: true, detail: `${decisionFile} passes decisions skip` }
865
+ : { check, ok: false, detail: `${decisionFile}: ${problem}` };
866
+ }
819
867
  async function finish(ctx) {
820
868
  const f = ctx.flags;
821
869
  const file = statusFile(ctx);
@@ -839,7 +887,7 @@ async function finish(ctx) {
839
887
  else {
840
888
  attempt = nonNegativeInt(f.attempt, "attempt");
841
889
  }
842
- const extras = Object.fromEntries(list(f.field).map(extraField));
890
+ const extras = fieldExtras(list(f.field));
843
891
  for (const spec of list(f.countField)) {
844
892
  const eq = spec.indexOf("=");
845
893
  if (eq <= 0)
@@ -954,7 +1002,9 @@ async function finish(ctx) {
954
1002
  extras.source === "ci" &&
955
1003
  extras.ciGeneration === active.ciGeneration &&
956
1004
  verdict === "FAIL" &&
957
- failures === undefined &&
1005
+ (typeof round.failures === "number"
1006
+ ? failures === round.failures
1007
+ : failures === undefined) &&
958
1008
  extras.scope === round.scope &&
959
1009
  artifacts.includes(String(round.artifact));
960
1010
  if (!matching)
@@ -998,6 +1048,8 @@ async function finish(ctx) {
998
1048
  });
999
1049
  if (missing.length)
1000
1050
  pre.push({ check: "status row", ok: false, detail: `row would miss ${missing.join(", ")}` });
1051
+ if (workflow === "build" && step === "build-decision" && extras.route === "continue")
1052
+ pre.push(continueCheck(ctx.cwd, artifacts[0]));
1001
1053
  if (pre.some((c) => !c.ok)) {
1002
1054
  for (const c of pre.filter((x) => !x.ok))
1003
1055
  ctx.log(`${c.check}: ${c.detail}`);
@@ -1009,16 +1061,132 @@ async function finish(ctx) {
1009
1061
  throw new CommandError(EXIT.USAGE, "--commit must be auto or none");
1010
1062
  // A code step never edits a planned test case: each one's own lines must still be the
1011
1063
  // lines the group's tests step recorded at its red. Every other edit to the file is
1012
- // ordinary code-step work the verifier reads in the diff.
1064
+ // ordinary code-step work the verifier reads in the diff. The holistic fix spans every group.
1013
1065
  if (workflow === "build" &&
1014
- (step === PLAN_TASKS_STEP || step === PLAN_REMEDIATE_STEP) &&
1015
- group !== undefined) {
1066
+ (step === PLAN_TASKS_STEP ||
1067
+ step === PLAN_REMEDIATE_STEP ||
1068
+ step === PLAN_REMEDIATE_HOLISTIC_STEP)) {
1016
1069
  const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1017
- const tests = touchedTests(top, file, workflow, group);
1070
+ const planArg = str(f.plan);
1071
+ const planFile = planArg === undefined
1072
+ ? runPlanPath(path.resolve(ctx.cwd, file))
1073
+ : path.resolve(ctx.cwd, planArg);
1074
+ const plan = fs.existsSync(planFile) ? fs.readFileSync(planFile, "utf-8") : undefined;
1075
+ const changed = touchedTests(top, file, workflow, plan);
1076
+ // A BLOCKED line of the step's log naming a changed test lets it through (recorded on the
1077
+ // row), unless an earlier record of that test already carries the line's reason.
1078
+ const logRead = artifacts[0] ? readTextFile(path.resolve(ctx.cwd, artifacts[0])) : undefined;
1079
+ const blocked = logRead?.ok ? blockedTests(logRead.text) : [];
1080
+ const changedTests = [];
1081
+ const tests = [];
1082
+ /** Why each refused test is refused, in step with `tests`. */
1083
+ const why = [];
1084
+ /**
1085
+ * Refused tests a later task contradicts: a BLOCKED line names the test, the change removes
1086
+ * lines, and the owning task's box is ticked. One entry per test, from its latest owner
1087
+ * (a chain of takeovers gives every owner the same baseline).
1088
+ */
1089
+ const latestOwner = new Map();
1090
+ const ticked = new Set(parsePlanBlocks(plan ?? "")
1091
+ .tasks.filter((t) => t.done)
1092
+ .map((t) => t.task));
1093
+ for (const c of changed) {
1094
+ const last = c.name.split(">").pop().trim();
1095
+ const naming = blocked.filter((b) => b.test === c.test && (b.name === c.name || b.name === last));
1096
+ const line = naming.find((b) => !c.reasons.includes(b.reason));
1097
+ const diff = line === undefined ? null : baselineDiff(top, c.text, c.test, c.name);
1098
+ // A test gone from the file (or renamed) against a recorded baseline removes its lines.
1099
+ const removes = diff === null ? c.text !== null : !diff.additive;
1100
+ if (line === undefined || removes) {
1101
+ if (!tests.some((t) => t.test === c.test && t.name === c.name)) {
1102
+ tests.push({ test: c.test, name: c.name });
1103
+ why.push({
1104
+ fromChange: c.fromChange,
1105
+ removed: line !== undefined,
1106
+ reused: line === undefined ? (naming[0]?.reason ?? null) : null,
1107
+ });
1108
+ }
1109
+ const key = `${c.test}\0${c.name}`;
1110
+ if (line !== undefined && ticked.has(c.task) && c.task > (latestOwner.get(key)?.from ?? 0))
1111
+ latestOwner.set(key, {
1112
+ test: c.test,
1113
+ name: c.name,
1114
+ from: c.task,
1115
+ task: line.task,
1116
+ reason: line.reason,
1117
+ });
1118
+ }
1119
+ else {
1120
+ const after = git(top, ["hash-object", "-w", "--", c.test]);
1121
+ changedTests.push({
1122
+ task: c.task,
1123
+ test: c.test,
1124
+ testName: c.name,
1125
+ block: c.block,
1126
+ reason: line.reason,
1127
+ blob: c.text,
1128
+ ...(after === null ? {} : { after }),
1129
+ });
1130
+ }
1131
+ }
1132
+ if (tests.length === 0 && changedTests.length > 0)
1133
+ extras.changedTests = changedTests;
1018
1134
  if (tests.length > 0) {
1019
1135
  const touched = [...new Set(tests.map((t) => t.test))];
1020
- const named = tests.map((t) => `\`${t.test}\` "${t.name}"`).join(", ");
1021
- const problem = `${named} differ${tests.length === 1 ? "s" : ""} from what the group's tests step recorded at its red: a code step never edits a planned test case — put ${tests.length === 1 ? "that test" : "those tests"} back as the tests step left ${tests.length === 1 ? "it" : "them"} (other edits to the file stay), or log the task BLOCKED naming the test and what it gets wrong (nothing written)`;
1136
+ const nameOf = (t) => `\`${t.test}\` "${t.name}"`;
1137
+ const named = tests.map(nameOf).join(", ");
1138
+ // The build hands each contradicted test to a takeover task before it re-asks.
1139
+ const entries = [...latestOwner.values()];
1140
+ // An entry needs a ticked owner, so the plan exists whenever there is one.
1141
+ const takeovers = addTakeoverTasks(ctx.cwd, planFile, path.resolve(ctx.cwd, file), entries, ctx.log);
1142
+ const contradicts = entries.map((e, i) => ({
1143
+ test: e.test,
1144
+ name: e.name,
1145
+ from: e.from,
1146
+ task: e.task,
1147
+ takeover: takeovers[i],
1148
+ }));
1149
+ const isContradicted = (t) => contradicts.some((x) => x.test === t.test && x.name === t.name);
1150
+ const contradictedPart = () => {
1151
+ if (contradicts.length === 0)
1152
+ return "";
1153
+ const many = contradicts.length > 1;
1154
+ const them = many ? "them" : "it";
1155
+ const owners = contradicts.map((x) => `TASK ${x.from}`).join(", ");
1156
+ const added = [...new Set(contradicts.map((x) => x.takeover))].join(", ");
1157
+ return `${contradicts.map(nameOf).join(", ")} ${many ? "are" : "is"} owned by an earlier, ticked task (${owners}) and this change contradicts ${them}: the build added takeover TASK ${added}, which rewrites ${them} in its own tests step — put ${them} back as the tests step left ${them} (other edits to the file stay); a BLOCKED line does not keep ${them}, so the keep-the-edit choice does not apply to ${them}`;
1158
+ };
1159
+ const logLines = (list) => list.map((t) => `BLOCKED — TASK {N}: test \`${t.test}\` \`${t.name}\` — {why}`).join("; ");
1160
+ const part = (fromChange) => {
1161
+ const list = tests.filter((t, i) => why[i].fromChange === fromChange && !isContradicted(t));
1162
+ if (list.length === 0)
1163
+ return "";
1164
+ const many = list.length > 1;
1165
+ const subject = `${list.map(nameOf).join(", ")} differ${many ? "" : "s"} from`;
1166
+ const them = many ? "those tests" : "that test";
1167
+ const it = many ? "them" : "it";
1168
+ return fromChange
1169
+ ? `${subject} the change a code step already recorded for ${many ? "them" : "it"} (changedTests): put ${them} back as that recorded change left ${it}, or keep the edit and log one line per test in the step's log: ${logLines(list)}`
1170
+ : `${subject} what the group's tests step recorded at its red: a code step never edits a planned test case — put ${them} back as the tests step left ${it} (other edits to the file stay), or keep the edit and log one line per test in the step's log: ${logLines(list)}`;
1171
+ };
1172
+ const notes = [];
1173
+ for (const [i, t] of tests.entries()) {
1174
+ const w = why[i];
1175
+ if (isContradicted(t))
1176
+ continue;
1177
+ if (w.removed)
1178
+ notes.push(`${nameOf(t)}: the engine refuses a BLOCKED-named change that removes a line of a planned test; it lets through only a change that adds lines, and verify reads every added line`);
1179
+ if (w.reused !== null)
1180
+ notes.push(`${nameOf(t)}: the BLOCKED line's reason "${w.reused}" is already recorded for that test — log a new reason`);
1181
+ }
1182
+ const refused = [part(false), part(true)].filter(Boolean);
1183
+ const refusedText = refused.length > 0
1184
+ ? `${refused.join(" | ")}${notes.length ? ` (${notes.join("; ")})` : ""} (Gap {N} in a gaps fix)`
1185
+ : "";
1186
+ const written = contradicts.length > 0
1187
+ ? "(no step row written; the plan and its build-takeover rows are)"
1188
+ : "(nothing written)";
1189
+ const problem = `${[contradictedPart(), refusedText].filter(Boolean).join(" | ")} ${written}`;
1022
1190
  ctx.log(problem);
1023
1191
  recordTestLockFriction(top, step, named);
1024
1192
  ctx.emit({
@@ -1027,6 +1195,7 @@ async function finish(ctx) {
1027
1195
  problem,
1028
1196
  touched,
1029
1197
  tests,
1198
+ contradicts,
1030
1199
  });
1031
1200
  return EXIT_TESTS_TOUCHED;
1032
1201
  }
@@ -1049,6 +1218,37 @@ async function finish(ctx) {
1049
1218
  ctx.emit({ pass: false, source });
1050
1219
  return EXIT_SOURCE_TOUCHED;
1051
1220
  }
1221
+ // An earlier task's planned test stays as its baseline left it, unless an open task of
1222
+ // this group names it (its own test, or one it takes over).
1223
+ const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1224
+ const planPath = path.resolve(ctx.cwd, planArg);
1225
+ const planText = fs.existsSync(planPath) ? fs.readFileSync(planPath, "utf-8") : undefined;
1226
+ const planTasks = parsePlanBlocks(planText ?? "").tasks;
1227
+ const done = new Set(planTasks.filter((t) => t.done).map((t) => t.task));
1228
+ const inGroup = new Set(planTasks.filter((t) => t.group === group).map((t) => t.task));
1229
+ const mine = readTestFirst(planText ?? "", group).flatMap((s) => s.kind === "test" && !done.has(s.task) ? s.tests : []);
1230
+ // Only a per-test lock binds here: an earlier group's test held by its whole file's blob
1231
+ // (no line carries its name, or the file was missing) cannot tell this group's own new
1232
+ // tests in that file from an edit to it.
1233
+ const tests = touchedTests(top, file, workflow, planText)
1234
+ .filter((c) => !c.wholeFile || inGroup.has(c.task))
1235
+ .filter((c) => !mine.some((m) => m.test === c.test && sameTestName(m.name, c.name)))
1236
+ .map((c) => ({ test: c.test, name: c.name }));
1237
+ if (tests.length > 0) {
1238
+ const touched = [...new Set(tests.map((t) => t.test))];
1239
+ const named = tests.map((t) => `\`${t.test}\` "${t.name}"`).join(", ");
1240
+ const problem = `${named} ${tests.length > 1 ? "are" : "is"} an earlier task's planned test that no open task of group ${group} names: the tests step never changes it — put it back as the earlier task's red left it (other edits to the file stay); to change what it asserts, the plan names it on this group's task TEST FIRST (a takeover) (nothing written)`;
1241
+ ctx.log(problem);
1242
+ recordTestLockFriction(top, step, named);
1243
+ ctx.emit({
1244
+ pass: false,
1245
+ reask: agents.length ? { agent: agents[0], artifact: artifacts[0] } : null,
1246
+ problem,
1247
+ touched,
1248
+ tests,
1249
+ });
1250
+ return EXIT_TESTS_TOUCHED;
1251
+ }
1052
1252
  }
1053
1253
  // The attempt finished is the latest one this run saved artifacts for.
1054
1254
  if (attempt !== undefined) {
@@ -1148,7 +1348,14 @@ async function finish(ctx) {
1148
1348
  if (comment === null)
1149
1349
  throw new CommandError(EXIT.USAGE, "--post needs --number");
1150
1350
  const key = actionKey(workflow, fs.existsSync(file) ? runNumber(readRuns(file), workflow) : 1, step, group, attempt, "comment");
1151
- tracker = await postForVerb(ctx, comment, { fid: fidOfStatusFile(file), file, key });
1351
+ tracker = await postForVerb(ctx, comment, {
1352
+ fid: fidOfStatusFile(file),
1353
+ file,
1354
+ key,
1355
+ purpose: step.endsWith("-decision") || verdict === "FAIL" || verdict === "HANDOVER"
1356
+ ? "attention"
1357
+ : "routine",
1358
+ });
1152
1359
  }
1153
1360
  const written = writeStepRow(ctx.cwd, {
1154
1361
  file,
@@ -1192,7 +1399,7 @@ async function finish(ctx) {
1192
1399
  checks,
1193
1400
  comment,
1194
1401
  // Written after the step's commit, so the commit never carries it.
1195
- commentFile: commentFileOf(ctx.cwd, comment),
1402
+ commentFile: commentFileOf(ctx.cwd, comment, ctx),
1196
1403
  ...(tracker === undefined ? {} : { tracker }),
1197
1404
  });
1198
1405
  if (written.code !== EXIT.OK)
@@ -1200,6 +1407,209 @@ async function finish(ctx) {
1200
1407
  return pass ? EXIT.OK : EXIT.NO;
1201
1408
  }
1202
1409
  // ---------------------------------------------------------------------------
1410
+ // stub --result-file — an artifact rendered from one structured result
1411
+ // ---------------------------------------------------------------------------
1412
+ /**
1413
+ * Header fields the engine computes from the findings; every other declared field is a
1414
+ * judgment the result must supply (the evidence-dependent ones: Tasks, Redesign, Strategy ...).
1415
+ */
1416
+ const DERIVED_FIELDS = {
1417
+ Failures: (f) => String(f.length),
1418
+ // `true` when any gap is fixable (the plan-verify header contract), `false` for none.
1419
+ Fixable: (f) => String(f.some((x) => x.fixable)),
1420
+ };
1421
+ /** The agent whose header is the audit summary (Status / Report / Findings), not a Verdict header. */
1422
+ const AUDIT_AGENT = "bkit-audit-generate";
1423
+ const withFingerprint = (head, body) => {
1424
+ const unsigned = `${head.join("\n")}\n${VERDICT_END}\n\n${body}`;
1425
+ const lines = unsigned.split("\n");
1426
+ const fingerprint = artifactFingerprint(lines, head.length);
1427
+ return `${head.join("\n")}\n${FINGERPRINT}: ${fingerprint}\n${VERDICT_END}\n\n${body}`;
1428
+ };
1429
+ const fingerprintOf = (text) => artifactFingerprint(text.split("\n"), text.split("\n").indexOf(VERDICT_END));
1430
+ /**
1431
+ * Every key the failures ledger (the working directory's `docs/failures.jsonl`, the file
1432
+ * `ledgers append` and `ledgers query` use) already holds, with the finding each row records,
1433
+ * so a derived audit key never lands on a different finding's row.
1434
+ */
1435
+ function ledgerKeys(cwd) {
1436
+ const file = path.resolve(cwd, "docs", "failures.jsonl");
1437
+ const held = new Map();
1438
+ if (!fs.existsSync(file))
1439
+ return held;
1440
+ for (const row of queryLedger(fs.readFileSync(file, "utf8")).rows) {
1441
+ const r = { ...row };
1442
+ if (typeof r["key"] !== "string")
1443
+ continue;
1444
+ const locations = Array.isArray(r["references"])
1445
+ ? r["references"].filter((x) => typeof x === "string")
1446
+ : [];
1447
+ const text = typeof r["description"] === "string" ? r["description"] : "";
1448
+ const fromText = /\((\S+:\d+)\);/.exec(text);
1449
+ if (fromText?.[1] !== undefined)
1450
+ locations.push(fromText[1]);
1451
+ held.set(r["key"], {
1452
+ summary: typeof r["summary"] === "string" ? r["summary"] : "",
1453
+ locations,
1454
+ });
1455
+ }
1456
+ return held;
1457
+ }
1458
+ function renderAudit(cwd, result) {
1459
+ const held = ledgerKeys(cwd);
1460
+ const entries = auditEntries(result, held);
1461
+ const totals = auditTotals(result.findings);
1462
+ const head = [
1463
+ `Status: ${result.status}`,
1464
+ `Report: ${result.report ?? "None"}`,
1465
+ `Findings: ${auditFindingsLine(totals)}`,
1466
+ `Issue: ${result.issue ?? "None"}`,
1467
+ `Parent: ${result.parent ?? "None"}`,
1468
+ ];
1469
+ const cell = (t) => t.replace(/\|/g, "\\|");
1470
+ const list = (items) => (items.length ? items.map((i) => `- ${i}`).join("\n") : "None");
1471
+ const body = [
1472
+ `# Audit Summary: ${result.slug}`,
1473
+ "",
1474
+ "## Stopped",
1475
+ "",
1476
+ result.stopped ?? "None",
1477
+ "",
1478
+ "## Overview",
1479
+ "",
1480
+ result.overview ?? "None",
1481
+ "",
1482
+ "## Suggested Issues",
1483
+ "",
1484
+ ...(entries.length
1485
+ ? [
1486
+ "| ID | Severity | Title | Location | Prior key |",
1487
+ "| --- | --- | --- | --- | --- |",
1488
+ ...entries.map((e) => `| ${e.id} | ${e.severity} | ${cell(e.title)} | \`${e.location}\` | ${e.priorKey ?? "none"} |`),
1489
+ ]
1490
+ : ["None"]),
1491
+ "",
1492
+ "## Not Checked",
1493
+ "",
1494
+ list(result.notChecked),
1495
+ "",
1496
+ "## Ledger",
1497
+ "",
1498
+ list(entries.map((e) => `\`${e.key}\` ${e.severity} OPEN`)),
1499
+ "",
1500
+ ].join("\n");
1501
+ const text = withFingerprint(head, body);
1502
+ return {
1503
+ text,
1504
+ fingerprint: fingerprintOf(text),
1505
+ extra: {
1506
+ ids: entries.map((e) => e.id),
1507
+ totals,
1508
+ ledgerRows: auditLedgerRows(result, held),
1509
+ },
1510
+ };
1511
+ }
1512
+ /**
1513
+ * The artifact for `agent` rendered from a structured result `{findings, judgments, body,
1514
+ * evidenceComplete}`: counts and booleans derived from the findings, judged fields passed
1515
+ * through and checked, a Fingerprint over the header and body. Throws a CommandError
1516
+ * (EXIT_INVALID) and writes nothing on any disagreement.
1517
+ */
1518
+ export function renderResult(cwd, agent, raw) {
1519
+ const bad = (why) => new CommandError(EXIT_INVALID, `result: ${why}`);
1520
+ if (agent === AUDIT_AGENT) {
1521
+ try {
1522
+ return renderAudit(cwd, parseAuditResult(raw));
1523
+ }
1524
+ catch (err) {
1525
+ throw err instanceof CommandError ? bad(err.message) : err;
1526
+ }
1527
+ }
1528
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw))
1529
+ throw bad("must be a JSON object");
1530
+ const r = raw;
1531
+ for (const k of Object.keys(r))
1532
+ if (!["findings", "judgments", "body", "evidenceComplete"].includes(k))
1533
+ throw bad(`unknown field "${k}"`);
1534
+ let findings;
1535
+ try {
1536
+ findings = structuredFindings(r["findings"] ?? [], cwd);
1537
+ }
1538
+ catch (err) {
1539
+ throw err instanceof CommandError ? bad(err.message) : err;
1540
+ }
1541
+ const judgments = r["judgments"] ?? {};
1542
+ if (judgments === null || typeof judgments !== "object" || Array.isArray(judgments))
1543
+ throw bad("judgments must be an object");
1544
+ const judged = new Map();
1545
+ for (const [k, v] of Object.entries(judgments)) {
1546
+ if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
1547
+ throw bad(`judgment ${k} must be text, a number or a boolean`);
1548
+ // A judgment renders into one header line: a line break would forge header lines.
1549
+ if (/[\r\n]/.test(String(v)))
1550
+ throw bad(`judgment ${k} must be a single line`);
1551
+ judged.set(k, String(v));
1552
+ }
1553
+ const declared = promptHeader(agent);
1554
+ const names = new Set(["Verdict", ...declared.fields.map((f) => f.name)]);
1555
+ for (const k of judged.keys()) {
1556
+ if (!names.has(k))
1557
+ throw bad(`judgment ${k} is not a header field of ${agent}`);
1558
+ if (k in DERIVED_FIELDS)
1559
+ throw bad(`${k} is derived from the findings and cannot be supplied`);
1560
+ }
1561
+ if (typeof r["evidenceComplete"] !== "boolean")
1562
+ throw bad("evidenceComplete must be stated as true or false");
1563
+ const evidenceComplete = r["evidenceComplete"];
1564
+ const arithmetic = findings.length > 0
1565
+ ? "FAIL"
1566
+ : !evidenceComplete
1567
+ ? declared.verdicts.includes("CONCERNS")
1568
+ ? "CONCERNS"
1569
+ : "FAIL"
1570
+ : "PASS";
1571
+ const verdict = judged.get("Verdict") ?? arithmetic;
1572
+ if (!declared.verdicts.includes(verdict))
1573
+ throw bad(`Verdict ${verdict} is not ${declared.verdicts.join("|")}`);
1574
+ if (verdict === "PASS" && arithmetic !== "PASS")
1575
+ throw bad(findings.length > 0
1576
+ ? `Verdict PASS contradicts ${findings.length} finding(s)`
1577
+ : "Verdict PASS contradicts incomplete evidence");
1578
+ const head = [`Verdict: ${verdict}`];
1579
+ for (const f of declared.fields) {
1580
+ const value = DERIVED_FIELDS[f.name]?.(findings) ?? judged.get(f.name);
1581
+ if (value === undefined)
1582
+ throw bad(`${f.name} is a judgment the result must supply`);
1583
+ if (f.values && !f.values.includes(value))
1584
+ throw bad(`${f.name} ${value} is not ${f.values.join("|")}`);
1585
+ if (f.integer && !/^[0-9]+$/.test(value))
1586
+ throw bad(`${f.name} ${value} is not a non-negative integer`);
1587
+ head.push(`${f.name}: ${value}`);
1588
+ }
1589
+ const given = r["body"] ?? "";
1590
+ if (typeof given !== "string")
1591
+ throw bad("body must be text");
1592
+ if (verdict === "PASS" && given.trim() === "")
1593
+ throw bad("a PASS result needs a non-empty body");
1594
+ if (given.split("\n").includes(VERDICT_END))
1595
+ throw bad(`body holds a ${VERDICT_END} line`);
1596
+ const log = findings.length > 0 && !/^## Findings Log\b/m.test(given)
1597
+ ? `\n${renderFindingsLog(findings)}\n`
1598
+ : "";
1599
+ const body = `${given.replace(/\n+$/, "")}\n${log}`;
1600
+ const text = withFingerprint(head, body.replace(/^\n+/, ""));
1601
+ return { text, fingerprint: fingerprintOf(text), extra: { findings: findings.length } };
1602
+ }
1603
+ function readResult(cwd, file) {
1604
+ const abs = path.resolve(cwd, file);
1605
+ if (!fs.existsSync(abs))
1606
+ throw new CommandError(EXIT_INVALID, `result: ${file} does not exist`);
1607
+ const parsed = parseJson(fs.readFileSync(abs, "utf-8"));
1608
+ if (!parsed.ok)
1609
+ throw new CommandError(EXIT_INVALID, `result: ${file} is not JSON`);
1610
+ return parsed.value;
1611
+ }
1612
+ // ---------------------------------------------------------------------------
1203
1613
  // stub
1204
1614
  // ---------------------------------------------------------------------------
1205
1615
  /** The header a fresh versioned artifact starts with; the subagent fills it in last. */
@@ -1326,7 +1736,7 @@ export const stepsCommand = {
1326
1736
  group,
1327
1737
  strategy,
1328
1738
  artifacts,
1329
- extras: Object.fromEntries(list(f.field).map(extraField)),
1739
+ extras: fieldExtras(list(f.field)),
1330
1740
  parentSha: str(f.parentSha),
1331
1741
  commit: commit,
1332
1742
  message: str(f.message),
@@ -1340,7 +1750,7 @@ export const stepsCommand = {
1340
1750
  },
1341
1751
  },
1342
1752
  finish: {
1343
- summary: "End a step: read the verdict header(s), derive the attempt, check the gate, write the row, commit, print the tracker comment.",
1753
+ summary: "End a step: read the verdict header(s), derive the attempt, check the gate, write the row, commit, print the tracker comment. Exit 11 on a build tests step that changed an earlier task's recorded test no open task of the group names, and on a code step that changed a planned test; for each BLOCKED test a ticked task owns, a code step first adds a takeover task to the plan and its build-takeover row, and prints them under contradicts.",
1344
1754
  use: "workflow",
1345
1755
  flags: [
1346
1756
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
@@ -1413,7 +1823,7 @@ export const stepsCommand = {
1413
1823
  {
1414
1824
  name: "plan",
1415
1825
  type: "string",
1416
- help: `${PLAN_TESTS_STEP}: the plan file whose TEST FIRST lines bound the step's commit (required there with --commit=auto)`,
1826
+ help: `${PLAN_TESTS_STEP}: the plan file whose TEST FIRST lines bound the step's commit (required there with --commit=auto); the code steps: the plan whose TEST FIRST lines name the planned tests the lock checks (default: the plan beside the status file)`,
1417
1827
  },
1418
1828
  ...COMMIT_FLAGS.map((c) => c.name === "message"
1419
1829
  ? {
@@ -1478,6 +1888,7 @@ export const stepsCommand = {
1478
1888
  reask: "verdict read failed, or a planned test was touched: {agent, artifact} to re-ask (exit 4 / 5 / 6 / 11 only)",
1479
1889
  problem: "why the verdict read failed, or which planned tests the code step touched (exit 4 / 5 / 6 / 11 only)",
1480
1890
  touched: "planned test files of the group that differ from the blob its tests step recorded (exit 11 only)",
1891
+ contradicts: "[{test, name, from, task, takeover}] the refused tests a ticked task `from` owns that this change contradicts, each with the takeover task the engine added (exit 11 on a code step only)",
1481
1892
  source: "files the tests step's commit would change that are not the group's TEST FIRST files, or add although a CREATE line names them (exit 15 only)",
1482
1893
  later: "artifacts of a later attempt this run saved (exit 12 only)",
1483
1894
  changed: "bkit.workflows keys the commit would change, dotted (exit 13 only)",
@@ -1493,7 +1904,7 @@ export const stepsCommand = {
1493
1904
  [EXIT_FOREIGN_PATH]: "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1494
1905
  [EXIT_NO_RECORD]: "a debug run on dev/main with no shared-checkout record: nothing written or committed",
1495
1906
  [EXIT_OUTSIDE_DOCS]: "--docs-only and the step staged a file outside the artifact tree (nothing written)",
1496
- [EXIT_TESTS_TOUCHED]: "build plan-execute / plan-gaps-remediate: a planned test case of the group differs from the lines its tests step recorded in status.jsonl (`tests`: [{test, name}]; `touched`: their files) — re-ask `reask.agent` to put that test back or log the task BLOCKED; other edits to the file stay (nothing written; an agent-rework friction row is appended)",
1907
+ [EXIT_TESTS_TOUCHED]: "build plan-execute / plan-gaps-remediate: a planned test case (of any group) differs from the lines recorded in status.jsonl (`tests`: [{test, name}]; `touched`: their files) — re-ask `reask.agent` to put that test back, or to keep the edit and log ``BLOCKED — TASK {N}: test `{file}` `{name}` — {why}`` (Gap {N} in a gaps fix) in the step's log, which lets that change through and records it in the row's `changedTests`; other edits to the file stay (nothing written; an agent-rework friction row is appended). A BLOCKED test that removes lines of a ticked task's planned test is contradicted instead: no BLOCKED line keeps it, the engine adds a takeover task and its build-takeover row (once per test, however often the finish runs) and lists it in `contradicts`; the agent puts it back",
1497
1908
  [EXIT_LATER_ATTEMPT]: "this run saved an artifact of a later attempt (`later`) than the one finished (nothing written)",
1498
1909
  [EXIT_WORKFLOWS_CHANGED]: "the commit would change bkit.workflows in package.json (`changed` names the keys) (nothing written)",
1499
1910
  [EXIT_SOURCE_TOUCHED]: "build plan-tests: the tests step changed a file no TEST FIRST line of the group's open tasks names, or added one a CREATE line of the plan names (`source`) (nothing written)",
@@ -1512,12 +1923,17 @@ export const stepsCommand = {
1512
1923
  repeatable: true,
1513
1924
  help: "header field that must be present, e.g. Failures",
1514
1925
  },
1926
+ {
1927
+ name: "result-file",
1928
+ type: "string",
1929
+ help: "with --agent: also require the artifact to be the render of this result (a changed result is stale)",
1930
+ },
1515
1931
  ],
1516
1932
  output: { verdict: "the Verdict value", fields: "every Key: value header field" },
1517
1933
  exitCodes: {
1518
1934
  [EXIT_EMPTY]: "artifact missing or empty",
1519
1935
  [EXIT_PENDING]: "a header field is still PENDING",
1520
- [EXIT_INVALID]: "no verdict:end line, Verdict outside the allowed set, or a required field missing — re-prompt the subagent",
1936
+ [EXIT_INVALID]: "no verdict:end line, Verdict outside the allowed set, a required field missing, or a generated artifact whose Fingerprint no longer matches its header and body (stale) — re-prompt the subagent or regenerate it",
1521
1937
  },
1522
1938
  run: (ctx) => {
1523
1939
  const header = readHeader(path.resolve(ctx.cwd, String(ctx.flags.file)), allowedVerdicts(ctx.flags), list(ctx.flags.field));
@@ -1525,6 +1941,23 @@ export const stepsCommand = {
1525
1941
  ctx.log(header.problem);
1526
1942
  return header.code;
1527
1943
  }
1944
+ if (ctx.flags.resultFile !== undefined) {
1945
+ if (ctx.flags.agent === undefined)
1946
+ throw new CommandError(EXIT.USAGE, "--result-file needs --agent");
1947
+ try {
1948
+ const rendered = renderResult(ctx.cwd, String(ctx.flags.agent), readResult(ctx.cwd, String(ctx.flags.resultFile)));
1949
+ if (header.fields[FINGERPRINT] !== rendered.fingerprint) {
1950
+ ctx.log(`${String(ctx.flags.file)}: stale; it is not the render of ${String(ctx.flags.resultFile)} (Fingerprint mismatch)`);
1951
+ return EXIT_INVALID;
1952
+ }
1953
+ }
1954
+ catch (err) {
1955
+ if (!(err instanceof CommandError) || err.code !== EXIT_INVALID)
1956
+ throw err;
1957
+ ctx.log(err.message);
1958
+ return EXIT_INVALID;
1959
+ }
1960
+ }
1528
1961
  ctx.emit({ verdict: header.verdict, fields: header.fields });
1529
1962
  return EXIT.OK;
1530
1963
  },
@@ -1680,17 +2113,88 @@ export const stepsCommand = {
1680
2113
  summary: "Seed a versioned artifact: copy the prior version, then put a PENDING verdict header on top.",
1681
2114
  use: "workflow",
1682
2115
  flags: [
1683
- { name: "from", type: "string", required: true, help: "the prior versioned artifact" },
2116
+ { name: "from", type: "string", help: "the prior versioned artifact (copy mode)" },
1684
2117
  { name: "to", type: "string", required: true, help: "the artifact to create" },
2118
+ {
2119
+ name: "agent",
2120
+ type: "string",
2121
+ help: "with --result-file: the subagent whose header the result renders",
2122
+ },
2123
+ {
2124
+ name: "result-file",
2125
+ type: "string",
2126
+ help: "render the artifact from this structured result JSON {findings, judgments, body, evidenceComplete} (audit: the audit result) instead of copying --from",
2127
+ },
2128
+ {
2129
+ name: "invocation",
2130
+ type: "string",
2131
+ unresolved: true,
2132
+ help: "with --result-file: the invocation id this step runs under; a result that names another invocation is stale and refused (exit 6, nothing written)",
2133
+ },
1685
2134
  {
1686
2135
  name: "strip-header",
1687
2136
  type: "boolean",
1688
2137
  help: "drop the prior version's own header (everything down to its <!-- verdict:end -->)",
1689
2138
  },
1690
2139
  ],
1691
- output: { file: "the artifact written", stripped: "the prior header was dropped" },
1692
- exitCodes: { [EXIT_EMPTY]: "--from is missing or empty" },
2140
+ output: {
2141
+ file: "the artifact written (an audit summary whose --to already holds a report goes to <result-file>.summary.md)",
2142
+ reportKept: "audit result: the existing report at --to, left untouched",
2143
+ stripped: "the prior header was dropped (copy mode)",
2144
+ fingerprint: "with --result-file: the Fingerprint header value",
2145
+ ids: "audit result: the report-local finding IDs, in report order",
2146
+ totals: "audit result: findings per severity",
2147
+ ledgerRows: "audit result: one failure ledger payload per finding, for `bkit ledgers append`",
2148
+ findings: "other results: the finding count",
2149
+ },
2150
+ exitCodes: {
2151
+ [EXIT_EMPTY]: "--from is missing or empty",
2152
+ [EXIT_INVALID]: "--result-file is unreadable or invalid, or a judgment contradicts the findings (nothing written)",
2153
+ },
1693
2154
  run: (ctx) => {
2155
+ if (ctx.flags.resultFile !== undefined) {
2156
+ if (ctx.flags.from !== undefined)
2157
+ throw new CommandError(EXIT.USAGE, "give --from or --result-file, not both");
2158
+ if (ctx.flags.agent === undefined)
2159
+ throw new CommandError(EXIT.USAGE, "--result-file needs --agent");
2160
+ try {
2161
+ const result = readResult(ctx.cwd, String(ctx.flags.resultFile));
2162
+ const issued = str(ctx.flags.invocation);
2163
+ const carried = typeof result === "object" && result !== null && !Array.isArray(result)
2164
+ ? result.invocation
2165
+ : undefined;
2166
+ // A result written under another invocation is left over from an earlier round or run.
2167
+ if (issued !== undefined && carried !== undefined && carried !== issued)
2168
+ throw new CommandError(EXIT_INVALID, `result: ${String(ctx.flags.resultFile)} was written under invocation ${String(carried)}, not ${issued}; it is a stale result from an earlier round or run (nothing written)`);
2169
+ const rendered = renderResult(ctx.cwd, String(ctx.flags.agent), result);
2170
+ const requested = path.resolve(ctx.cwd, String(ctx.flags.to));
2171
+ // An audit's --to is the finished report; the summary never replaces it.
2172
+ const keepsReport = ctx.flags.agent === AUDIT_AGENT &&
2173
+ fs.existsSync(requested) &&
2174
+ fs.statSync(requested).size > 0;
2175
+ const resultFile = path.resolve(ctx.cwd, String(ctx.flags.resultFile));
2176
+ const to = keepsReport
2177
+ ? path.join(path.dirname(resultFile), `${path.basename(resultFile, path.extname(resultFile))}.summary.md`)
2178
+ : requested;
2179
+ fs.mkdirSync(path.dirname(to), { recursive: true });
2180
+ fs.writeFileSync(to, rendered.text);
2181
+ ctx.emit({
2182
+ file: keepsReport ? path.relative(ctx.cwd, to) : String(ctx.flags.to),
2183
+ ...(keepsReport ? { reportKept: String(ctx.flags.to) } : {}),
2184
+ fingerprint: rendered.fingerprint,
2185
+ ...rendered.extra,
2186
+ });
2187
+ return EXIT.OK;
2188
+ }
2189
+ catch (err) {
2190
+ if (!(err instanceof CommandError) || err.code !== EXIT_INVALID)
2191
+ throw err;
2192
+ ctx.log(err.message);
2193
+ return EXIT_INVALID;
2194
+ }
2195
+ }
2196
+ if (ctx.flags.from === undefined)
2197
+ throw new CommandError(EXIT.USAGE, "give --from (copy) or --result-file");
1694
2198
  const from = path.resolve(ctx.cwd, String(ctx.flags.from));
1695
2199
  if (!fs.existsSync(from) || fs.statSync(from).size === 0) {
1696
2200
  ctx.log(`${String(ctx.flags.from)} is missing or empty`);