@cbartens/bkit 5.5.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -19,7 +19,7 @@ import { writeNetworkAllowlist } from "../network-allowlist.js";
19
19
  import type { PreflightFinding } from "../../checks/before/index.js";
20
20
  import { parseJson, readJsonFile } from "../../shared/json.js";
21
21
  import { readInstallingVersion } from "../../shared/package-json.js";
22
- import { CONFIG_DEFAULTS } from "../../shared/settings.js";
22
+ import { ASK_POINTS, CONFIG_DEFAULTS, limitKey } from "../../shared/settings.js";
23
23
  import {
24
24
  getCoreRoot,
25
25
  getSharedRoot,
@@ -33,6 +33,7 @@ import {
33
33
  BKIT_PUSH_GATES,
34
34
  BKIT_TEST_FILE_SCRIPT,
35
35
  } from "../manifest.js";
36
+ import { migrateLedgers } from "../../ledgers/migrate.js";
36
37
  import type { ModuleContext } from "./index.js";
37
38
 
38
39
  export function listMdFiles(dir: string, prefix?: string): string[] {
@@ -249,10 +250,11 @@ function runCoreTemplates(
249
250
  // in-repo without spelunking node_modules. Force-overwritten (Tier 1) — bkit owns
250
251
  // them, so a consumer edit is replaced. Source of truth is the package's own
251
252
  // `.bkit/core/.bkit/<name>`. (`advisories.md` is a regenerated runtime artifact and
252
- // `wording.md` is repo-only tooling — neither belongs here. `LICENSE.md` is the MIT
253
+ // `instructions.md` is repo-only tooling — neither belongs here. `LICENSE.md` is the MIT
253
254
  // notice that travels with the files bkit writes: MIT requires the copyright and
254
255
  // permission notice in every copy.)
255
256
  export const BKIT_CANONICAL_DOCS = [
257
+ "authoring.md",
256
258
  "cloud.md",
257
259
  "comparison.md",
258
260
  "install.md",
@@ -302,6 +304,28 @@ export function runBkitDocs(
302
304
  }
303
305
  migrateShortcutsToLite(dryRun, ws, logPrefix);
304
306
  migrateRetiredDevLock(dryRun, ws, logPrefix);
307
+ migrateLedgerSchema(dryRun, ws, logPrefix);
308
+ migrateJiraKeyName(dryRun, logPrefix);
309
+ }
310
+
311
+ // Migration (installs up to 5.5.x, `docs/migrations.md`): the Jira key was
312
+ // `BKIT_JIRA_API_TOKEN`; the engine and the MCP configs now read `BKIT_JIRA_API_KEY`.
313
+ // `.bkit/.env` lines naming the old key are renamed in place, value kept. Logged only,
314
+ // never recorded in ws: a ws write gets a canonical hash, and a secrets file never does.
315
+ // A file already naming the new key is left alone.
316
+ const ENV_FILE = path.join(".bkit", ".env");
317
+ const OLD_JIRA_KEY = "BKIT_JIRA_API_TOKEN";
318
+ const NEW_JIRA_KEY = "BKIT_JIRA_API_KEY";
319
+
320
+ export function migrateJiraKeyName(dryRun: boolean, logPrefix: string): void {
321
+ if (!fs.lstatSync(ENV_FILE, { throwIfNoEntry: false })?.isFile()) return;
322
+ const text = fs.readFileSync(ENV_FILE, "utf-8");
323
+ const assigns = (key: string) => new RegExp(`^\\s*(export\\s+)?${key}=`, "m").test(text);
324
+ if (!assigns(OLD_JIRA_KEY) || assigns(NEW_JIRA_KEY)) return;
325
+ if (!dryRun) fs.writeFileSync(ENV_FILE, text.split(OLD_JIRA_KEY).join(NEW_JIRA_KEY), "utf-8");
326
+ console.log(
327
+ `${logPrefix} ${dryRun ? "[dry-run] " : ""}core: ${ENV_FILE} — ${OLD_JIRA_KEY} renamed to ${NEW_JIRA_KEY}`,
328
+ );
305
329
  }
306
330
 
307
331
  // Migration (5.1.0 – 5.2.4 installs, `docs/migrations.md`): the lite workflows lived at
@@ -355,6 +379,20 @@ export function migrateRetiredDevLock(dryRun: boolean, ws: WriteSet, logPrefix:
355
379
  );
356
380
  }
357
381
 
382
+ // Migration (installs up to 5.5.x, `docs/migrations.md`): ledger rows written before
383
+ // `schema: 2` are rewritten into the current shape (`.bkit/jsonl.md` § Generic Fields).
384
+ // Recorded in ws so `bkit check` fails until upgrade runs; ledgers never get a
385
+ // canonical hash (`mergeCanonicalHashes`).
386
+ export function migrateLedgerSchema(dryRun: boolean, ws: WriteSet, logPrefix: string): void {
387
+ for (const { file, rewritten, dropped } of migrateLedgers(process.cwd(), dryRun)) {
388
+ ws.writes.push({ path: file, action: "update" });
389
+ const copies = dropped > 0 ? `, ${dropped} old copy(ies) of rewritten rows dropped` : "";
390
+ console.log(
391
+ `${logPrefix} ${dryRun ? "[dry-run] " : ""}core: ${file} — ${rewritten} row(s) rewritten to schema 2${copies}`,
392
+ );
393
+ }
394
+ }
395
+
358
396
  // ---------------------------------------------------------------------------
359
397
  // Source-rendered host outputs — agents (.agents/prompts source) and commands
360
398
  // (.bkit/workflows source). Extracted from the host module functions so BOTH
@@ -400,9 +438,117 @@ export function seedCorePackageJsonScripts(
400
438
  if (migrateGithubProjectKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
401
439
  written.push("package.json");
402
440
  }
441
+ if (migrateBkitLayout(dryRun, ws, logPrefix) && !written.includes("package.json")) {
442
+ written.push("package.json");
443
+ }
444
+ if (seedBkitDefaults(dryRun, ws, logPrefix) && !written.includes("package.json")) {
445
+ written.push("package.json");
446
+ }
403
447
  return written;
404
448
  }
405
449
 
450
+ /**
451
+ * Every `bkit.*` setting, written on every install and upgrade so consumers see them all;
452
+ * add-if-missing, nested blocks included. A key with a default gets it; a choice not made
453
+ * yet is `""` or `[]`, which every reader treats as unset.
454
+ */
455
+ export const SEEDED_BKIT_DEFAULTS: Readonly<Record<string, unknown>> = {
456
+ tracker: {
457
+ default: "",
458
+ github: {
459
+ project: "",
460
+ progress: CONFIG_DEFAULTS.github.progress,
461
+ review: CONFIG_DEFAULTS.github.review,
462
+ },
463
+ linear: {
464
+ team: "",
465
+ project: "",
466
+ progress: CONFIG_DEFAULTS.linear.progress,
467
+ review: CONFIG_DEFAULTS.linear.review,
468
+ },
469
+ jira: {
470
+ site: "",
471
+ project: "",
472
+ progress: CONFIG_DEFAULTS.jira.progress,
473
+ review: CONFIG_DEFAULTS.jira.review,
474
+ },
475
+ },
476
+ cloud: { agent: "" },
477
+ providers: { opencode: { default: "", installed: [] } },
478
+ testing: {
479
+ ciWorkflow: CONFIG_DEFAULTS.ciWorkflow,
480
+ ciCapstone: CONFIG_DEFAULTS.capstoneJob,
481
+ shipGate: [...CONFIG_DEFAULTS.shipGateRequiredLanes],
482
+ minPushPaths: [...CONFIG_DEFAULTS.minPushPaths],
483
+ },
484
+ workflows: {
485
+ minFreeGb: CONFIG_DEFAULTS.diskMinFreeGb,
486
+ worktree: { copy: [...CONFIG_DEFAULTS.worktreeCopy], install: CONFIG_DEFAULTS.worktreeInstall },
487
+ tasks: { ...CONFIG_DEFAULTS.tasks },
488
+ ...askBlocks(),
489
+ },
490
+ // bkit-utility-update-roadmap list length; the prompt falls back to 25 too.
491
+ prompts: { roadmapNext: 25 },
492
+ dependencies: { updater: "" },
493
+ advisories: { ignore: [] },
494
+ };
495
+
496
+ /** `{design: {grill: {ask, maxTurns}}, build: {...}, ...}`, from `CONFIG_DEFAULTS.asks`. */
497
+ function askBlocks(): Record<string, Record<string, Record<string, unknown>>> {
498
+ const out: Record<string, Record<string, Record<string, unknown>>> = {};
499
+ for (const point of ASK_POINTS) {
500
+ const [workflow, name] = point.split(".") as [string, string];
501
+ const d = CONFIG_DEFAULTS.asks[point];
502
+ (out[workflow] ??= {})[name] = { ask: d.ask, [limitKey(point)]: d.max };
503
+ }
504
+ return out;
505
+ }
506
+
507
+ const plainObject = (v: unknown): v is Record<string, unknown> =>
508
+ v !== null && typeof v === "object" && !Array.isArray(v);
509
+
510
+ // Copy each `defaults` key missing from `target`, descending into blocks both sides hold.
511
+ // A present key keeps its value, whatever it is. Pushes each added key's dotted path.
512
+ function addMissingKeys(
513
+ target: Record<string, unknown>,
514
+ defaults: Readonly<Record<string, unknown>>,
515
+ prefix: string,
516
+ added: string[],
517
+ ): void {
518
+ for (const [k, v] of Object.entries(defaults)) {
519
+ if (!Object.prototype.hasOwnProperty.call(target, k)) {
520
+ target[k] = structuredClone(v);
521
+ added.push(`${prefix}${k}`);
522
+ } else if (plainObject(v) && plainObject(target[k])) {
523
+ addMissingKeys(target[k], v, `${prefix}${k}.`, added);
524
+ }
525
+ }
526
+ }
527
+
528
+ // Add each SEEDED_BKIT_DEFAULTS key missing from `package.json` `bkit`, creating the block
529
+ // when absent. Runs after the legacy-key migrations, which test `=== undefined`. Returns
530
+ // true when package.json changed.
531
+ export function seedBkitDefaults(dryRun: boolean, ws: WriteSet, logPrefix: string): boolean {
532
+ const pkgPath = "package.json";
533
+ if (!fs.existsSync(pkgPath)) return false;
534
+ const raw = fs.readFileSync(pkgPath, "utf-8");
535
+ const parsed = parseJson(raw);
536
+ if (!parsed.ok) return false;
537
+ const pkg = parsed.value as Record<string, unknown>;
538
+ if (pkg.bkit !== undefined && !plainObject(pkg.bkit)) return false;
539
+ const cfg = (pkg.bkit ?? {}) as Record<string, unknown>;
540
+ const added: string[] = [];
541
+ addMissingKeys(cfg, SEEDED_BKIT_DEFAULTS, "bkit.", added);
542
+ if (added.length === 0) return false;
543
+ pkg.bkit = cfg;
544
+ ws.writes.push({ path: pkgPath, action: "update" });
545
+ if (!dryRun) writePackageJsonLike(raw, pkg);
546
+ console.log(
547
+ `${logPrefix} ${dryRun ? "[dry-run] " : ""}core: added ${added.join(", ")} to package.json`,
548
+ );
549
+ return true;
550
+ }
551
+
406
552
  /** Rewrite package.json with `pkg`, keeping the file's indent and trailing newline. */
407
553
  function writePackageJsonLike(raw: string, pkg: unknown): void {
408
554
  const indentMatch = raw.match(/\n([ \t]+)"/);
@@ -470,11 +616,112 @@ export function migrateGithubProjectKey(dryRun: boolean, ws: WriteSet, logPrefix
470
616
  console.log(`${logPrefix} ${tag}core: moved bkit.githubProject to bkit.github in package.json`);
471
617
  for (const moment of unnamed)
472
618
  console.log(
473
- `${logPrefix} ${tag}core: bkit.githubProject named its ${moment} Status option by id; set bkit.github.${moment} to that option's name (default "${CONFIG_DEFAULTS.github[moment]}")`,
619
+ `${logPrefix} ${tag}core: bkit.githubProject named its ${moment} Status option by id; set bkit.tracker.github.${moment} to that option's name (default "${CONFIG_DEFAULTS.github[moment]}")`,
474
620
  );
475
621
  return true;
476
622
  }
477
623
 
624
+ // Migration (up to 5.5.x installs, `docs/migrations.md`): `bkit` settings sat flat; they
625
+ // are grouped into named sections. Each old key moves to its new path; a value already at
626
+ // the new path wins, and two blocks merge key by key. `loopPause: true|false` becomes
627
+ // `ask` on every point under `workflows.<workflow>`, where an `ask` already set wins.
628
+ // Runs after the linearTeam and githubProject moves, which write the flat keys. Returns
629
+ // true when package.json changed.
630
+ export const BKIT_LAYOUT_MOVES: readonly (readonly [string, string])[] = [
631
+ ["issueTracker", "tracker.default"],
632
+ ["github", "tracker.github"],
633
+ ["linear", "tracker.linear"],
634
+ ["jira", "tracker.jira"],
635
+ ["cloudAgents", "cloud.agent"],
636
+ ["opencodeProvider", "providers.opencode.default"],
637
+ ["opencodeProviders", "providers.opencode.installed"],
638
+ ["minPushPaths", "testing.minPushPaths"],
639
+ ["capstoneJob", "testing.ciCapstone"],
640
+ ["ciWorkflow", "testing.ciWorkflow"],
641
+ ["shipGateRequiredLanes", "testing.shipGate"],
642
+ ["disk.minFreeGb", "workflows.minFreeGb"],
643
+ ["worktree", "workflows.worktree"],
644
+ ["tasks", "workflows.tasks"],
645
+ ["roadmapNext", "prompts.roadmapNext"],
646
+ ["depUpdater", "dependencies.updater"],
647
+ ["ignoreAdvisories", "advisories.ignore"],
648
+ ];
649
+
650
+ // Fill `into` with each `from` key it lacks, descending into blocks both sides hold.
651
+ function mergeMissing(into: Record<string, unknown>, from: Record<string, unknown>): void {
652
+ for (const [k, v] of Object.entries(from)) {
653
+ if (into[k] === undefined) into[k] = v;
654
+ else if (plainObject(v) && plainObject(into[k])) mergeMissing(into[k], v);
655
+ }
656
+ }
657
+
658
+ export function migrateBkitLayout(dryRun: boolean, ws: WriteSet, logPrefix: string): boolean {
659
+ const pkgPath = "package.json";
660
+ if (!fs.existsSync(pkgPath)) return false;
661
+ const raw = fs.readFileSync(pkgPath, "utf-8");
662
+ const parsed = parseJson(raw);
663
+ if (!parsed.ok) return false;
664
+ const pkg = parsed.value as Record<string, unknown>;
665
+ if (!plainObject(pkg.bkit)) return false;
666
+ const cfg = pkg.bkit;
667
+ const moved: string[] = [];
668
+ for (const [from, to] of BKIT_LAYOUT_MOVES) {
669
+ const fromPath = from.split(".");
670
+ const fromParent = fromPath
671
+ .slice(0, -1)
672
+ .reduce<unknown>((o, k) => (plainObject(o) ? o[k] : undefined), cfg);
673
+ const fromKey = fromPath[fromPath.length - 1]!;
674
+ if (!plainObject(fromParent) || !Object.prototype.hasOwnProperty.call(fromParent, fromKey))
675
+ continue;
676
+ const old = fromParent[fromKey];
677
+ const toPath = to.split(".");
678
+ let parent: Record<string, unknown> = cfg;
679
+ let blocked = false;
680
+ for (const k of toPath.slice(0, -1)) {
681
+ if (parent[k] === undefined) parent[k] = {};
682
+ if (!plainObject(parent[k])) {
683
+ blocked = true;
684
+ break;
685
+ }
686
+ parent = parent[k];
687
+ }
688
+ // A non-object where the new section belongs: leave the old key for `bkit check` to show.
689
+ if (blocked) continue;
690
+ const toKey = toPath[toPath.length - 1]!;
691
+ if (parent[toKey] === undefined) parent[toKey] = old;
692
+ else if (plainObject(parent[toKey]) && plainObject(old)) mergeMissing(parent[toKey], old);
693
+ delete fromParent[fromKey];
694
+ if (fromParent !== cfg && Object.keys(fromParent).length === 0) delete cfg[fromPath[0]!];
695
+ moved.push(`bkit.${from} -> bkit.${to}`);
696
+ }
697
+ if (Object.prototype.hasOwnProperty.call(cfg, "loopPause")) {
698
+ const old = cfg.loopPause;
699
+ if (typeof old === "boolean") {
700
+ if (cfg.workflows === undefined) cfg.workflows = {};
701
+ if (plainObject(cfg.workflows)) mergeMissing(cfg.workflows, askOnly(old));
702
+ }
703
+ delete cfg.loopPause;
704
+ moved.push("bkit.loopPause -> bkit.workflows.<workflow>.<point>.ask");
705
+ }
706
+ if (moved.length === 0) return false;
707
+ ws.writes.push({ path: pkgPath, action: "update" });
708
+ if (!dryRun) writePackageJsonLike(raw, pkg);
709
+ console.log(
710
+ `${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved ${moved.join(", ")} in package.json`,
711
+ );
712
+ return true;
713
+ }
714
+
715
+ /** `{design: {grill: {ask}}, build: {verify: {ask}, ...}, ...}` with every `ask` = `ask`. */
716
+ function askOnly(ask: boolean): Record<string, unknown> {
717
+ const out: Record<string, Record<string, Record<string, unknown>>> = {};
718
+ for (const point of ASK_POINTS) {
719
+ const [workflow, name] = point.split(".") as [string, string];
720
+ (out[workflow] ??= {})[name] = { ask };
721
+ }
722
+ return out;
723
+ }
724
+
478
725
  // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
479
726
  // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
480
727
  // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
@@ -158,7 +158,7 @@ export function detectOpencodeYmlProviderDrift(cwd: string): PreflightFinding |
158
158
  const ymlPath = path.join(cwd, ".github", "workflows", "opencode.yml");
159
159
  if (!fs.existsSync(ymlPath)) return null;
160
160
 
161
- // The installed provider — package.json `bkit.opencodeProvider` is the authoritative record
161
+ // The installed provider — package.json `bkit.providers.opencode.default` is the authoritative record
162
162
  // written on install. Absent/broken/unsupported → the null-guard below skips silently.
163
163
  const provider = readBkitConfig(cwd).opencodeProvider;
164
164
  if (!provider) return null;
@@ -267,7 +267,7 @@ export function renderOpencodeJson(
267
267
  // Same "oauth": false reason as github: the API token in the header is the only auth
268
268
  // bkit wires, so a bad one fails as a 401, not as an OAuth sign-in prompt.
269
269
  mcpEntry =
270
- '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_TOKEN}" } }';
270
+ '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_KEY}" } }';
271
271
  } else {
272
272
  mcpEntry = "";
273
273
  }
@@ -16,6 +16,7 @@ import * as path from "node:path";
16
16
  import * as crypto from "node:crypto";
17
17
  import { parseJson } from "../shared/json.js";
18
18
  import { getTemplatesRoot, templateRelPath } from "../shared/package-roots.js";
19
+ import { isSchemaLedger } from "../ledgers/migrate.js";
19
20
 
20
21
  // ---------------------------------------------------------------------------
21
22
  // Schema types
@@ -184,14 +185,17 @@ export function mergeCanonicalHashes(
184
185
  if (
185
186
  !fs.existsSync(path.join(cwd, relPath)) ||
186
187
  isRemoving(relPath) ||
187
- isTemplateSetPath(relPath)
188
+ isTemplateSetPath(relPath) ||
189
+ isSchemaLedger(relPath)
188
190
  ) {
189
191
  pruned++;
190
192
  continue;
191
193
  }
192
194
  canonicalHashes[relPath] = hash;
193
195
  }
194
- return { canonicalHashes: { ...canonicalHashes, ...fresh }, pruned };
196
+ // A ledger is append-only data a migration may rewrite, never a managed file.
197
+ const kept = Object.fromEntries(Object.entries(fresh).filter(([p]) => !isSchemaLedger(p)));
198
+ return { canonicalHashes: { ...canonicalHashes, ...kept }, pruned };
195
199
  }
196
200
 
197
201
  /** True when `dest` is a member of the package's copy-and-own template set. */
@@ -0,0 +1,92 @@
1
+ // Ledger rows written before `schema: 2` rewritten in place into the schema-2 shape
2
+ // (`docs/migrations.md`). Each line goes through `normalize`; a line that already
3
+ // carries `schema`, does not parse, or is not a JSON object stays byte-for-byte,
4
+ // so a second run changes nothing. Readers still normalize: a union merge can
5
+ // bring an old line back from a branch that predates the rewrite, beside its
6
+ // rewritten copy. The next run drops such a line instead of rewriting it twice.
7
+
8
+ import * as fs from "node:fs";
9
+ import * as path from "node:path";
10
+
11
+ import { parseJson } from "../shared/json.js";
12
+ import { normalize } from "./telemetry.js";
13
+
14
+ /** Every repo ledger whose rows carry the shared top section (`.bkit/jsonl.md`). */
15
+ export const SCHEMA_LEDGERS = [
16
+ ".bkit/stats.jsonl",
17
+ ".bkit/friction.jsonl",
18
+ ".bkit/issues.jsonl",
19
+ "docs/decisions.jsonl",
20
+ "docs/deferrals.jsonl",
21
+ "docs/failures.jsonl",
22
+ "docs/knowledge.jsonl",
23
+ ] as const;
24
+
25
+ /** True for a repo ledger path: append-only data, never a bkit-managed file. */
26
+ export const isSchemaLedger = (relPath: string): boolean =>
27
+ (SCHEMA_LEDGERS as readonly string[]).includes(relPath.split(path.sep).join("/"));
28
+
29
+ /** A line's row when it is a JSON object, else undefined. */
30
+ function rowOf(body: string): Record<string, unknown> | undefined {
31
+ const parsed = parseJson(body);
32
+ const row = parsed.ok ? parsed.value : undefined;
33
+ return row !== null && typeof row === "object" && !Array.isArray(row)
34
+ ? (row as Record<string, unknown>)
35
+ : undefined;
36
+ }
37
+
38
+ /**
39
+ * `text` with every pre-schema row rewritten; `rewritten` counts the lines changed.
40
+ * A pre-schema row whose rewrite is already a schema line of `text` is dropped and
41
+ * counted in `dropped`: it is that row's copy from an unmigrated branch.
42
+ */
43
+ export function migrateLedgerText(text: string): {
44
+ text: string;
45
+ rewritten: number;
46
+ dropped: number;
47
+ } {
48
+ let rewritten = 0;
49
+ let dropped = 0;
50
+ const bodies = text.split("\n").map((line) => line.replace(/\r$/, ""));
51
+ const present = new Set(bodies.filter((b) => rowOf(b)?.["schema"] !== undefined));
52
+ const lines = text.split("\n").flatMap((line, i) => {
53
+ const body = bodies[i] ?? "";
54
+ if (body.trim() === "") return [line];
55
+ const row = rowOf(body);
56
+ if (row === undefined || row["schema"] !== undefined) return [line];
57
+ const next = JSON.stringify(normalize(row));
58
+ if (present.has(next)) {
59
+ dropped++;
60
+ return [];
61
+ }
62
+ rewritten++;
63
+ return [next + line.slice(body.length)];
64
+ });
65
+ return { text: lines.join("\n"), rewritten, dropped };
66
+ }
67
+
68
+ /**
69
+ * Rewrite (or drop, as {@link migrateLedgerText} does) the pre-schema rows of every {@link SCHEMA_LEDGERS} file under `root`;
70
+ * with `dryRun`, only count them. Returns the files that have (or had) such rows,
71
+ * with their line counts. Writes via temp file + rename, so an interrupted run
72
+ * never leaves a torn ledger.
73
+ */
74
+ export function migrateLedgers(
75
+ root: string,
76
+ dryRun: boolean,
77
+ ): Array<{ file: string; rewritten: number; dropped: number }> {
78
+ const out: Array<{ file: string; rewritten: number; dropped: number }> = [];
79
+ for (const file of SCHEMA_LEDGERS) {
80
+ const abs = path.join(root, file);
81
+ if (!fs.lstatSync(abs, { throwIfNoEntry: false })?.isFile()) continue;
82
+ const { text, rewritten, dropped } = migrateLedgerText(fs.readFileSync(abs, "utf-8"));
83
+ if (rewritten + dropped === 0) continue;
84
+ if (!dryRun) {
85
+ const tmp = `${abs}.bkit-migrate.tmp`;
86
+ fs.writeFileSync(tmp, text, "utf-8");
87
+ fs.renameSync(tmp, abs);
88
+ }
89
+ out.push({ file, rewritten, dropped });
90
+ }
91
+ return out;
92
+ }
@@ -15,6 +15,12 @@
15
15
  // step's own commit (if any). Forensic only — points to the commit that preceded
16
16
  // this step's work, not the commit that resulted from it.
17
17
 
18
+ import { createHash } from "node:crypto";
19
+ import * as fs from "node:fs";
20
+ import * as path from "node:path";
21
+
22
+ import { parseJson } from "../shared/json.js";
23
+
18
24
  export type Step = {
19
25
  step: string;
20
26
  status: "DONE" | "FAILED";
@@ -23,6 +29,9 @@ export type Step = {
23
29
  artifacts: string[];
24
30
  verdict?: "PASS" | "FAIL" | "CONCERNS" | "SINGLE" | "SPLIT";
25
31
  attempt?: number;
32
+ /** The plan group the step ran for. */
33
+ group?: number;
34
+ /** A row written before groups replaced sub-plans; read as its group. */
26
35
  subPlan?: number;
27
36
  failures?: number;
28
37
  strategy?: "STANDARD" | "PIVOT" | "FINAL";
@@ -44,7 +53,8 @@ export type StatusEvent =
44
53
  | { type: "workflow-started"; workflow: string; at: string }
45
54
  | ({ type: "step-done"; workflow: string } & Step)
46
55
  | ({ type: "workflow-meta"; workflow: string; at: string } & Record<string, unknown>)
47
- | { type: "workflow-done"; workflow: string; at: string }
56
+ // `parentSha`: HEAD at close, the run's join key (`run.parentSha` on its ledger rows).
57
+ | { type: "workflow-done"; workflow: string; at: string; parentSha?: string }
48
58
  | { type: "workflow-failed"; workflow: string; at: string };
49
59
 
50
60
  // Identity for de-dup under union merge. `step-done` is unique per
@@ -142,26 +152,26 @@ export function lastRun(runs: WorkflowRun[], workflow: string): WorkflowRun | un
142
152
 
143
153
  export interface StepFilter {
144
154
  step: string;
145
- subPlan?: number;
155
+ group?: number;
146
156
  }
147
157
 
148
158
  const matches = (s: Step, f: StepFilter) =>
149
- s.step === f.step && s.status === "DONE" && (f.subPlan === undefined || s.subPlan === f.subPlan);
159
+ s.step === f.step &&
160
+ s.status === "DONE" &&
161
+ (f.group === undefined || (s.group ?? s.subPlan) === f.group);
150
162
 
151
- /**
152
- * DONE rows for the step in the active run of `workflow`. `since` names a run
153
- * field holding a timestamp (SOAK's `soakEntryAt`): only rows after it count.
154
- */
155
- export function activeDoneSteps(
156
- runs: WorkflowRun[],
157
- workflow: string,
158
- f: StepFilter,
159
- since?: string,
160
- ): Step[] {
163
+ /** DONE rows for the step in the active run of `workflow`. */
164
+ export function activeDoneSteps(runs: WorkflowRun[], workflow: string, f: StepFilter): Step[] {
161
165
  const run = lastRun(runs, workflow);
162
166
  if (!run) return [];
163
- const floor = since === undefined ? undefined : String(run[since] ?? "");
164
- return run.steps.filter((s) => matches(s, f) && (floor === undefined || s.at > floor));
167
+ return run.steps.filter((s) => matches(s, f));
168
+ }
169
+
170
+ /** DONE rows for the step across ALL runs of `workflow`: debug's limits span every run. */
171
+ export function allRunsDoneSteps(runs: WorkflowRun[], workflow: string, f: StepFilter): Step[] {
172
+ return runs
173
+ .filter((r) => r.workflow === workflow)
174
+ .flatMap((r) => r.steps.filter((s) => matches(s, f)));
165
175
  }
166
176
 
167
177
  /** The last DONE row for the step across ALL runs of `workflow`. */
@@ -204,6 +214,73 @@ export function runOrStepField(runs: WorkflowRun[], workflow: string, field: str
204
214
  return fromStep === undefined ? "" : String(fromStep);
205
215
  }
206
216
 
217
+ // ---------------------------------------------------------------------------
218
+ // engine-action rows — an engine action unsafe to repeat (a tracker comment, a
219
+ // marker commit, a CI re-trigger, a PR open) records itself here and is checked
220
+ // first, so a re-run of the same block does not do it twice. Actions safe to
221
+ // repeat (a label already set) record nothing. The fold and every status reader
222
+ // skip the type.
223
+ // ---------------------------------------------------------------------------
224
+
225
+ export const ENGINE_ACTION = "engine-action";
226
+
227
+ export type EngineActionRow = {
228
+ type: typeof ENGINE_ACTION;
229
+ /** What was done: `comment`, `commit`, `dispatch`, `pr-open`, … */
230
+ action: string;
231
+ /** The moment: workflow, run, step, plan group, attempt and kind, joined by `/`. */
232
+ key: string;
233
+ /** sha256 of the body or payload acted on. */
234
+ hash: string;
235
+ /** What the action made: comment URL, commit SHA, run id; null when it names none. */
236
+ ref: string | null;
237
+ at: string;
238
+ };
239
+
240
+ /** The `key` of an engine-action row: its parts joined by `/`, an absent part as `-`. */
241
+ export const actionKey = (...parts: Array<string | number | undefined | null>): string =>
242
+ parts.map((p) => (p === undefined || p === null || p === "" ? "-" : String(p))).join("/");
243
+
244
+ /** sha256 hex of an action's body or payload. */
245
+ export const actionHash = (payload: string): string =>
246
+ createHash("sha256").update(payload).digest("hex");
247
+
248
+ /** The engine-action rows of `file`; a missing file or a malformed line reads as none. */
249
+ function engineActions(file: string): EngineActionRow[] {
250
+ if (!fs.existsSync(file)) return [];
251
+ const out: EngineActionRow[] = [];
252
+ for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
253
+ if (line.trim() === "") continue;
254
+ const parsed = parseJson(line);
255
+ if (!parsed.ok) continue;
256
+ const r = parsed.value as Partial<EngineActionRow> | null;
257
+ if (r?.type === ENGINE_ACTION && typeof r.key === "string" && typeof r.hash === "string")
258
+ out.push(r as EngineActionRow);
259
+ }
260
+ return out;
261
+ }
262
+
263
+ /**
264
+ * The row recording this action already done (same key, same hash), or undefined.
265
+ * Same key with a different hash is a deliberate edit: act again.
266
+ */
267
+ export function alreadyDone(file: string, key: string, hash: string): EngineActionRow | undefined {
268
+ return engineActions(file)
269
+ .filter((r) => r.key === key && r.hash === hash)
270
+ .at(-1);
271
+ }
272
+
273
+ /** Append the engine-action row for an action just done; returns the row. */
274
+ export function recordAction(
275
+ file: string,
276
+ a: { action: string; key: string; hash: string; ref: string | null },
277
+ ): EngineActionRow {
278
+ const row: EngineActionRow = { type: ENGINE_ACTION, ...a, at: statusTimestamp() };
279
+ fs.mkdirSync(path.dirname(file), { recursive: true });
280
+ fs.appendFileSync(file, appendLine(row));
281
+ return row;
282
+ }
283
+
207
284
  export type Strategy = NonNullable<Step["strategy"]>;
208
285
 
209
286
  /** Next rung: none -> STANDARD -> PIVOT -> FINAL, and FINAL stays FINAL. */