@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
@@ -11,6 +11,7 @@ import * as fs from "node:fs";
11
11
  import * as path from "node:path";
12
12
 
13
13
  import { CommandError, EXIT, type CommandSpec, type FlagSpec, type RunContext } from "../lib.js";
14
+ import { COMMENT_FILE_OUTPUT, GENERATED_MARKER, commentFileOf, stampMarker } from "./tracker.js";
14
15
 
15
16
  /** Exit code: no workstream parsed — the workflow's Failure Path. */
16
17
  export const EXIT_NONE = 3;
@@ -91,14 +92,15 @@ export function commentBody(
91
92
  ): string {
92
93
  const doc = `docs/plans/${opts.month}/${opts.fid}-design.md`;
93
94
  const url = `https://github.com/${opts.ownerRepo}/blob/dev/${doc}`;
94
- return [
95
- "###### bkit:generated",
95
+ const lines = [
96
+ GENERATED_MARKER,
96
97
  "### Step 11 — Suggested Workstreams",
97
98
  "Advisory only. NEVER auto-trigger.",
98
99
  ...ws.map((w) => `- ${w.id}: ${w.name}. Requires: ${requiresList(w)}`),
99
100
  `Filing one issue per workstream: put \`**Parent design:** [${opts.fid}-design.md](${url})\` in its body, and list the issues it requires in a blocked-by block (.bkit/trackers.md § Issue shapes).`,
100
101
  `[${doc}](${url})`,
101
- ].join("\n");
102
+ ];
103
+ return stampMarker(lines.join("\n"));
102
104
  }
103
105
 
104
106
  const ARTIFACT_FLAG: FlagSpec = {
@@ -149,7 +151,11 @@ export const workstreamsCommand: CommandSpec = {
149
151
  help: "owner/repo for the design doc link",
150
152
  },
151
153
  ],
152
- output: { comment: "the comment body", workstreams: "the parsed workstreams" },
154
+ output: {
155
+ comment: "the comment body",
156
+ commentFile: COMMENT_FILE_OUTPUT,
157
+ workstreams: "the parsed workstreams",
158
+ },
153
159
  exitCodes: { [EXIT_NONE]: "no workstream parsed (Failure Path)" },
154
160
  run: (ctx) => {
155
161
  const workstreams = read(ctx);
@@ -158,7 +164,7 @@ export const workstreamsCommand: CommandSpec = {
158
164
  month: String(ctx.flags.month),
159
165
  fid: String(ctx.flags.fid),
160
166
  });
161
- ctx.emit({ comment: body, workstreams });
167
+ ctx.emit({ comment: body, commentFile: commentFileOf(ctx.cwd, body), workstreams });
162
168
  return EXIT.OK;
163
169
  },
164
170
  },
@@ -17,6 +17,7 @@ import { spawnSync } from "node:child_process";
17
17
  import * as fs from "node:fs";
18
18
  import * as path from "node:path";
19
19
 
20
+ import { lastRun } from "../../ledgers/status.js";
20
21
  import { gitEnv } from "../../ledgers/telemetry.js";
21
22
  import { readBkitConfig } from "../../shared/settings.js";
22
23
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
@@ -26,13 +27,23 @@ import {
26
27
  EXIT,
27
28
  git,
28
29
  isSharedBranch,
30
+ MAIN,
29
31
  repoRoot,
30
32
  runGit,
31
33
  type CommandSpec,
32
34
  } from "../lib.js";
33
35
  import { ensureDiskSpace } from "./disk.js";
36
+ import {
37
+ listRecords,
38
+ newRecord,
39
+ readRecord,
40
+ removeRecord,
41
+ withSetupGuard,
42
+ writeRecord,
43
+ } from "./ledgers.js";
44
+ import { workflowLockFresh, workflowLockLive } from "./locks.js";
34
45
  import { detect } from "./runtime.js";
35
- import { WORKFLOW_FLAG } from "./status.js";
46
+ import { WORKFLOW_FLAG, readRuns } from "./status.js";
36
47
 
