@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
@@ -9,6 +9,7 @@
9
9
  import * as fs from "node:fs";
10
10
  import * as path from "node:path";
11
11
  import { CommandError, EXIT } from "../lib.js";
12
+ import { COMMENT_FILE_OUTPUT, GENERATED_MARKER, commentFileOf, stampMarker } from "./tracker.js";
12
13
  /** Exit code: no workstream parsed — the workflow's Failure Path. */
13
14
  export const EXIT_NONE = 3;
14
15
  const HEADING = /^(#{1,6})\s+(.*?)\s*$/;
@@ -74,14 +75,15 @@ export const requiresList = (w) => `[${w.requires.join(", ")}]`;
74
75
  export function commentBody(ws, opts) {
75
76
  const doc = `docs/plans/${opts.month}/${opts.fid}-design.md`;
76
77
  const url = `https://github.com/${opts.ownerRepo}/blob/dev/${doc}`;
77
- return [
78
- "###### bkit:generated",
78
+ const lines = [
79
+ GENERATED_MARKER,
79
80
  "### Step 11 — Suggested Workstreams",
80
81
  "Advisory only. NEVER auto-trigger.",
81
82
  ...ws.map((w) => `- ${w.id}: ${w.name}. Requires: ${requiresList(w)}`),
82
83
  `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).`,
83
84
  `[${doc}](${url})`,
84
- ].join("\n");
85
+ ];
86
+ return stampMarker(lines.join("\n"));
85
87
  }
86
88
  const ARTIFACT_FLAG = {
87
89
  name: "artifact",
@@ -126,7 +128,11 @@ export const workstreamsCommand = {
126
128
  help: "owner/repo for the design doc link",
127
129
  },
128
130
  ],
129
- output: { comment: "the comment body", workstreams: "the parsed workstreams" },
131
+ output: {
132
+ comment: "the comment body",
133
+ commentFile: COMMENT_FILE_OUTPUT,
134
+ workstreams: "the parsed workstreams",
135
+ },
130
136
  exitCodes: { [EXIT_NONE]: "no workstream parsed (Failure Path)" },
131
137
  run: (ctx) => {
132
138
  const workstreams = read(ctx);
@@ -135,7 +141,7 @@ export const workstreamsCommand = {
135
141
  month: String(ctx.flags.month),
136
142
  fid: String(ctx.flags.fid),
137
143
  });
138
- ctx.emit({ comment: body, workstreams });
144
+ ctx.emit({ comment: body, commentFile: commentFileOf(ctx.cwd, body), workstreams });
139
145
  return EXIT.OK;
140
146
  },
141
147
  },
@@ -15,13 +15,16 @@
15
15
  import { spawnSync } from "node:child_process";
16
16
  import * as fs from "node:fs";
17
17
  import * as path from "node:path";
18
+ import { lastRun } from "../../ledgers/status.js";
18
19
  import { gitEnv } from "../../ledgers/telemetry.js";
19
20
  import { readBkitConfig } from "../../shared/settings.js";
20
21
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
21
- import { CommandError, DEV, EXIT, git, isSharedBranch, repoRoot, runGit, } from "../lib.js";
22
+ import { CommandError, DEV, EXIT, git, isSharedBranch, MAIN, repoRoot, runGit, } from "../lib.js";
22
23
  import { ensureDiskSpace } from "./disk.js";
24
+ import { listRecords, newRecord, readRecord, removeRecord, withSetupGuard, writeRecord, } from "./ledgers.js";
25
+ import { workflowLockFresh, workflowLockLive } from "./locks.js";
23
26
  import { detect } from "./runtime.js";
24
- import { WORKFLOW_FLAG } from "./status.js";
27
+ import { WORKFLOW_FLAG, readRuns } from "./status.js";
25
28
  const WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
26
29
  const ORIGIN_DEV = `origin/${DEV}`;
27
30
  export const EXIT_REBASE_CONFLICT = 3;
