@cbartens/bkit 5.5.0 → 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 (297) 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 +51 -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 +20 -20
  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 +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  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 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  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 +10 -7
  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 +427 -105
  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 +59 -7
  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 +276 -22
  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 +325 -7
  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 +202 -33
  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 +30 -14
  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 +33 -13
  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 +75 -19
  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 +30 -15
  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 +28 -13
  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 +43 -20
  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 +16 -28
  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 +27 -10
  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 +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -11,8 +11,10 @@ import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
11
11
  import { writeNetworkAllowlist } from "../network-allowlist.js";
12
12
  import { parseJson, readJsonFile } from "../../shared/json.js";
13
13
  import { readInstallingVersion } from "../../shared/package-json.js";
14
+ import { ASK_POINTS, CONFIG_DEFAULTS, limitKey } from "../../shared/settings.js";
14
15
  import { getCoreRoot, getSharedRoot, getBkitDocsRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
15
16
  import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_PUSH_GATES, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
17
+ import { migrateLedgers } from "../../ledgers/migrate.js";
16
18
  export function listMdFiles(dir, prefix) {
17
19
  if (!fs.existsSync(dir))
18
20
  return [];
@@ -183,10 +185,11 @@ function runCoreTemplates(dryRun, tokens, ws, logPrefix) {
183
185
  // in-repo without spelunking node_modules. Force-overwritten (Tier 1) — bkit owns
184
186
  // them, so a consumer edit is replaced. Source of truth is the package's own
185
187
  // `.bkit/core/.bkit/<name>`. (`advisories.md` is a regenerated runtime artifact and
186
- // `wording.md` is repo-only tooling — neither belongs here. `LICENSE.md` is the MIT
188
+ // `instructions.md` is repo-only tooling — neither belongs here. `LICENSE.md` is the MIT
187
189
  // notice that travels with the files bkit writes: MIT requires the copyright and
188
190
  // permission notice in every copy.)
189
191
  export const BKIT_CANONICAL_DOCS = [
192
+ "authoring.md",
190
193
  "cloud.md",
191
194
  "comparison.md",
192
195
  "install.md",
@@ -232,6 +235,27 @@ export function runBkitDocs(dryRun, tokens, ws, logPrefix) {
232
235
  }
233
236
  migrateShortcutsToLite(dryRun, ws, logPrefix);
234
237
  migrateRetiredDevLock(dryRun, ws, logPrefix);
238
+ migrateLedgerSchema(dryRun, ws, logPrefix);
239
+ migrateJiraKeyName(dryRun, logPrefix);
240
+ }
241
+ // Migration (installs up to 5.5.x, `docs/migrations.md`): the Jira key was
242
+ // `BKIT_JIRA_API_TOKEN`; the engine and the MCP configs now read `BKIT_JIRA_API_KEY`.
243
+ // `.bkit/.env` lines naming the old key are renamed in place, value kept. Logged only,
244
+ // never recorded in ws: a ws write gets a canonical hash, and a secrets file never does.
245
+ // A file already naming the new key is left alone.
246
+ const ENV_FILE = path.join(".bkit", ".env");
247
+ const OLD_JIRA_KEY = "BKIT_JIRA_API_TOKEN";
248
+ const NEW_JIRA_KEY = "BKIT_JIRA_API_KEY";
249
+ export function migrateJiraKeyName(dryRun, logPrefix) {
250
+ if (!fs.lstatSync(ENV_FILE, { throwIfNoEntry: false })?.isFile())
251
+ return;
252
+ const text = fs.readFileSync(ENV_FILE, "utf-8");
253
+ const assigns = (key) => new RegExp(`^\\s*(export\\s+)?${key}=`, "m").test(text);
254
+ if (!assigns(OLD_JIRA_KEY) || assigns(NEW_JIRA_KEY))
255
+ return;
256
+ if (!dryRun)
257
+ fs.writeFileSync(ENV_FILE, text.split(OLD_JIRA_KEY).join(NEW_JIRA_KEY), "utf-8");
258
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: ${ENV_FILE} — ${OLD_JIRA_KEY} renamed to ${NEW_JIRA_KEY}`);
235
259
  }
236
260
  // Migration (5.1.0 – 5.2.4 installs, `docs/migrations.md`): the lite workflows lived at
237
261
  // `.agents/shortcuts.md`. The consumer's own lines below `bkit:end` (minus the seeded
@@ -281,6 +305,17 @@ export function migrateRetiredDevLock(dryRun, ws, logPrefix) {
281
305
  ws.writes.push({ path: RETIRED_DEV_LOCK, action: "write" });
282
306
  console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: removed ${RETIRED_DEV_LOCK} (the dev lock is gone)`);
283
307
  }
308
+ // Migration (installs up to 5.5.x, `docs/migrations.md`): ledger rows written before
309
+ // `schema: 2` are rewritten into the current shape (`.bkit/jsonl.md` § Generic Fields).
310
+ // Recorded in ws so `bkit check` fails until upgrade runs; ledgers never get a
311
+ // canonical hash (`mergeCanonicalHashes`).
312
+ export function migrateLedgerSchema(dryRun, ws, logPrefix) {
313
+ for (const { file, rewritten, dropped } of migrateLedgers(process.cwd(), dryRun)) {
314
+ ws.writes.push({ path: file, action: "update" });
315
+ const copies = dropped > 0 ? `, ${dropped} old copy(ies) of rewritten rows dropped` : "";
316
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: ${file} — ${rewritten} row(s) rewritten to schema 2${copies}`);
317
+ }
318
+ }
284
319
  // ---------------------------------------------------------------------------
285
320
  // Source-rendered host outputs — agents (.agents/prompts source) and commands
286
321
  // (.bkit/workflows source). Extracted from the host module functions so BOTH
@@ -318,8 +353,296 @@ export function seedCorePackageJsonScripts(ctx) {
318
353
  if (migrateLinearTeamKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
319
354
  written.push("package.json");
320
355
  }
356
+ if (migrateGithubProjectKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
357
+ written.push("package.json");
358
+ }
359
+ if (migrateBkitLayout(dryRun, ws, logPrefix) && !written.includes("package.json")) {
360
+ written.push("package.json");
361
+ }
362
+ if (seedBkitDefaults(dryRun, ws, logPrefix) && !written.includes("package.json")) {
363
+ written.push("package.json");
364
+ }
321
365
  return written;
322
366
  }
367
+ /**
368
+ * Every `bkit.*` setting, written on every install and upgrade so consumers see them all;
369
+ * add-if-missing, nested blocks included. A key with a default gets it; a choice not made
370
+ * yet is `""` or `[]`, which every reader treats as unset.
371
+ */
372
+ export const SEEDED_BKIT_DEFAULTS = {
373
+ tracker: {
374
+ default: "",
375
+ github: {
376
+ project: "",
377
+ progress: CONFIG_DEFAULTS.github.progress,
378
+ review: CONFIG_DEFAULTS.github.review,
379
+ },
380
+ linear: {
381
+ team: "",
382
+ project: "",
383
+ progress: CONFIG_DEFAULTS.linear.progress,
384
+ review: CONFIG_DEFAULTS.linear.review,
385
+ },
386
+ jira: {
387
+ site: "",
388
+ project: "",
389
+ progress: CONFIG_DEFAULTS.jira.progress,
390
+ review: CONFIG_DEFAULTS.jira.review,
391
+ },
392
+ },
393
+ cloud: { agent: "" },
394
+ providers: { opencode: { default: "", installed: [] } },
395
+ testing: {
396
+ ciWorkflow: CONFIG_DEFAULTS.ciWorkflow,
397
+ ciCapstone: CONFIG_DEFAULTS.capstoneJob,
398
+ shipGate: [...CONFIG_DEFAULTS.shipGateRequiredLanes],
399
+ minPushPaths: [...CONFIG_DEFAULTS.minPushPaths],
400
+ },
401
+ workflows: {
402
+ minFreeGb: CONFIG_DEFAULTS.diskMinFreeGb,
403
+ worktree: { copy: [...CONFIG_DEFAULTS.worktreeCopy], install: CONFIG_DEFAULTS.worktreeInstall },
404
+ tasks: { ...CONFIG_DEFAULTS.tasks },
405
+ ...askBlocks(),
406
+ },
407
+ // bkit-utility-update-roadmap list length; the prompt falls back to 25 too.
408
+ prompts: { roadmapNext: 25 },
409
+ dependencies: { updater: "" },
410
+ advisories: { ignore: [] },
411
+ };
412
+ /** `{design: {grill: {ask, maxTurns}}, build: {...}, ...}`, from `CONFIG_DEFAULTS.asks`. */
413
+ function askBlocks() {
414
+ const out = {};
415
+ for (const point of ASK_POINTS) {
416
+ const [workflow, name] = point.split(".");
417
+ const d = CONFIG_DEFAULTS.asks[point];
418
+ (out[workflow] ??= {})[name] = { ask: d.ask, [limitKey(point)]: d.max };
419
+ }
420
+ return out;
421
+ }
422
+ const plainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
423
+ // Copy each `defaults` key missing from `target`, descending into blocks both sides hold.
424
+ // A present key keeps its value, whatever it is. Pushes each added key's dotted path.
425
+ function addMissingKeys(target, defaults, prefix, added) {
426
+ for (const [k, v] of Object.entries(defaults)) {
427
+ if (!Object.prototype.hasOwnProperty.call(target, k)) {
428
+ target[k] = structuredClone(v);
429
+ added.push(`${prefix}${k}`);
430
+ }
431
+ else if (plainObject(v) && plainObject(target[k])) {
432
+ addMissingKeys(target[k], v, `${prefix}${k}.`, added);
433
+ }
434
+ }
435
+ }
436
+ // Add each SEEDED_BKIT_DEFAULTS key missing from `package.json` `bkit`, creating the block
437
+ // when absent. Runs after the legacy-key migrations, which test `=== undefined`. Returns
438
+ // true when package.json changed.
439
+ export function seedBkitDefaults(dryRun, ws, logPrefix) {
440
+ const pkgPath = "package.json";
441
+ if (!fs.existsSync(pkgPath))
442
+ return false;
443
+ const raw = fs.readFileSync(pkgPath, "utf-8");
444
+ const parsed = parseJson(raw);
445
+ if (!parsed.ok)
446
+ return false;
447
+ const pkg = parsed.value;
448
+ if (pkg.bkit !== undefined && !plainObject(pkg.bkit))
449
+ return false;
450
+ const cfg = (pkg.bkit ?? {});
451
+ const added = [];
452
+ addMissingKeys(cfg, SEEDED_BKIT_DEFAULTS, "bkit.", added);
453
+ if (added.length === 0)
454
+ return false;
455
+ pkg.bkit = cfg;
456
+ ws.writes.push({ path: pkgPath, action: "update" });
457
+ if (!dryRun)
458
+ writePackageJsonLike(raw, pkg);
459
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: added ${added.join(", ")} to package.json`);
460
+ return true;
461
+ }
462
+ /** Rewrite package.json with `pkg`, keeping the file's indent and trailing newline. */
463
+ function writePackageJsonLike(raw, pkg) {
464
+ const indentMatch = raw.match(/\n([ \t]+)"/);
465
+ const indent = indentMatch ? indentMatch[1] : " ";
466
+ const trailingNewline = raw.endsWith("\n") ? "\n" : "";
467
+ fs.writeFileSync("package.json", JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
468
+ }
469
+ // Status option ids of GitHub's Kanban and Team planning board templates; every board
470
+ // made from one carries the same ids.
471
+ const TEMPLATE_STATUS_OPTIONS = {
472
+ "47fc9ee4": "In progress",
473
+ df73e18b: "In review",
474
+ };
475
+ // Migration (up to 5.4.x installs, `docs/migrations.md`): the board lived at
476
+ // `bkit.githubProject` as `{owner, number, statusFieldId, *OptionId}`, org boards only; it
477
+ // is `bkit.github.project`, the board URL, with Status set by option name from
478
+ // `bkit.github.progress` / `review`. An existing `bkit.github.project` wins over the old
479
+ // key. Returns true when package.json changed.
480
+ export function migrateGithubProjectKey(dryRun, ws, logPrefix) {
481
+ const pkgPath = "package.json";
482
+ if (!fs.existsSync(pkgPath))
483
+ return false;
484
+ const raw = fs.readFileSync(pkgPath, "utf-8");
485
+ const parsed = parseJson(raw);
486
+ if (!parsed.ok)
487
+ return false;
488
+ const pkg = parsed.value;
489
+ const bkit = pkg.bkit;
490
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit))
491
+ return false;
492
+ const cfg = bkit;
493
+ if (!Object.prototype.hasOwnProperty.call(cfg, "githubProject"))
494
+ return false;
495
+ const old = cfg.githubProject;
496
+ const github = cfg.github !== null && typeof cfg.github === "object" && !Array.isArray(cfg.github)
497
+ ? cfg.github
498
+ : {};
499
+ const unnamed = [];
500
+ if (github.project === undefined) {
501
+ if (old === false)
502
+ github.project = false;
503
+ else if (old !== null && typeof old === "object" && !Array.isArray(old)) {
504
+ const board = old;
505
+ const owner = typeof board.owner === "string" ? board.owner.trim() : "";
506
+ const number = Number(board.number);
507
+ if (owner !== "" && Number.isInteger(number) && number > 0) {
508
+ github.project = `https://github.com/orgs/${owner}/projects/${number}`;
509
+ for (const [moment, key] of [
510
+ ["progress", "progressOptionId"],
511
+ ["review", "reviewOptionId"],
512
+ ]) {
513
+ const id = board[key];
514
+ if (typeof id !== "string" || id.trim() === "")
515
+ continue;
516
+ const name = TEMPLATE_STATUS_OPTIONS[id.trim()];
517
+ if (name === undefined)
518
+ unnamed.push(moment);
519
+ else if (github[moment] === undefined && name !== CONFIG_DEFAULTS.github[moment])
520
+ github[moment] = name;
521
+ }
522
+ }
523
+ }
524
+ }
525
+ delete cfg.githubProject;
526
+ if (Object.keys(github).length > 0)
527
+ cfg.github = github;
528
+ ws.writes.push({ path: pkgPath, action: "update" });
529
+ if (!dryRun)
530
+ writePackageJsonLike(raw, pkg);
531
+ const tag = dryRun ? "[dry-run] " : "";
532
+ console.log(`${logPrefix} ${tag}core: moved bkit.githubProject to bkit.github in package.json`);
533
+ for (const moment of unnamed)
534
+ console.log(`${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]}")`);
535
+ return true;
536
+ }
537
+ // Migration (up to 5.5.x installs, `docs/migrations.md`): `bkit` settings sat flat; they
538
+ // are grouped into named sections. Each old key moves to its new path; a value already at
539
+ // the new path wins, and two blocks merge key by key. `loopPause: true|false` becomes
540
+ // `ask` on every point under `workflows.<workflow>`, where an `ask` already set wins.
541
+ // Runs after the linearTeam and githubProject moves, which write the flat keys. Returns
542
+ // true when package.json changed.
543
+ export const BKIT_LAYOUT_MOVES = [
544
+ ["issueTracker", "tracker.default"],
545
+ ["github", "tracker.github"],
546
+ ["linear", "tracker.linear"],
547
+ ["jira", "tracker.jira"],
548
+ ["cloudAgents", "cloud.agent"],
549
+ ["opencodeProvider", "providers.opencode.default"],
550
+ ["opencodeProviders", "providers.opencode.installed"],
551
+ ["minPushPaths", "testing.minPushPaths"],
552
+ ["capstoneJob", "testing.ciCapstone"],
553
+ ["ciWorkflow", "testing.ciWorkflow"],
554
+ ["shipGateRequiredLanes", "testing.shipGate"],
555
+ ["disk.minFreeGb", "workflows.minFreeGb"],
556
+ ["worktree", "workflows.worktree"],
557
+ ["tasks", "workflows.tasks"],
558
+ ["roadmapNext", "prompts.roadmapNext"],
559
+ ["depUpdater", "dependencies.updater"],
560
+ ["ignoreAdvisories", "advisories.ignore"],
561
+ ];
562
+ // Fill `into` with each `from` key it lacks, descending into blocks both sides hold.
563
+ function mergeMissing(into, from) {
564
+ for (const [k, v] of Object.entries(from)) {
565
+ if (into[k] === undefined)
566
+ into[k] = v;
567
+ else if (plainObject(v) && plainObject(into[k]))
568
+ mergeMissing(into[k], v);
569
+ }
570
+ }
571
+ export function migrateBkitLayout(dryRun, ws, logPrefix) {
572
+ const pkgPath = "package.json";
573
+ if (!fs.existsSync(pkgPath))
574
+ return false;
575
+ const raw = fs.readFileSync(pkgPath, "utf-8");
576
+ const parsed = parseJson(raw);
577
+ if (!parsed.ok)
578
+ return false;
579
+ const pkg = parsed.value;
580
+ if (!plainObject(pkg.bkit))
581
+ return false;
582
+ const cfg = pkg.bkit;
583
+ const moved = [];
584
+ for (const [from, to] of BKIT_LAYOUT_MOVES) {
585
+ const fromPath = from.split(".");
586
+ const fromParent = fromPath
587
+ .slice(0, -1)
588
+ .reduce((o, k) => (plainObject(o) ? o[k] : undefined), cfg);
589
+ const fromKey = fromPath[fromPath.length - 1];
590
+ if (!plainObject(fromParent) || !Object.prototype.hasOwnProperty.call(fromParent, fromKey))
591
+ continue;
592
+ const old = fromParent[fromKey];
593
+ const toPath = to.split(".");
594
+ let parent = cfg;
595
+ let blocked = false;
596
+ for (const k of toPath.slice(0, -1)) {
597
+ if (parent[k] === undefined)
598
+ parent[k] = {};
599
+ if (!plainObject(parent[k])) {
600
+ blocked = true;
601
+ break;
602
+ }
603
+ parent = parent[k];
604
+ }
605
+ // A non-object where the new section belongs: leave the old key for `bkit check` to show.
606
+ if (blocked)
607
+ continue;
608
+ const toKey = toPath[toPath.length - 1];
609
+ if (parent[toKey] === undefined)
610
+ parent[toKey] = old;
611
+ else if (plainObject(parent[toKey]) && plainObject(old))
612
+ mergeMissing(parent[toKey], old);
613
+ delete fromParent[fromKey];
614
+ if (fromParent !== cfg && Object.keys(fromParent).length === 0)
615
+ delete cfg[fromPath[0]];
616
+ moved.push(`bkit.${from} -> bkit.${to}`);
617
+ }
618
+ if (Object.prototype.hasOwnProperty.call(cfg, "loopPause")) {
619
+ const old = cfg.loopPause;
620
+ if (typeof old === "boolean") {
621
+ if (cfg.workflows === undefined)
622
+ cfg.workflows = {};
623
+ if (plainObject(cfg.workflows))
624
+ mergeMissing(cfg.workflows, askOnly(old));
625
+ }
626
+ delete cfg.loopPause;
627
+ moved.push("bkit.loopPause -> bkit.workflows.<workflow>.<point>.ask");
628
+ }
629
+ if (moved.length === 0)
630
+ return false;
631
+ ws.writes.push({ path: pkgPath, action: "update" });
632
+ if (!dryRun)
633
+ writePackageJsonLike(raw, pkg);
634
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved ${moved.join(", ")} in package.json`);
635
+ return true;
636
+ }
637
+ /** `{design: {grill: {ask}}, build: {verify: {ask}, ...}, ...}` with every `ask` = `ask`. */
638
+ function askOnly(ask) {
639
+ const out = {};
640
+ for (const point of ASK_POINTS) {
641
+ const [workflow, name] = point.split(".");
642
+ (out[workflow] ??= {})[name] = { ask };
643
+ }
644
+ return out;
645
+ }
323
646
  // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
324
647
  // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
325
648
  // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
@@ -348,12 +671,8 @@ export function migrateLinearTeamKey(dryRun, ws, logPrefix) {
348
671
  if (Object.keys(linear).length > 0)
349
672
  cfg.linear = linear;
350
673
  ws.writes.push({ path: pkgPath, action: "update" });
351
- if (!dryRun) {
352
- const indentMatch = raw.match(/\n([ \t]+)"/);
353
- const indent = indentMatch ? indentMatch[1] : " ";
354
- const trailingNewline = raw.endsWith("\n") ? "\n" : "";
355
- fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
356
- }
674
+ if (!dryRun)
675
+ writePackageJsonLike(raw, pkg);
357
676
  console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved bkit.linearTeam to bkit.linear.team in package.json`);
358
677
  return true;
359
678
  }
@@ -121,7 +121,7 @@ export function detectOpencodeYmlProviderDrift(cwd) {
121
121
  const ymlPath = path.join(cwd, ".github", "workflows", "opencode.yml");
122
122
  if (!fs.existsSync(ymlPath))
123
123
  return null;
124
- // The installed provider — package.json `bkit.opencodeProvider` is the authoritative record
124
+ // The installed provider — package.json `bkit.providers.opencode.default` is the authoritative record
125
125
  // written on install. Absent/broken/unsupported → the null-guard below skips silently.
126
126
  const provider = readBkitConfig(cwd).opencodeProvider;
127
127
  if (!provider)
@@ -216,7 +216,7 @@ export function renderOpencodeJson(templatePath, tracker, provider, cwd = proces
216
216
  // Same "oauth": false reason as github: the API token in the header is the only auth
217
217
  // bkit wires, so a bad one fails as a 401, not as an OAuth sign-in prompt.
218
218
  mcpEntry =
219
- '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_TOKEN}" } }';
219
+ '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_KEY}" } }';
220
220
  }
221
221
  else {
222
222
  mcpEntry = "";
@@ -15,6 +15,7 @@ import * as path from "node:path";
15
15
  import * as crypto from "node:crypto";
16
16
  import { parseJson } from "../shared/json.js";
17
17
  import { getTemplatesRoot, templateRelPath } from "../shared/package-roots.js";
18
+ import { isSchemaLedger } from "../ledgers/migrate.js";
18
19
  // ---------------------------------------------------------------------------
19
20
  // Parse
20
21
  // ---------------------------------------------------------------------------
@@ -131,13 +132,16 @@ export function mergeCanonicalHashes(cwd, existing, fresh, removing = []) {
131
132
  for (const [relPath, hash] of Object.entries(existing)) {
132
133
  if (!fs.existsSync(path.join(cwd, relPath)) ||
133
134
  isRemoving(relPath) ||
134
- isTemplateSetPath(relPath)) {
135
+ isTemplateSetPath(relPath) ||
136
+ isSchemaLedger(relPath)) {
135
137
  pruned++;
136
138
  continue;
137
139
  }
138
140
  canonicalHashes[relPath] = hash;
139
141
  }
140
- return { canonicalHashes: { ...canonicalHashes, ...fresh }, pruned };
142
+ // A ledger is append-only data a migration may rewrite, never a managed file.
143
+ const kept = Object.fromEntries(Object.entries(fresh).filter(([p]) => !isSchemaLedger(p)));
144
+ return { canonicalHashes: { ...canonicalHashes, ...kept }, pruned };
141
145
  }
142
146
  /** True when `dest` is a member of the package's copy-and-own template set. */
143
147
  function isTemplateSetPath(dest) {
@@ -0,0 +1,81 @@
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
+ import * as fs from "node:fs";
8
+ import * as path from "node:path";
9
+ import { parseJson } from "../shared/json.js";
10
+ import { normalize } from "./telemetry.js";
11
+ /** Every repo ledger whose rows carry the shared top section (`.bkit/jsonl.md`). */
12
+ export const SCHEMA_LEDGERS = [
13
+ ".bkit/stats.jsonl",
14
+ ".bkit/friction.jsonl",
15
+ ".bkit/issues.jsonl",
16
+ "docs/decisions.jsonl",
17
+ "docs/deferrals.jsonl",
18
+ "docs/failures.jsonl",
19
+ "docs/knowledge.jsonl",
20
+ ];
21
+ /** True for a repo ledger path: append-only data, never a bkit-managed file. */
22
+ export const isSchemaLedger = (relPath) => SCHEMA_LEDGERS.includes(relPath.split(path.sep).join("/"));
23
+ /** A line's row when it is a JSON object, else undefined. */
24
+ function rowOf(body) {
25
+ const parsed = parseJson(body);
26
+ const row = parsed.ok ? parsed.value : undefined;
27
+ return row !== null && typeof row === "object" && !Array.isArray(row)
28
+ ? row
29
+ : undefined;
30
+ }
31
+ /**
32
+ * `text` with every pre-schema row rewritten; `rewritten` counts the lines changed.
33
+ * A pre-schema row whose rewrite is already a schema line of `text` is dropped and
34
+ * counted in `dropped`: it is that row's copy from an unmigrated branch.
35
+ */
36
+ export function migrateLedgerText(text) {
37
+ let rewritten = 0;
38
+ let dropped = 0;
39
+ const bodies = text.split("\n").map((line) => line.replace(/\r$/, ""));
40
+ const present = new Set(bodies.filter((b) => rowOf(b)?.["schema"] !== undefined));
41
+ const lines = text.split("\n").flatMap((line, i) => {
42
+ const body = bodies[i] ?? "";
43
+ if (body.trim() === "")
44
+ return [line];
45
+ const row = rowOf(body);
46
+ if (row === undefined || row["schema"] !== undefined)
47
+ return [line];
48
+ const next = JSON.stringify(normalize(row));
49
+ if (present.has(next)) {
50
+ dropped++;
51
+ return [];
52
+ }
53
+ rewritten++;
54
+ return [next + line.slice(body.length)];
55
+ });
56
+ return { text: lines.join("\n"), rewritten, dropped };
57
+ }
58
+ /**
59
+ * Rewrite (or drop, as {@link migrateLedgerText} does) the pre-schema rows of every {@link SCHEMA_LEDGERS} file under `root`;
60
+ * with `dryRun`, only count them. Returns the files that have (or had) such rows,
61
+ * with their line counts. Writes via temp file + rename, so an interrupted run
62
+ * never leaves a torn ledger.
63
+ */
64
+ export function migrateLedgers(root, dryRun) {
65
+ const out = [];
66
+ for (const file of SCHEMA_LEDGERS) {
67
+ const abs = path.join(root, file);
68
+ if (!fs.lstatSync(abs, { throwIfNoEntry: false })?.isFile())
69
+ continue;
70
+ const { text, rewritten, dropped } = migrateLedgerText(fs.readFileSync(abs, "utf-8"));
71
+ if (rewritten + dropped === 0)
72
+ continue;
73
+ if (!dryRun) {
74
+ const tmp = `${abs}.bkit-migrate.tmp`;
75
+ fs.writeFileSync(tmp, text, "utf-8");
76
+ fs.renameSync(tmp, abs);
77
+ }
78
+ out.push({ file, rewritten, dropped });
79
+ }
80
+ return out;
81
+ }
@@ -14,6 +14,10 @@
14
14
  // `parentSha` is captured at step START via `git rev-parse HEAD`, BEFORE the
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
+ import { createHash } from "node:crypto";
18
+ import * as fs from "node:fs";
19
+ import * as path from "node:path";
20
+ import { parseJson } from "../shared/json.js";
17
21
  // Identity for de-dup under union merge. `step-done` is unique per
18
22
  // (workflow, step, parentSha, at); workflow-level events per (type, workflow, at).
19
23
  function identity(e) {
@@ -101,17 +105,21 @@ export function lastRun(runs, workflow) {
101
105
  const i = lastIndexOfWorkflow(runs, workflow);
102
106
  return i < 0 ? undefined : runs[i];
103
107
  }
104
- const matches = (s, f) => s.step === f.step && s.status === "DONE" && (f.subPlan === undefined || s.subPlan === f.subPlan);
105
- /**
106
- * DONE rows for the step in the active run of `workflow`. `since` names a run
107
- * field holding a timestamp (SOAK's `soakEntryAt`): only rows after it count.
108
- */
109
- export function activeDoneSteps(runs, workflow, f, since) {
108
+ const matches = (s, f) => s.step === f.step &&
109
+ s.status === "DONE" &&
110
+ (f.group === undefined || (s.group ?? s.subPlan) === f.group);
111
+ /** DONE rows for the step in the active run of `workflow`. */
112
+ export function activeDoneSteps(runs, workflow, f) {
110
113
  const run = lastRun(runs, workflow);
111
114
  if (!run)
112
115
  return [];
113
- const floor = since === undefined ? undefined : String(run[since] ?? "");
114
- return run.steps.filter((s) => matches(s, f) && (floor === undefined || s.at > floor));
116
+ return run.steps.filter((s) => matches(s, f));
117
+ }
118
+ /** DONE rows for the step across ALL runs of `workflow`: debug's limits span every run. */
119
+ export function allRunsDoneSteps(runs, workflow, f) {
120
+ return runs
121
+ .filter((r) => r.workflow === workflow)
122
+ .flatMap((r) => r.steps.filter((s) => matches(s, f)));
115
123
  }
116
124
  /** The last DONE row for the step across ALL runs of `workflow`. */
117
125
  export function lastDoneStepAllRuns(runs, workflow, f) {
@@ -148,6 +156,51 @@ export function runOrStepField(runs, workflow, field) {
148
156
  .at(-1);
149
157
  return fromStep === undefined ? "" : String(fromStep);
150
158
  }
159
+ // ---------------------------------------------------------------------------
160
+ // engine-action rows — an engine action unsafe to repeat (a tracker comment, a
161
+ // marker commit, a CI re-trigger, a PR open) records itself here and is checked
162
+ // first, so a re-run of the same block does not do it twice. Actions safe to
163
+ // repeat (a label already set) record nothing. The fold and every status reader
164
+ // skip the type.
165
+ // ---------------------------------------------------------------------------
166
+ export const ENGINE_ACTION = "engine-action";
167
+ /** The `key` of an engine-action row: its parts joined by `/`, an absent part as `-`. */
168
+ export const actionKey = (...parts) => parts.map((p) => (p === undefined || p === null || p === "" ? "-" : String(p))).join("/");
169
+ /** sha256 hex of an action's body or payload. */
170
+ export const actionHash = (payload) => createHash("sha256").update(payload).digest("hex");
171
+ /** The engine-action rows of `file`; a missing file or a malformed line reads as none. */
172
+ function engineActions(file) {
173
+ if (!fs.existsSync(file))
174
+ return [];
175
+ const out = [];
176
+ for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
177
+ if (line.trim() === "")
178
+ continue;
179
+ const parsed = parseJson(line);
180
+ if (!parsed.ok)
181
+ continue;
182
+ const r = parsed.value;
183
+ if (r?.type === ENGINE_ACTION && typeof r.key === "string" && typeof r.hash === "string")
184
+ out.push(r);
185
+ }
186
+ return out;
187
+ }
188
+ /**
189
+ * The row recording this action already done (same key, same hash), or undefined.
190
+ * Same key with a different hash is a deliberate edit: act again.
191
+ */
192
+ export function alreadyDone(file, key, hash) {
193
+ return engineActions(file)
194
+ .filter((r) => r.key === key && r.hash === hash)
195
+ .at(-1);
196
+ }
197
+ /** Append the engine-action row for an action just done; returns the row. */
198
+ export function recordAction(file, a) {
199
+ const row = { type: ENGINE_ACTION, ...a, at: statusTimestamp() };
200
+ fs.mkdirSync(path.dirname(file), { recursive: true });
201
+ fs.appendFileSync(file, appendLine(row));
202
+ return row;
203
+ }
151
204
  /** Next rung: none -> STANDARD -> PIVOT -> FINAL, and FINAL stays FINAL. */
152
205
  export function nextStrategy(prior) {
153
206
  if (prior === undefined)