37
48
  const WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
38
49
  const ORIGIN_DEV = `origin/${DEV}`;
@@ -47,6 +58,7 @@ export const EXIT_REBASE_NOT_STARTED = 9;
47
58
  export const EXIT_NOT_A_WORKTREE = 10;
48
59
  export const EXIT_REMOVE = 11;
49
60
  export const EXIT_DISK_FULL = 12;
61
+ export const EXIT_SHARED_BUSY = 13;
50
62
 
51
63
  const FID_FLAG = { name: "fid", type: "string", required: true, help: "feature id" } as const;
52
64
 
@@ -111,6 +123,41 @@ function fetchBranch(cwd: string, branch: string): void {
111
123
  }
112
124
  }
113
125
 
126
+ /**
127
+ * The shared-checkout record for an in-place run on `dev`. Another feature's
128
+ * record with a live workflow lock means that run owns the checkout; one
129
+ * without is left over and removed. The same feature with an open run in
130
+ * `{logDir}/status.jsonl` is a resume and keeps its record; a new run rewrites it.
131
+ */
132
+ function openSharedRecord(root: string, fid: string, workflow: string, logDir: string) {
133
+ const busy = (other: string) =>
134
+ new CommandError(
135
+ EXIT_SHARED_BUSY,
136
+ `${other} is running in this checkout (workflow lock held) — wait for it to finish, then re-run`,
137
+ );
138
+ const guarded = withSetupGuard(root, () => {
139
+ for (const other of listRecords(root)) {
140
+ if (other.fid === fid) continue;
141
+ // A closed run that has not released its lock still pushes and waits for CI.
142
+ if (workflowLockLive(root, other.fid) || workflowLockFresh(root, other.fid)) {
143
+ throw busy(other.fid);
144
+ }
145
+ removeRecord(root, other.fid);
146
+ }
147
+ const existing = readRecord(root, fid);
148
+ const statusFile = path.join(logDir, "status.jsonl");
149
+ const open =
150
+ fs.existsSync(statusFile) &&
151
+ lastRun(readRuns(statusFile), workflow)?.status === "IN_PROGRESS";
152
+ if (existing !== null && existing.branch === DEV && open) return existing;
153
+ const fresh = newRecord(root, fid, DEV);
154
+ writeRecord(root, fresh);
155
+ return fresh;
156
+ });
157
+ if (guarded === null) throw busy("another run");
158
+ return guarded.value;
159
+ }
160
+
114
161
  /** Ship's branch: the one the prompt names, else `feat/{fid}` when it exists, else the session's. */
115
162
  function shipBranch(root: string, fid: string, named: string | undefined, session: string) {
116
163
  if (named) return named;
@@ -185,6 +232,61 @@ function rebaseInProgress(wt: string): boolean {
185
232
  });
186
233
  }
187
234
 