@@ -34,6 +37,7 @@ export const EXIT_REBASE_NOT_STARTED = 9;
34
37
  export const EXIT_NOT_A_WORKTREE = 10;
35
38
  export const EXIT_REMOVE = 11;
36
39
  export const EXIT_DISK_FULL = 12;
40
+ export const EXIT_SHARED_BUSY = 13;
37
41
  const FID_FLAG = { name: "fid", type: "string", required: true, help: "feature id" };
38
42
  function fidOf(value) {
39
43
  const fid = String(value);
@@ -87,6 +91,38 @@ function fetchBranch(cwd, branch) {
87
91
  throw new CommandError(EXIT_FETCH, `could not fetch origin ${branch}: ${res.stderr}`);
88
92
  }
89
93
  }
94
+ /**
95
+ * The shared-checkout record for an in-place run on `dev`. Another feature's
96
+ * record with a live workflow lock means that run owns the checkout; one
97
+ * without is left over and removed. The same feature with an open run in
98
+ * `{logDir}/status.jsonl` is a resume and keeps its record; a new run rewrites it.
99
+ */
100
+ function openSharedRecord(root, fid, workflow, logDir) {
101
+ const busy = (other) => new CommandError(EXIT_SHARED_BUSY, `${other} is running in this checkout (workflow lock held) — wait for it to finish, then re-run`);
102
+ const guarded = withSetupGuard(root, () => {
103
+ for (const other of listRecords(root)) {
104
+ if (other.fid === fid)
105
+ continue;
106
+ // A closed run that has not released its lock still pushes and waits for CI.
107
+ if (workflowLockLive(root, other.fid) || workflowLockFresh(root, other.fid)) {
108
+ throw busy(other.fid);
109
+ }
110
+ removeRecord(root, other.fid);
111
+ }
112
+ const existing = readRecord(root, fid);
113
+ const statusFile = path.join(logDir, "status.jsonl");
114
+ const open = fs.existsSync(statusFile) &&
115
+ lastRun(readRuns(statusFile), workflow)?.status === "IN_PROGRESS";
116
+ if (existing !== null && existing.branch === DEV && open)
117
+ return existing;
118
+ const fresh = newRecord(root, fid, DEV);
119
+ writeRecord(root, fresh);
120
+ return fresh;
121
+ });
122
+ if (guarded === null)
123
+ throw busy("another run");
124
+ return guarded.value;
125
+ }
90
126
  /** Ship's branch: the one the prompt names, else `feat/{fid}` when it exists, else the session's. */
91
127
  function shipBranch(root, fid, named, session) {
92
128
  if (named)
@@ -154,6 +190,51 @@ function rebaseInProgress(wt) {
154
190
  return dir !== null && fs.existsSync(dir);
155
191
  });
156
192
  }
193
+ /**
194
+ * `git add -A` in `tree`, leaving out the `bkit.workflows.worktree.copy` entries setup
195
+ * copies in from the main checkout (`.env` and the like): no bkit commit may
196
+ * carry them, gitignored or not.
197
+ */
198
+ export function addAllButCopied(tree, copied = readBkitConfig(tree).worktreeCopy) {
199
+ const keep = copied.map((e) => `:(exclude)${path.normalize(e)}`);
200
+ return runGit(tree, ["add", "-A", "--", ".", ...keep]);
201
+ }
202
+ /**
203
+ * Commit what an earlier run left uncommitted in a resumed worktree, so the
204
+ * resume rebase can start: a failed ship's flush lands its record on dev and
205
+ * leaves the worktree as it was, for whatever runs next. An untracked file in a
206
+ * log folder of this feature that `onto` already holds is dropped first: dev's
207
+ * copy, landed by that flush, wins, and a second copy would stop the rebase.
208
+ * The `worktreeCopy` entries setup copies in are never committed. Clean tree →
209
+ * null; a failed commit is narrated and leaves the tree for the rebase to refuse.
210
+ */
211
+ function carryLeftovers(wt, o, log) {
212
+ const dirty = () => (git(wt, ["status", "--porcelain", "--untracked-files=all"]) ?? "") !== "";
213
+ if (!dirty())
214
+ return null;
215
+ const logs = new RegExp(`^docs/plans/[^/]+/logs/${o.fid.replace(/\./g, "\\.")}/`);
216
+ const dropped = (git(wt, ["ls-files", "--others", "--exclude-standard"]) ?? "")
217
+ .split("\n")
218
+ .filter((f) => logs.test(f) && runGit(wt, ["cat-file", "-e", `${o.onto}:${f}`]).ok);
219
+ for (const f of dropped)
220
+ fs.rmSync(path.join(wt, f));
221
+ if (dropped.length > 0)
222
+ log(`dropped ${dropped.length} untracked log(s) ${o.onto} already holds: ${dropped.join(", ")}`);
223
+ if (!dirty())
224
+ return { sha: null, dropped };
225
+ const prior = fs.existsSync(o.statusFile) ? readRuns(o.statusFile).at(-1) : undefined;
226
+ const what = prior === undefined
227
+ ? "uncommitted work left in the worktree"
228
+ : `the ${prior.status === "FAILED" ? "failed " : ""}${prior.workflow} record left uncommitted`;
229
+ addAllButCopied(wt, o.copied);
230
+ const made = runGit(wt, ["commit", "-m", `chore(${o.fid}): carry ${what} bkit`]);
231
+ if (!made.ok) {
232
+ log(`could not commit what an earlier run left in ${wt}: ${made.stderr || made.stdout}`);
233
+ return { sha: null, dropped };
234
+ }
235
+ log(`committed ${what} before the resume rebase`);
236
+ return { sha: git(wt, ["rev-parse", "HEAD"]), dropped };
237
+ }
157
238
  // ---------------------------------------------------------------------------
158
239
  // Copy and install
159
240
  // ---------------------------------------------------------------------------