235
+ /**
236
+ * `git add -A` in `tree`, leaving out the `bkit.workflows.worktree.copy` entries setup
237
+ * copies in from the main checkout (`.env` and the like): no bkit commit may
238
+ * carry them, gitignored or not.
239
+ */
240
+ export function addAllButCopied(
241
+ tree: string,
242
+ copied: string[] = readBkitConfig(tree).worktreeCopy,
243
+ ): ReturnType<typeof runGit> {
244
+ const keep = copied.map((e) => `:(exclude)${path.normalize(e)}`);
245
+ return runGit(tree, ["add", "-A", "--", ".", ...keep]);
246
+ }
247
+
248
+ /**
249
+ * Commit what an earlier run left uncommitted in a resumed worktree, so the
250
+ * resume rebase can start: a failed ship's flush lands its record on dev and
251
+ * leaves the worktree as it was, for whatever runs next. An untracked file in a
252
+ * log folder of this feature that `onto` already holds is dropped first: dev's
253
+ * copy, landed by that flush, wins, and a second copy would stop the rebase.
254
+ * The `worktreeCopy` entries setup copies in are never committed. Clean tree →
255
+ * null; a failed commit is narrated and leaves the tree for the rebase to refuse.
256
+ */
257
+ function carryLeftovers(
258
+ wt: string,
259
+ o: { fid: string; onto: string; statusFile: string; copied: string[] },
260
+ log: (m: string) => void,
261
+ ): { sha: string | null; dropped: string[] } | null {
262
+ const dirty = () => (git(wt, ["status", "--porcelain", "--untracked-files=all"]) ?? "") !== "";
263
+ if (!dirty()) return null;
264
+ const logs = new RegExp(`^docs/plans/[^/]+/logs/${o.fid.replace(/\./g, "\\.")}/`);
265
+ const dropped = (git(wt, ["ls-files", "--others", "--exclude-standard"]) ?? "")
266
+ .split("\n")
267
+ .filter((f) => logs.test(f) && runGit(wt, ["cat-file", "-e", `${o.onto}:${f}`]).ok);
268
+ for (const f of dropped) fs.rmSync(path.join(wt, f));
269
+ if (dropped.length > 0)
270
+ log(
271
+ `dropped ${dropped.length} untracked log(s) ${o.onto} already holds: ${dropped.join(", ")}`,
272
+ );
273
+ if (!dirty()) return { sha: null, dropped };
274
+
275
+ const prior = fs.existsSync(o.statusFile) ? readRuns(o.statusFile).at(-1) : undefined;
276
+ const what =
277
+ prior === undefined
278
+ ? "uncommitted work left in the worktree"
279
+ : `the ${prior.status === "FAILED" ? "failed " : ""}${prior.workflow} record left uncommitted`;
280
+ addAllButCopied(wt, o.copied);
281
+ const made = runGit(wt, ["commit", "-m", `chore(${o.fid}): carry ${what} bkit`]);
282
+ if (!made.ok) {
283
+ log(`could not commit what an earlier run left in ${wt}: ${made.stderr || made.stdout}`);
284
+ return { sha: null, dropped };
285
+ }
286
+ log(`committed ${what} before the resume rebase`);
287
+ return { sha: git(wt, ["rev-parse", "HEAD"]), dropped };
288
+ }
289
+
188
290
  // ---------------------------------------------------------------------------
189
291
  // Copy and install
190
292
  // ---------------------------------------------------------------------------
@@ -359,6 +461,17 @@ export function removeWorktree(
359
461
  // Command
360
462
  // ---------------------------------------------------------------------------
361
463
 
464
+ /**
465
+ * The warning ship prints when the branch it ships names neither the FID nor the
466
+ * issue (case-insensitive); null when it names one. A hand-made branch still ships.
467
+ */
468
+ export function shipBranchWarning(branch: string, fid: string, issue?: string): string | null {
469
+ const b = branch.toLowerCase();
470
+ const id = (issue ?? "").replace(/^#/, "").toLowerCase();
471
+ if (b.includes(fid.toLowerCase()) || (id !== "" && b.includes(id))) return null;
472
+ return `[bkit-ship] WARNING branch ${branch} not named for ${fid} — shipping it as named`;
473
+ }
474
+
362
475
  export const worktreesCommand: CommandSpec = {
363
476
  noun: "worktrees",
364
477
  summary: "Set up and remove the per-feature worktrees under .worktrees/.",
@@ -384,12 +497,19 @@ export const worktreesCommand: CommandSpec = {
384
497
  type: "string",
385
498
  help: "ship only: the branch the session prompt names (default: feat/{fid} when it exists, else the session branch)",
386
499
  },
500
+ {
501
+ name: "issue",
502
+ type: "string",
503
+ help: "ship only: the issue id; a branch naming it (or the FID) prints no branchWarning",
504
+ },
387
505
  ],
388
506
  output: {
389
507
  worktreePath: "directory the workflow must cd into",
390
508
  repoRoot: "the main checkout",
391
509
  branch: "branch checked out at worktreePath",
392
510
  mode: "created | resumed | adopted",
511
+ branchWarning:
512
+ "ship: the warning printed when the branch names neither the FID nor --issue, else null",
393
513
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
394
514
  rebaseConflict:
395
515
  "a resume rebase onto baseRef stopped on a conflict and is left in progress",
@@ -398,11 +518,19 @@ export const worktreesCommand: CommandSpec = {
398
518
  baseRef:
399
519
  "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
400
520
  baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
521
+ carriedSha:
522
+ "resume: the commit holding what an earlier run left uncommitted (a failed ship's record), made before the rebase; else null",
523
+ carriedDropped:
524
+ "resume: untracked logs of this feature dropped because baseRef already holds them (dev's copy wins)",
401
525
  copied: "worktree copy entries copied from the main checkout",
402
526
  copyMissing: "worktree copy entries absent from the main checkout",
403
527
  direnvAllowed:
404
528
  "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
405
529
  installed: "dependencies were installed",
530
+ startSha:
531
+ "in place on dev (debug): HEAD when the run started, recorded in the shared-checkout record; absent otherwise",
532
+ aheadAtStart:
533
+ "in place on dev (debug): commits local dev held beyond origin/dev when the run started; absent otherwise",
406
534
  },
407
535
  exitCodes: {
408
536
  [EXIT_REBASE_CONFLICT]:
@@ -411,12 +539,15 @@ export const worktreesCommand: CommandSpec = {
411
539
  [EXIT_INSTALL]: "dependency install failed",
412
540
  [EXIT_INSTALL_COULD_NOT_RUN]: "the package manager could not run (exit 126 / 127)",
413
541
  [EXIT_REFUSED]:
414
- "refused: dev / main as the working branch, detached HEAD, or ship could not switch to its branch",
542
+ "refused: main as the working branch (dev too, except debug in place), ship of dev / main, detached HEAD, or ship could not switch to its branch (a missing feat/{fid} is named)",
415
543
  [EXIT_WORKTREE_ADD]: "git worktree add failed",
416
- [EXIT_REBASE_NOT_STARTED]: "resume rebase could not start (e.g. uncommitted changes)",
544
+ [EXIT_REBASE_NOT_STARTED]:
545
+ "resume rebase could not start, even after committing what an earlier run left (e.g. a commit hook refused that commit)",
417
546
  [EXIT_NOT_A_WORKTREE]: ".worktrees/{fid} exists but is not a registered git worktree",
547
+ [EXIT_SHARED_BUSY]:
548
+ "in place on dev: another feature's run holds this checkout (its shared-checkout record has a live workflow lock); nothing written",
418
549
  [EXIT_DISK_FULL]:
419
- "free disk under bkit.disk.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
550
+ "free disk under bkit.workflows.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
420
551
  },
421
552
  run: async (ctx) => {
422
553
  const f = ctx.flags;
@@ -431,6 +562,9 @@ export const worktreesCommand: CommandSpec = {
431
562
  if (named !== undefined && workflow !== "ship") {
432
563
  throw new CommandError(EXIT.USAGE, "--branch is ship only");
433
564
  }
565
+ if (f.issue !== undefined && workflow !== "ship") {
566
+ throw new CommandError(EXIT.USAGE, "--issue is ship only");
567
+ }
434
568
  if (named !== undefined && !runGit(ctx.cwd, ["check-ref-format", "--branch", named]).ok) {
435
569
  throw new CommandError(EXIT.USAGE, `--branch "${named}" is not a valid branch name`);
436
570
  }
@@ -446,7 +580,12 @@ export const worktreesCommand: CommandSpec = {
446
580
  }
447
581
  const target = workflow === "ship" ? shipBranch(root, fid, named, session) : `feat/${fid}`;
448
582
  if (isSharedBranch(target)) {
449
- throw new CommandError(EXIT_REFUSED, `refusing to ship ${target} as a feature branch`);
583
+ throw new CommandError(
584
+ EXIT_REFUSED,
585
+ workflow === "ship"
586
+ ? `refusing to ship ${target}: /bkit-ship ships a feature branch into ${DEV} only; it never opens a PR from ${DEV} into ${MAIN} or merges into ${MAIN}, releases stay manual. Name the feature branch to ship.`
587
+ : `refusing to ship ${target} as a feature branch`,
588
+ );
450
589
  }
451
590
 
452
591
  // Ship mints only when the session is not already on the branch it ships:
@@ -491,6 +630,12 @@ export const worktreesCommand: CommandSpec = {
491
630
  if (workflow === "ship" && git(root, ["branch", "--show-current"]) !== target) {
492
631
  const sw = runGit(root, ["switch", target]);
493
632
  if (!sw.ok) {
633
+ if (!hasLocal(root, target) && remoteHas(root, target) !== "yes") {
634
+ throw new CommandError(
635
+ EXIT_REFUSED,
636
+ `${target} does not exist — name the feature branch to ship`,
637
+ );
638
+ }
494
639
  throw new CommandError(
495
640
  EXIT_REFUSED,
496
641
  `adopt mode: cannot switch to ${target} — commit or stash local changes, then re-run (${sw.stderr})`,
@@ -498,8 +643,8 @@ export const worktreesCommand: CommandSpec = {
498
643
  }
499
644
  }
500
645
  const here = git(root, ["branch", "--show-current"]) ?? "";
501
- const refused = workflow === "debug" ? "main" : DEV;
502
- if (here === "" || here === refused) {
646
+ // Debug may work in place on dev (its shared-checkout path); nothing works in place on main.
647
+ if (here === "" || here === MAIN || (here === DEV && workflow !== "debug")) {
503
648
  throw new CommandError(
504
649
  EXIT_REFUSED,
505
650
  here === ""
@@ -509,8 +654,16 @@ export const worktreesCommand: CommandSpec = {
509
654
  }
510
655
  }
511
656
 
657
+ // An in-place run on a shared branch records what was dirty before it, so its
658
+ // commits and push take only its own work.
659
+ const shared =
660
+ mode === "adopted" && isSharedBranch(git(root, ["branch", "--show-current"]) ?? "")
661
+ ? openSharedRecord(root, fid, workflow, logDir)
662
+ : undefined;
663
+
512
664
  let rebaseConflict = false;
513
665
  let sentinel: string | null = null;
666
+ let carried: ReturnType<typeof carryLeftovers> = null;
514
667
  const sentinelPath = path.join(logDir, ".rebase-failed");
515
668
  if (mode === "resumed" && workflow !== "ship") {
516
669
  // Cleared before every attempt: a sentinel left by an earlier run would
@@ -526,7 +679,19 @@ export const worktreesCommand: CommandSpec = {
526
679
  } else {
527
680
  fetchBranch(wt, DEV);
528
681
  const onto = devBase(wt, ctx.log);
682
+ carried = carryLeftovers(
683
+ wt,
684
+ {
685
+ fid,
686
+ onto,
687
+ statusFile: path.join(logDir, "status.jsonl"),
688
+ copied: config.worktreeCopy,
689
+ },
690
+ ctx.log,
691
+ );
529
692
  const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
693
+ // The rebase replays the carry commit on top: report the replayed one.
694
+ if (rb.ok && carried?.sha) carried.sha = git(wt, ["rev-parse", "HEAD"]);
530
695
  if (!rb.ok) {
531
696
  failure = {
532
697
  conflict: rebaseInProgress(wt),
@@ -564,21 +729,33 @@ export const worktreesCommand: CommandSpec = {
564
729
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
565
730
 
566
731
  const baseRef = devBase(wt);
732
+ const branch = git(wt, ["branch", "--show-current"]) ?? "";
733
+ const branchWarning =
734
+ workflow === "ship"
735
+ ? shipBranchWarning(branch, fid, f.issue === undefined ? undefined : String(f.issue))
736
+ : null;
737
+ if (branchWarning !== null) ctx.log(branchWarning);
567
738
  ctx.emit({
568
739
  worktreePath: wt,
569
740
  repoRoot: root,
570
- branch: git(wt, ["branch", "--show-current"]) ?? "",
741
+ branch,
571
742
  mode,
743
+ branchWarning,
572
744
  owned: fs.existsSync(marker),
573
745
  rebaseConflict,
574
746
  sentinel,
575
747
  logDir,
576
748
  baseRef,
577
749
  baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
750
+ carriedSha: carried?.sha ?? null,
751
+ carriedDropped: carried?.dropped ?? [],
578
752
  copied,
579
753
  copyMissing,
580
754
  direnvAllowed,
581
755
  installed: wantInstall && installStatus === 0,
756
+ ...(shared === undefined
757
+ ? {}
758
+ : { startSha: shared.startSha, aheadAtStart: shared.aheadAtStart }),
582
759
  });
583
760
  if (sentinel !== null)
584
761
  return rebaseConflict ? EXIT_REBASE_CONFLICT : EXIT_REBASE_NOT_STARTED;
@@ -65,7 +65,7 @@ export type ModuleName =
65
65
  export const ISSUE_TRACKERS = ["github", "linear", "jira", "none"] as const;
66
66
  export type IssueTracker = (typeof ISSUE_TRACKERS)[number];
67
67
 
68
- /** Default tracker when consumer manifest has no `bkit.issueTracker` field. */
68
+ /** Default tracker when consumer manifest has no `bkit.tracker.default` field. */
69
69
  export const DEFAULT_ISSUE_TRACKER: IssueTracker = "none";
70
70
 
71
71
  /**
@@ -94,17 +94,17 @@ export function parseIssueTracker(value: unknown): IssueTracker | null {
94
94
  * presence). Requires `tracker=github` + local opencode host (`bkit install --opencode=<provider>`).
95
95
  * - `none` — explicit opt-out; silences the post-install nudge advisory.
96
96
  *
97
- * Recorded in `package.json` `bkit.cloudAgents`. Presence of the adopted copy
97
+ * Recorded in `package.json` `bkit.cloud.agent`. Presence of the adopted copy
98
98
  * (`bkit-cloud.yml` for github-host variants; `.cursor/Dockerfile` for cursor) is the authoritative
99
99
  * "active" signal; the package.json field only distinguishes an opt-out from
100
100
  * an undecided install.
101
101
  *
102
- * Single self-describing field (mirrors `bkit.issueTracker`).
102
+ * Single self-describing field (mirrors `bkit.tracker.default`).
103
103
  */
104
104
  export const CLOUD_MODES = ["claude", "cursor", "opencode", "none"] as const;
105
105
  export type CloudAgents = (typeof CLOUD_MODES)[number];
106
106
 
107
- /** Default when consumer manifest has no `bkit.cloudAgents` field (undecided). */
107
+ /** Default when consumer manifest has no `bkit.cloud.agent` field (undecided). */
108
108
  export const DEFAULT_CLOUD_AGENTS: CloudAgents = "none";
109
109
 
110
110
  /** Narrow an unknown string to `CloudAgents` or return `null` if invalid. */
@@ -138,6 +138,7 @@ const CORE_MANIFEST: ManifestEntry[] = [
138
138
  // consumer copies are force-overwritten mirrors (writeTier1) so a consumer can read
139
139
  // them in-repo. Whole file is bkit-owned → byte-equal-text (refreshed every install);
140
140
  // prompts.md and lite.md are markered-text, keeping the consumer section below `bkit:end`.
141
+ { path: ".bkit/authoring.md", format: "byte-equal-text", module: "core" },
141
142
  { path: ".bkit/cloud.md", format: "byte-equal-text", module: "core" },
142
143
  { path: ".bkit/comparison.md", format: "byte-equal-text", module: "core" },
143
144
  { path: ".bkit/install.md", format: "byte-equal-text", module: "core" },
@@ -208,7 +209,7 @@ const CLAUDE_MANIFEST: ManifestEntry[] = [
208
209
  // (bkit-tests-static / -unit / -integration / -e2e / -live). Where a step is not a
209
210
  // tier (`format`, the ship gate) the name spells out the actual steps. One exception:
210
211
  // `min` sits off the chain: the least a push runs, on a push that changes no code
211
- // (`bkit.minPushPaths`); its steps are whatever that push can still break.
212
+ // (`bkit.testing.minPushPaths`); its steps are whatever that push can still break.
212
213
  //
213
214
  // The consumer owns every value: a turbo monorepo writes `turbo run … --filter`,
214
215
  // a Python repo writes `ruff check && pytest`. bkit never reads a value — only
@@ -238,7 +239,7 @@ export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
238
239
  // `.husky/pre-commit`: prettier --write over staged files, and nothing else —
239
240
  // seconds, not minutes. Prose is a whole-repo scan, so it gates at pre-push.
240
241
  "bkit:gate:format": "pnpm lint-staged",
241
- // `.husky/pre-push` on a min push (every file matches `bkit.minPushPaths`): no code, so
242
+ // `.husky/pre-push` on a min push (every file matches `bkit.testing.minPushPaths`): no code, so
242
243
  // no typecheck, lint or tests. Off the chain. Add any test that reads a min-push file.
243
244
  "bkit:gate:min": "pnpm format:check && pnpm lint:prose && pnpm slop:delta",
244
245
  // Everything that needs no test runner. Every part has a matching step in the
@@ -248,7 +249,7 @@ export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
248
249
  "bkit:gate:static":
249
250
  "pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta",
250
251
  // The default local gate: `.husky/pre-push` (when no `…-integration` gate is declared),
251
- // build Step 14, the remediates. `pnpm test` is the unit tier only: a test file the
252
+ // build Step 11, the remediates. `pnpm test` is the unit tier only: a test file the
252
253
  // integration gate also runs must not match it.
253
254
  "bkit:gate:static-unit": "pnpm bkit:gate:static && pnpm test",
254
255
  // Ship's conflict-resolve, the only caller whose dependency graph may have just
@@ -277,11 +278,12 @@ export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
277
278
  export const BKIT_DEBUG_GATES: readonly string[] = [
278
279
  "bkit:gate:static-unit-integration-e2e-live",
279
280
  "bkit:gate:static-unit-integration-e2e",
281
+ "bkit:gate:static-unit-integration",
280
282
  "bkit:gate:static-unit",
281
283
  ];
282
284
 
283
285
  /**
284
- * What `/bkit-build` Step 14 will run, in DESCENDING order — first one declared wins.
286
+ * What `/bkit-build` Step 11 will run, in DESCENDING order — first one declared wins.
285
287
  *
286
288
  * Build stops at integration; E2E and live are not in this list.
287
289
  *
@@ -497,7 +499,7 @@ export const ANTIGRAVITY_MANIFEST: ManifestEntry[] = [
497
499
  // (bkit-cloud.yml), bkit-cloud-bootstrap.sh and the Cursor Background Agent files
498
500
  // (.cursor/Dockerfile, .cursor/environment.json) ship as templates
499
501
  // (`.bkit/templates.md`); the consumer copies and owns them. Each variant only
500
- // records `bkit.cloudAgents` and prints its setup advisories.
502
+ // records `bkit.cloud.agent` and prints its setup advisories.
501
503
  export const CLOUD_MANIFEST_CLAUDE: ManifestEntry[] = [];
502
504
 
503
505
  export const CLOUD_MANIFEST_OPENCODE: ManifestEntry[] = [];
@@ -15,11 +15,12 @@ import type { ModuleContext } from "./index.js";
15
15
 
16
16
  /**
17
17
  * Persist a `bkit.<field>` value into the consumer's package.json so the
18
- * post-install advisory can tell "deliberately none" from "undecided". Mirrors
19
- * the `bkit.issueTracker` persist logic in commands/install/install.ts. Used for the opt-in
20
- * decisions recorded by their owning modules (`cloudAgents`). No-op
21
- * on dry-run or when package.json is absent/unparseable (non-fatal — the config
22
- * file presence is still the primary signal).
18
+ * post-install advisory can tell "deliberately none" from "undecided". `field` is a
19
+ * dotted path (`cloud.agent`); each missing section on the way is created. Mirrors
20
+ * the `bkit.tracker.default` persist logic in commands/install/install.ts. Used for the opt-in
21
+ * decisions recorded by their owning modules (`cloud.agent`). No-op
22
+ * on dry-run, when package.json is absent/unparseable, or when a section on the path
23
+ * holds a non-object (non-fatal — the config file presence is still the primary signal).
23
24
  */
24
25
  function setConsumerBkitField(field: string, value: string, dryRun: boolean): void {
25
26
  if (dryRun) return;
@@ -30,10 +31,17 @@ function setConsumerBkitField(field: string, value: string, dryRun: boolean): vo
30
31
  const parsed = parseJson(raw);
31
32
  if (!parsed.ok) return;
32
33
  const pkg = parsed.value as Record<string, unknown>;
33
- const bkit = (pkg.bkit ?? {}) as Record<string, unknown>;
34
- if (bkit[field] === value) return; // already set — avoid a no-op rewrite
35
- bkit[field] = value;
36
- pkg.bkit = bkit;
34
+ const keys = ["bkit", ...field.split(".")];
35
+ const leaf = keys.pop()!;
36
+ let parent = pkg;
37
+ for (const k of keys) {
38
+ parent[k] ??= {};
39
+ const next = parent[k];
40
+ if (next === null || typeof next !== "object" || Array.isArray(next)) return;
41
+ parent = next as Record<string, unknown>;
42
+ }
43
+ if (parent[leaf] === value) return; // already set — avoid a no-op rewrite
44
+ parent[leaf] = value;
37
45
  const indentMatch = raw.match(/\n([ \t]+)"/);
38
46
  const indent = indentMatch ? indentMatch[1] : " ";
39
47
  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
@@ -54,7 +62,7 @@ const CLOUD_WORKFLOW_ADOPT_STEP =
54
62
  //
55
63
  // NOT shipped by a default install — opt-in via `bkit install --auto=<variant>`,
56
64
  // so a default install ships ZERO cloud footprint. Every variant records
57
- // `bkit.cloudAgents` and prints its setup advisories; none writes a file. The cloud
65
+ // `bkit.cloud.agent` and prints its setup advisories; none writes a file. The cloud
58
66
  // workflow (bkit-cloud.yml), bkit-cloud-bootstrap.sh and the Cursor Background Agent
59
67
  // files (.cursor/Dockerfile, .cursor/environment.json) are templates the advisories
60
68
  // point at.
@@ -72,7 +80,7 @@ export function runCloudModule(ctx: ModuleContext): void {
72
80
  // --- cloud=claude: GitHub-tracker path ---
73
81
 
74
82
  // Record the variant so the post-install advisory and `bkit check` stay consistent.
75
- setConsumerBkitField("cloudAgents", "claude", dryRun);
83
+ setConsumerBkitField("cloud.agent", "claude", dryRun);
76
84
 
77
85
  // Advisory — cloud=claude setup checklist (App required; id-token: write).
78
86
  advisories.push({
@@ -115,7 +123,7 @@ export function runCloudModule(ctx: ModuleContext): void {
115
123
  // --- cloud=opencode: GitHub-tracker path (same bkit-cloud.yml template, no OIDC) ---
116
124
 
117
125
  // Record the variant.
118
- setConsumerBkitField("cloudAgents", "opencode", dryRun);
126
+ setConsumerBkitField("cloud.agent", "opencode", dryRun);
119
127
 
120
128
  // Advisory — cloud=opencode setup checklist.
121
129
  advisories.push({
@@ -138,7 +146,7 @@ export function runCloudModule(ctx: ModuleContext): void {
138
146
  // --- cloud=cursor: Linear-tracker path ---
139
147
 
140
148
  // Record the variant.
141
- setConsumerBkitField("cloudAgents", "cursor", dryRun);
149
+ setConsumerBkitField("cloud.agent", "cursor", dryRun);
142
150
 
143
151
  // Advisory — cloud=cursor setup checklist.
144
152
  advisories.push({