@@ -304,6 +385,17 @@ export function removeWorktree(cwd, fid, branch, log) {
304
385
  // ---------------------------------------------------------------------------
305
386
  // Command
306
387
  // ---------------------------------------------------------------------------
388
+ /**
389
+ * The warning ship prints when the branch it ships names neither the FID nor the
390
+ * issue (case-insensitive); null when it names one. A hand-made branch still ships.
391
+ */
392
+ export function shipBranchWarning(branch, fid, issue) {
393
+ const b = branch.toLowerCase();
394
+ const id = (issue ?? "").replace(/^#/, "").toLowerCase();
395
+ if (b.includes(fid.toLowerCase()) || (id !== "" && b.includes(id)))
396
+ return null;
397
+ return `[bkit-ship] WARNING branch ${branch} not named for ${fid} — shipping it as named`;
398
+ }
307
399
  export const worktreesCommand = {
308
400
  noun: "worktrees",
309
401
  summary: "Set up and remove the per-feature worktrees under .worktrees/.",
@@ -329,33 +421,44 @@ export const worktreesCommand = {
329
421
  type: "string",
330
422
  help: "ship only: the branch the session prompt names (default: feat/{fid} when it exists, else the session branch)",
331
423
  },
424
+ {
425
+ name: "issue",
426
+ type: "string",
427
+ help: "ship only: the issue id; a branch naming it (or the FID) prints no branchWarning",
428
+ },
332
429
  ],
333
430
  output: {
334
431
  worktreePath: "directory the workflow must cd into",
335
432
  repoRoot: "the main checkout",
336
433
  branch: "branch checked out at worktreePath",
337
434
  mode: "created | resumed | adopted",
435
+ branchWarning: "ship: the warning printed when the branch names neither the FID nor --issue, else null",
338
436
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
339
437
  rebaseConflict: "a resume rebase onto baseRef stopped on a conflict and is left in progress",
340
438
  sentinel: "the .rebase-failed sentinel written on a failed rebase, else null",
341
439
  logDir: "docs/plans/{month}/logs/{fid} under worktreePath (created)",
342
440
  baseRef: "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
343
441
  baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
442
+ carriedSha: "resume: the commit holding what an earlier run left uncommitted (a failed ship's record), made before the rebase; else null",
443
+ carriedDropped: "resume: untracked logs of this feature dropped because baseRef already holds them (dev's copy wins)",
344
444
  copied: "worktree copy entries copied from the main checkout",
345
445
  copyMissing: "worktree copy entries absent from the main checkout",
346
446
  direnvAllowed: "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
347
447
  installed: "dependencies were installed",
448
+ startSha: "in place on dev (debug): HEAD when the run started, recorded in the shared-checkout record; absent otherwise",
449
+ aheadAtStart: "in place on dev (debug): commits local dev held beyond origin/dev when the run started; absent otherwise",
348
450
  },
349
451
  exitCodes: {
350
452
  [EXIT_REBASE_CONFLICT]: "resume rebase stopped on a conflict, left in progress — run `bkit branches rebase`, then re-run setup; on its failure, Failure Path",
351
453
  [EXIT_FETCH]: "could not fetch from origin",
352
454
  [EXIT_INSTALL]: "dependency install failed",
353
455
  [EXIT_INSTALL_COULD_NOT_RUN]: "the package manager could not run (exit 126 / 127)",
354
- [EXIT_REFUSED]: "refused: dev / main as the working branch, detached HEAD, or ship could not switch to its branch",
456
+ [EXIT_REFUSED]: "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)",
355
457
  [EXIT_WORKTREE_ADD]: "git worktree add failed",
356
- [EXIT_REBASE_NOT_STARTED]: "resume rebase could not start (e.g. uncommitted changes)",
458
+ [EXIT_REBASE_NOT_STARTED]: "resume rebase could not start, even after committing what an earlier run left (e.g. a commit hook refused that commit)",
357
459
  [EXIT_NOT_A_WORKTREE]: ".worktrees/{fid} exists but is not a registered git worktree",
358
- [EXIT_DISK_FULL]: "free disk under bkit.disk.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
460
+ [EXIT_SHARED_BUSY]: "in place on dev: another feature's run holds this checkout (its shared-checkout record has a live workflow lock); nothing written",
461
+ [EXIT_DISK_FULL]: "free disk under bkit.workflows.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
359
462
  },
360
463
  run: async (ctx) => {
361
464
  const f = ctx.flags;
@@ -371,6 +474,9 @@ export const worktreesCommand = {
371
474
  if (named !== undefined && workflow !== "ship") {
372
475
  throw new CommandError(EXIT.USAGE, "--branch is ship only");
373
476
  }
477
+ if (f.issue !== undefined && workflow !== "ship") {
478
+ throw new CommandError(EXIT.USAGE, "--issue is ship only");
479
+ }
374
480
  if (named !== undefined && !runGit(ctx.cwd, ["check-ref-format", "--branch", named]).ok) {
375
481
  throw new CommandError(EXIT.USAGE, `--branch "${named}" is not a valid branch name`);
376
482
  }
@@ -382,7 +488,9 @@ export const worktreesCommand = {
382
488
  }
383
489
  const target = workflow === "ship" ? shipBranch(root, fid, named, session) : `feat/${fid}`;
384
490
  if (isSharedBranch(target)) {
385
- throw new CommandError(EXIT_REFUSED, `refusing to ship ${target} as a feature branch`);
491
+ throw new CommandError(EXIT_REFUSED, workflow === "ship"
492
+ ? `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.`
493
+ : `refusing to ship ${target} as a feature branch`);
386
494
  }
387
495
  // Ship mints only when the session is not already on the branch it ships:
388
496
  // that branch cannot be checked out in two places.
@@ -424,19 +532,28 @@ export const worktreesCommand = {
424
532
  if (workflow === "ship" && git(root, ["branch", "--show-current"]) !== target) {
425
533
  const sw = runGit(root, ["switch", target]);
426
534
  if (!sw.ok) {
535
+ if (!hasLocal(root, target) && remoteHas(root, target) !== "yes") {
536
+ throw new CommandError(EXIT_REFUSED, `${target} does not exist — name the feature branch to ship`);
537
+ }
427
538
  throw new CommandError(EXIT_REFUSED, `adopt mode: cannot switch to ${target} — commit or stash local changes, then re-run (${sw.stderr})`);
428
539
  }
429
540
  }
430
541
  const here = git(root, ["branch", "--show-current"]) ?? "";
431
- const refused = workflow === "debug" ? "main" : DEV;
432
- if (here === "" || here === refused) {
542
+ // Debug may work in place on dev (its shared-checkout path); nothing works in place on main.
543
+ if (here === "" || here === MAIN || (here === DEV && workflow !== "debug")) {
433
544
  throw new CommandError(EXIT_REFUSED, here === ""
434
545
  ? "adopt mode: detached HEAD — check out the feature branch"
435
546
  : `adopt mode: current branch is ${here} — refusing to work in place on ${here}`);
436
547
  }
437
548
  }
549
+ // An in-place run on a shared branch records what was dirty before it, so its
550
+ // commits and push take only its own work.
551
+ const shared = mode === "adopted" && isSharedBranch(git(root, ["branch", "--show-current"]) ?? "")
552
+ ? openSharedRecord(root, fid, workflow, logDir)
553
+ : undefined;
438
554
  let rebaseConflict = false;
439
555
  let sentinel = null;
556
+ let carried = null;
440
557
  const sentinelPath = path.join(logDir, ".rebase-failed");
441
558
  if (mode === "resumed" && workflow !== "ship") {
442
559
  // Cleared before every attempt: a sentinel left by an earlier run would
@@ -453,7 +570,16 @@ export const worktreesCommand = {
453
570
  else {
454
571
  fetchBranch(wt, DEV);
455
572
  const onto = devBase(wt, ctx.log);
573
+ carried = carryLeftovers(wt, {
574
+ fid,
575
+ onto,
576
+ statusFile: path.join(logDir, "status.jsonl"),
577
+ copied: config.worktreeCopy,
578
+ }, ctx.log);
456
579
  const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
580
+ // The rebase replays the carry commit on top: report the replayed one.
581
+ if (rb.ok && carried?.sha)
582
+ carried.sha = git(wt, ["rev-parse", "HEAD"]);
457
583
  if (!rb.ok) {
458
584
  failure = {
459
585
  conflict: rebaseInProgress(wt),
@@ -484,21 +610,33 @@ export const worktreesCommand = {
484
610
  const wantInstall = done && config.worktreeInstall;
485
611
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
486
612
  const baseRef = devBase(wt);
613
+ const branch = git(wt, ["branch", "--show-current"]) ?? "";
614
+ const branchWarning = workflow === "ship"
615
+ ? shipBranchWarning(branch, fid, f.issue === undefined ? undefined : String(f.issue))
616
+ : null;
617
+ if (branchWarning !== null)
618
+ ctx.log(branchWarning);
487
619
  ctx.emit({
488
620
  worktreePath: wt,
489
621
  repoRoot: root,
490
- branch: git(wt, ["branch", "--show-current"]) ?? "",
622
+ branch,
491
623
  mode,
624
+ branchWarning,
492
625
  owned: fs.existsSync(marker),
493
626
  rebaseConflict,
494
627
  sentinel,
495
628
  logDir,
496
629
  baseRef,
497
630
  baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
631
+ carriedSha: carried?.sha ?? null,
632
+ carriedDropped: carried?.dropped ?? [],
498
633
  copied,
499
634
  copyMissing,
500
635
  direnvAllowed,
501
636
  installed: wantInstall && installStatus === 0,
637
+ ...(shared === undefined
638
+ ? {}
639
+ : { startSha: shared.startSha, aheadAtStart: shared.aheadAtStart }),
502
640
  });
503
641
  if (sentinel !== null)
504
642
  return rebaseConflict ? EXIT_REBASE_CONFLICT : EXIT_REBASE_NOT_STARTED;
@@ -25,7 +25,7 @@ export const OPTIN_MODULES = new Set(["cloud", "opencode", "codex", "antigravity
25
25
  * `render/trackers.ts`.
26
26
  */
27
27
  export const ISSUE_TRACKERS = ["github", "linear", "jira", "none"];
28
- /** Default tracker when consumer manifest has no `bkit.issueTracker` field. */
28
+ /** Default tracker when consumer manifest has no `bkit.tracker.default` field. */
29
29
  export const DEFAULT_ISSUE_TRACKER = "none";
30
30
  /**
31
31
  * Narrow an unknown string to `IssueTracker` or return `null` if invalid.
@@ -51,15 +51,15 @@ export function parseIssueTracker(value) {
51
51
  * presence). Requires `tracker=github` + local opencode host (`bkit install --opencode=<provider>`).
52
52
  * - `none` — explicit opt-out; silences the post-install nudge advisory.
53
53
  *
54
- * Recorded in `package.json` `bkit.cloudAgents`. Presence of the adopted copy
54
+ * Recorded in `package.json` `bkit.cloud.agent`. Presence of the adopted copy
55
55
  * (`bkit-cloud.yml` for github-host variants; `.cursor/Dockerfile` for cursor) is the authoritative
56
56
  * "active" signal; the package.json field only distinguishes an opt-out from
57
57
  * an undecided install.
58
58
  *
59
- * Single self-describing field (mirrors `bkit.issueTracker`).
59
+ * Single self-describing field (mirrors `bkit.tracker.default`).
60
60
  */
61
61
  export const CLOUD_MODES = ["claude", "cursor", "opencode", "none"];
62
- /** Default when consumer manifest has no `bkit.cloudAgents` field (undecided). */
62
+ /** Default when consumer manifest has no `bkit.cloud.agent` field (undecided). */
63
63
  export const DEFAULT_CLOUD_AGENTS = "none";
64
64
  /** Narrow an unknown string to `CloudAgents` or return `null` if invalid. */
65
65
  export function parseCloudAgents(value) {
@@ -90,6 +90,7 @@ const CORE_MANIFEST = [
90
90
  // consumer copies are force-overwritten mirrors (writeTier1) so a consumer can read
91
91
  // them in-repo. Whole file is bkit-owned → byte-equal-text (refreshed every install);
92
92
  // prompts.md and lite.md are markered-text, keeping the consumer section below `bkit:end`.
93
+ { path: ".bkit/authoring.md", format: "byte-equal-text", module: "core" },
93
94
  { path: ".bkit/cloud.md", format: "byte-equal-text", module: "core" },
94
95
  { path: ".bkit/comparison.md", format: "byte-equal-text", module: "core" },
95
96
  { path: ".bkit/install.md", format: "byte-equal-text", module: "core" },
@@ -158,7 +159,7 @@ const CLAUDE_MANIFEST = [
158
159
  // (bkit-tests-static / -unit / -integration / -e2e / -live). Where a step is not a
159
160
  // tier (`format`, the ship gate) the name spells out the actual steps. One exception:
160
161
  // `min` sits off the chain: the least a push runs, on a push that changes no code
161
- // (`bkit.minPushPaths`); its steps are whatever that push can still break.
162
+ // (`bkit.testing.minPushPaths`); its steps are whatever that push can still break.
162
163
  //
163
164
  // The consumer owns every value: a turbo monorepo writes `turbo run … --filter`,
164
165
  // a Python repo writes `ruff check && pytest`. bkit never reads a value — only
@@ -188,7 +189,7 @@ export const BKIT_GATE_SCRIPTS = {
188
189
  // `.husky/pre-commit`: prettier --write over staged files, and nothing else —
189
190
  // seconds, not minutes. Prose is a whole-repo scan, so it gates at pre-push.
190
191
  "bkit:gate:format": "pnpm lint-staged",
191
- // `.husky/pre-push` on a min push (every file matches `bkit.minPushPaths`): no code, so
192
+ // `.husky/pre-push` on a min push (every file matches `bkit.testing.minPushPaths`): no code, so
192
193
  // no typecheck, lint or tests. Off the chain. Add any test that reads a min-push file.
193
194
  "bkit:gate:min": "pnpm format:check && pnpm lint:prose && pnpm slop:delta",
194
195
  // Everything that needs no test runner. Every part has a matching step in the
@@ -197,7 +198,7 @@ export const BKIT_GATE_SCRIPTS = {
197
198
  // path.
198
199
  "bkit:gate:static": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta",
199
200
  // The default local gate: `.husky/pre-push` (when no `…-integration` gate is declared),
200
- // build Step 14, the remediates. `pnpm test` is the unit tier only: a test file the
201
+ // build Step 11, the remediates. `pnpm test` is the unit tier only: a test file the
201
202
  // integration gate also runs must not match it.
202
203
  "bkit:gate:static-unit": "pnpm bkit:gate:static && pnpm test",
203
204
  // Ship's conflict-resolve, the only caller whose dependency graph may have just
@@ -224,10 +225,11 @@ export const BKIT_GATE_SCRIPTS = {
224
225
  export const BKIT_DEBUG_GATES = [
225
226
  "bkit:gate:static-unit-integration-e2e-live",
226
227
  "bkit:gate:static-unit-integration-e2e",
228
+ "bkit:gate:static-unit-integration",
227
229
  "bkit:gate:static-unit",
228
230
  ];
229
231
  /**
230
- * What `/bkit-build` Step 14 will run, in DESCENDING order — first one declared wins.
232
+ * What `/bkit-build` Step 11 will run, in DESCENDING order — first one declared wins.
231
233
  *
232
234
  * Build stops at integration; E2E and live are not in this list.
233
235
  *
@@ -431,7 +433,7 @@ export const ANTIGRAVITY_MANIFEST = [
431
433
  // (bkit-cloud.yml), bkit-cloud-bootstrap.sh and the Cursor Background Agent files
432
434
  // (.cursor/Dockerfile, .cursor/environment.json) ship as templates
433
435
  // (`.bkit/templates.md`); the consumer copies and owns them. Each variant only
434
- // records `bkit.cloudAgents` and prints its setup advisories.
436
+ // records `bkit.cloud.agent` and prints its setup advisories.
435
437
  export const CLOUD_MANIFEST_CLAUDE = [];
436
438
  export const CLOUD_MANIFEST_OPENCODE = [];
437
439
  export const CLOUD_MANIFEST_CURSOR = [];
@@ -10,11 +10,12 @@ import { parseJson } from "../../shared/json.js";
10
10
  // ---------------------------------------------------------------------------
11
11
  /**
12
12
  * Persist a `bkit.<field>` value into the consumer's package.json so the
13
- * post-install advisory can tell "deliberately none" from "undecided". Mirrors
14
- * the `bkit.issueTracker` persist logic in commands/install/install.ts. Used for the opt-in
15
- * decisions recorded by their owning modules (`cloudAgents`). No-op
16
- * on dry-run or when package.json is absent/unparseable (non-fatal — the config
17
- * file presence is still the primary signal).
13
+ * post-install advisory can tell "deliberately none" from "undecided". `field` is a
14
+ * dotted path (`cloud.agent`); each missing section on the way is created. Mirrors
15
+ * the `bkit.tracker.default` persist logic in commands/install/install.ts. Used for the opt-in
16
+ * decisions recorded by their owning modules (`cloud.agent`). No-op
17
+ * on dry-run, when package.json is absent/unparseable, or when a section on the path
18
+ * holds a non-object (non-fatal — the config file presence is still the primary signal).
18
19
  */
19
20
  function setConsumerBkitField(field, value, dryRun) {
20
21
  if (dryRun)
@@ -28,11 +29,19 @@ function setConsumerBkitField(field, value, dryRun) {
28
29
  if (!parsed.ok)
29
30
  return;
30
31
  const pkg = parsed.value;
31
- const bkit = (pkg.bkit ?? {});
32
- if (bkit[field] === value)
32
+ const keys = ["bkit", ...field.split(".")];
33
+ const leaf = keys.pop();
34
+ let parent = pkg;
35
+ for (const k of keys) {
36
+ parent[k] ??= {};
37
+ const next = parent[k];
38
+ if (next === null || typeof next !== "object" || Array.isArray(next))
39
+ return;
40
+ parent = next;
41
+ }
42
+ if (parent[leaf] === value)
33
43
  return; // already set — avoid a no-op rewrite
34
- bkit[field] = value;
35
- pkg.bkit = bkit;
44
+ parent[leaf] = value;
36
45
  const indentMatch = raw.match(/\n([ \t]+)"/);
37
46
  const indent = indentMatch ? indentMatch[1] : " ";
38
47
  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
@@ -51,7 +60,7 @@ const CLOUD_WORKFLOW_ADOPT_STEP = " - Copy `.bkit/templates/.github/workflows/b
51
60
  //
52
61
  // NOT shipped by a default install — opt-in via `bkit install --auto=<variant>`,
53
62
  // so a default install ships ZERO cloud footprint. Every variant records
54
- // `bkit.cloudAgents` and prints its setup advisories; none writes a file. The cloud
63
+ // `bkit.cloud.agent` and prints its setup advisories; none writes a file. The cloud
55
64
  // workflow (bkit-cloud.yml), bkit-cloud-bootstrap.sh and the Cursor Background Agent
56
65
  // files (.cursor/Dockerfile, .cursor/environment.json) are templates the advisories
57
66
  // point at.
@@ -66,7 +75,7 @@ export function runCloudModule(ctx) {
66
75
  if (variant === "claude") {
67
76
  // --- cloud=claude: GitHub-tracker path ---
68
77
  // Record the variant so the post-install advisory and `bkit check` stay consistent.
69
- setConsumerBkitField("cloudAgents", "claude", dryRun);
78
+ setConsumerBkitField("cloud.agent", "claude", dryRun);
70
79
  // Advisory — cloud=claude setup checklist (App required; id-token: write).
71
80
  advisories.push({
72
81
  id: "bkit-cloud-setup",
@@ -103,7 +112,7 @@ export function runCloudModule(ctx) {
103
112
  else if (variant === "opencode") {
104
113
  // --- cloud=opencode: GitHub-tracker path (same bkit-cloud.yml template, no OIDC) ---
105
114
  // Record the variant.
106
- setConsumerBkitField("cloudAgents", "opencode", dryRun);
115
+ setConsumerBkitField("cloud.agent", "opencode", dryRun);
107
116
  // Advisory — cloud=opencode setup checklist.
108
117
  advisories.push({
109
118
  id: "bkit-cloud-setup",
@@ -123,7 +132,7 @@ export function runCloudModule(ctx) {
123
132
  else {
124
133
  // --- cloud=cursor: Linear-tracker path ---
125
134
  // Record the variant.
126
- setConsumerBkitField("cloudAgents", "cursor", dryRun);
135
+ setConsumerBkitField("cloud.agent", "cursor", dryRun);
127
136
  // Advisory — cloud=cursor setup checklist.
128
137
  advisories.push({
129
138
  id: "bkit-cloud-setup",