@cbartens/bkit 5.5.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -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
  },
@@ -8,17 +8,23 @@
8
8
  // reports it. `remove` is the close / cleanup half: it removes only a worktree a
9
9
  // workflow created, marked in the git common dir's outbox so the marker outlives
10
10
  // the worktree it describes, and with `--branch` deletes the feature branch
11
- // unless another worktree still holds it.
11
+ // unless another worktree still holds it. A new branch, and a resume rebase,
12
+ // use local `dev` when it is a fast-forward of `origin/dev`: dev pushes wait for
13
+ // a human, so local dev is routinely ahead, and a worktree without those commits
14
+ // builds against superseded work.
12
15
  import { spawnSync } from "node:child_process";
13
16
  import * as fs from "node:fs";
14
17
  import * as path from "node:path";
18
+ import { lastRun } from "../../ledgers/status.js";
15
19
  import { gitEnv } from "../../ledgers/telemetry.js";
16
20
  import { readBkitConfig } from "../../shared/settings.js";
17
21
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
18
- import { CommandError, DEV, EXIT, git, isSharedBranch, repoRoot, runGit, } from "../lib.js";
22
+ import { CommandError, DEV, EXIT, git, isSharedBranch, MAIN, repoRoot, runGit, } from "../lib.js";
19
23
  import { ensureDiskSpace } from "./disk.js";
24
+ import { listRecords, newRecord, readRecord, removeRecord, withSetupGuard, writeRecord, } from "./ledgers.js";
25
+ import { workflowLockFresh, workflowLockLive } from "./locks.js";
20
26
  import { detect } from "./runtime.js";
21
- import { WORKFLOW_FLAG } from "./status.js";
27
+ import { WORKFLOW_FLAG, readRuns } from "./status.js";
22
28
  const WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
23
29
  const ORIGIN_DEV = `origin/${DEV}`;
24
30
  export const EXIT_REBASE_CONFLICT = 3;
@@ -31,6 +37,7 @@ export const EXIT_REBASE_NOT_STARTED = 9;
31
37
  export const EXIT_NOT_A_WORKTREE = 10;
32
38
  export const EXIT_REMOVE = 11;
33
39
  export const EXIT_DISK_FULL = 12;
40
+ export const EXIT_SHARED_BUSY = 13;
34
41
  const FID_FLAG = { name: "fid", type: "string", required: true, help: "feature id" };
35
42
  function fidOf(value) {
36
43
  const fid = String(value);
@@ -84,6 +91,38 @@ function fetchBranch(cwd, branch) {
84
91
  throw new CommandError(EXIT_FETCH, `could not fetch origin ${branch}: ${res.stderr}`);
85
92
  }
86
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
+ }
87
126
  /** Ship's branch: the one the prompt names, else `feat/{fid}` when it exists, else the session's. */
88
127
  function shipBranch(root, fid, named, session) {
89
128
  if (named)
@@ -93,12 +132,32 @@ function shipBranch(root, fid, named, session) {
93
132
  return feat;
94
133
  return isSharedBranch(session) || session === "" ? feat : session;
95
134
  }
135
+ /**
136
+ * The ref a feature branch starts from and rebases onto: local `dev` when it is
137
+ * strictly ahead of `origin/dev` (a fast-forward of it), else `origin/dev`. With
138
+ * `log`, says why when the two differ. Fetch first for a current answer.
139
+ */
140
+ export function devBase(cwd, log) {
141
+ const local = git(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${DEV}`]);
142
+ const remote = git(cwd, ["rev-parse", "-q", "--verify", `refs/remotes/${ORIGIN_DEV}`]);
143
+ if (local === null || remote === null || local === remote)
144
+ return ORIGIN_DEV;
145
+ const count = (range) => git(cwd, ["rev-list", "--count", range]) ?? "?";
146
+ if (runGit(cwd, ["merge-base", "--is-ancestor", remote, local]).ok) {
147
+ log?.(`local ${DEV} is ${count(`${remote}..${local}`)} commit(s) ahead of ${ORIGIN_DEV} — basing on local ${DEV}; push ${DEV} before the feature PR`);
148
+ return DEV;
149
+ }
150
+ if (!runGit(cwd, ["merge-base", "--is-ancestor", local, remote]).ok) {
151
+ log?.(`local ${DEV} and ${ORIGIN_DEV} have diverged — basing on ${ORIGIN_DEV}; local ${DEV}'s ${count(`${remote}..${local}`)} commit(s) are not in this worktree`);
152
+ }
153
+ return ORIGIN_DEV;
154
+ }
96
155
  /**
97
156
  * `git worktree add` for `branch`: the local branch, else a tracking branch off
98
- * `origin`, else (when `mayCreate`) a new branch off a freshly fetched
99
- * `origin/dev`. Returns false when there was nothing to add and `mayCreate` is off.
157
+ * `origin`, else (when `mayCreate`) a new branch off `devBase` after a fresh
158
+ * fetch. Returns false when there was nothing to add and `mayCreate` is off.
100
159
  */
101
- function addWorktree(root, wt, branch, mayCreate) {
160
+ function addWorktree(root, wt, branch, mayCreate, log) {
102
161
  let args;
103
162
  if (hasLocal(root, branch)) {
104
163
  args = [wt, branch];
@@ -114,7 +173,7 @@ function addWorktree(root, wt, branch, mayCreate) {
114
173
  }
115
174
  else if (mayCreate) {
116
175
  fetchBranch(root, DEV);
117
- args = [wt, "-b", branch, ORIGIN_DEV];
176
+ args = [wt, "-b", branch, devBase(root, log)];
118
177
  }
119
178
  else {
120
179
  return false;
@@ -131,6 +190,51 @@ function rebaseInProgress(wt) {
131
190
  return dir !== null && fs.existsSync(dir);
132
191
  });
133
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
+ }
134
238
  // ---------------------------------------------------------------------------
135
239
  // Copy and install
136
240
  // ---------------------------------------------------------------------------
@@ -157,6 +261,32 @@ function copyListed(root, wt, entries, log) {
157
261
  }
158
262
  return { copied, copyMissing };
159
263
  }
264
+ /**
265
+ * `direnv allow` the worktree's `.envrc` when it matches the main checkout's
266
+ * byte for byte, so the worktree inherits the trust given there and nothing
267
+ * more; a differing file is left for a human to read. No `.envrc`, direnv
268
+ * missing or failing → false, narrated, never fatal.
269
+ */
270
+ function allowDirenv(root, wt, log) {
271
+ const envrc = path.join(wt, ".envrc");
272
+ if (!fs.existsSync(envrc))
273
+ return false;
274
+ const main = path.join(root, ".envrc");
275
+ if (!fs.existsSync(main) || !fs.readFileSync(main).equals(fs.readFileSync(envrc))) {
276
+ log(`direnv: ${envrc} differs from the main checkout's — not allowed; read it, then run direnv allow`);
277
+ return false;
278
+ }
279
+ const res = spawnSync("direnv", ["allow", wt], { cwd: wt, encoding: "utf-8" });
280
+ if (res.error || res.status === 127) {
281
+ log("direnv: not installed — run direnv allow in the worktree once it is");
282
+ return false;
283
+ }
284
+ if (res.status !== 0) {
285
+ log(`direnv allow failed (exit ${res.status}): ${(res.stderr ?? "").trim()}`);
286
+ return false;
287
+ }
288
+ return true;
289
+ }
160
290
  /** Run the frozen install in `wt`; the exit status, with a spawn failure read as "could not run". */
161
291
  function install(wt, log) {
162
292
  const [cmd, ...args] = installCommand({ frozen: true });
@@ -255,6 +385,17 @@ export function removeWorktree(cwd, fid, branch, log) {
255
385
  // ---------------------------------------------------------------------------
256
386
  // Command
257
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
+ }
258
399
  export const worktreesCommand = {
259
400
  noun: "worktrees",
260
401
  summary: "Set up and remove the per-feature worktrees under .worktrees/.",
@@ -280,31 +421,44 @@ export const worktreesCommand = {
280
421
  type: "string",
281
422
  help: "ship only: the branch the session prompt names (default: feat/{fid} when it exists, else the session branch)",
282
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
+ },
283
429
  ],
284
430
  output: {
285
431
  worktreePath: "directory the workflow must cd into",
286
432
  repoRoot: "the main checkout",
287
433
  branch: "branch checked out at worktreePath",
288
434
  mode: "created | resumed | adopted",
435
+ branchWarning: "ship: the warning printed when the branch names neither the FID nor --issue, else null",
289
436
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
290
- rebaseConflict: "a resume rebase onto origin/dev stopped on a conflict and is left in progress",
437
+ rebaseConflict: "a resume rebase onto baseRef stopped on a conflict and is left in progress",
291
438
  sentinel: "the .rebase-failed sentinel written on a failed rebase, else null",
292
439
  logDir: "docs/plans/{month}/logs/{fid} under worktreePath (created)",
293
- baseSha: "git merge-base origin/dev HEAD at worktreePath, or null",
440
+ baseRef: "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
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)",
294
444
  copied: "worktree copy entries copied from the main checkout",
295
445
  copyMissing: "worktree copy entries absent from the main checkout",
446
+ direnvAllowed: "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
296
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",
297
450
  },
298
451
  exitCodes: {
299
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",
300
453
  [EXIT_FETCH]: "could not fetch from origin",
301
454
  [EXIT_INSTALL]: "dependency install failed",
302
455
  [EXIT_INSTALL_COULD_NOT_RUN]: "the package manager could not run (exit 126 / 127)",
303
- [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)",
304
457
  [EXIT_WORKTREE_ADD]: "git worktree add failed",
305
- [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)",
306
459
  [EXIT_NOT_A_WORKTREE]: ".worktrees/{fid} exists but is not a registered git worktree",
307
- [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",
308
462
  },
309
463
  run: async (ctx) => {
310
464
  const f = ctx.flags;
@@ -320,6 +474,9 @@ export const worktreesCommand = {
320
474
  if (named !== undefined && workflow !== "ship") {
321
475
  throw new CommandError(EXIT.USAGE, "--branch is ship only");
322
476
  }
477
+ if (f.issue !== undefined && workflow !== "ship") {
478
+ throw new CommandError(EXIT.USAGE, "--issue is ship only");
479
+ }
323
480
  if (named !== undefined && !runGit(ctx.cwd, ["check-ref-format", "--branch", named]).ok) {
324
481
  throw new CommandError(EXIT.USAGE, `--branch "${named}" is not a valid branch name`);
325
482
  }
@@ -331,7 +488,9 @@ export const worktreesCommand = {
331
488
  }
332
489
  const target = workflow === "ship" ? shipBranch(root, fid, named, session) : `feat/${fid}`;
333
490
  if (isSharedBranch(target)) {
334
- 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`);
335
494
  }
336
495
  // Ship mints only when the session is not already on the branch it ships:
337
496
  // that branch cannot be checked out in two places.
@@ -362,7 +521,7 @@ export const worktreesCommand = {
362
521
  }
363
522
  else if (workflow !== "debug" || session !== target) {
364
523
  // Debug adopts an existing feat/{fid}; it never mints a branch of its own.
365
- if (addWorktree(root, wtDir, target, workflow !== "debug"))
524
+ if (addWorktree(root, wtDir, target, workflow !== "debug", ctx.log))
366
525
  mode = "created";
367
526
  }
368
527
  }
@@ -373,19 +532,28 @@ export const worktreesCommand = {
373
532
  if (workflow === "ship" && git(root, ["branch", "--show-current"]) !== target) {
374
533
  const sw = runGit(root, ["switch", target]);
375
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
+ }
376
538
  throw new CommandError(EXIT_REFUSED, `adopt mode: cannot switch to ${target} — commit or stash local changes, then re-run (${sw.stderr})`);
377
539
  }
378
540
  }
379
541
  const here = git(root, ["branch", "--show-current"]) ?? "";
380
- const refused = workflow === "debug" ? "main" : DEV;
381
- 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")) {
382
544
  throw new CommandError(EXIT_REFUSED, here === ""
383
545
  ? "adopt mode: detached HEAD — check out the feature branch"
384
546
  : `adopt mode: current branch is ${here} — refusing to work in place on ${here}`);
385
547
  }
386
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;
387
554
  let rebaseConflict = false;
388
555
  let sentinel = null;
556
+ let carried = null;
389
557
  const sentinelPath = path.join(logDir, ".rebase-failed");
390
558
  if (mode === "resumed" && workflow !== "ship") {
391
559
  // Cleared before every attempt: a sentinel left by an earlier run would
@@ -393,23 +561,38 @@ export const worktreesCommand = {
393
561
  fs.rmSync(sentinelPath, { force: true });
394
562
  let failure;
395
563
  if (rebaseInProgress(wt)) {
396
- failure = { conflict: true, detail: "a rebase is already in progress" };
564
+ failure = {
565
+ conflict: true,
566
+ detail: "a rebase is already in progress",
567
+ onto: devBase(wt),
568
+ };
397
569
  }
398
570
  else {
399
571
  fetchBranch(wt, DEV);
400
- const rb = runGit(wt, ["rebase", "--rebase-merges", ORIGIN_DEV]);
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);
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"]);
401
583
  if (!rb.ok) {
402
584
  failure = {
403
585
  conflict: rebaseInProgress(wt),
404
586
  detail: [rb.stdout, rb.stderr].filter(Boolean).join("\n"),
587
+ onto,
405
588
  };
406
589
  }
407
590
  }
408
591
  if (failure) {
409
592
  fs.mkdirSync(logDir, { recursive: true });
410
- fs.appendFileSync(path.join(logDir, "rebase-resolve-log.md"), `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${ORIGIN_DEV} stopped\n${failure.detail}\n`);
593
+ fs.appendFileSync(path.join(logDir, "rebase-resolve-log.md"), `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${failure.onto} stopped\n${failure.detail}\n`);
411
594
  fs.writeFileSync(sentinelPath, "");
412
- ctx.log(`rebase onto ${ORIGIN_DEV} failed in ${wt}: ${failure.detail.split("\n")[0]}`);
595
+ ctx.log(`rebase onto ${failure.onto} failed in ${wt}: ${failure.detail.split("\n")[0]}`);
413
596
  rebaseConflict = failure.conflict;
414
597
  sentinel = sentinelPath;
415
598
  }
@@ -423,21 +606,37 @@ export const worktreesCommand = {
423
606
  const { copied, copyMissing } = done
424
607
  ? copyListed(root, wt, config.worktreeCopy, ctx.log)
425
608
  : { copied: [], copyMissing: [] };
609
+ const direnvAllowed = done && allowDirenv(root, wt, ctx.log);
426
610
  const wantInstall = done && config.worktreeInstall;
427
611
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
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);
428
619
  ctx.emit({
429
620
  worktreePath: wt,
430
621
  repoRoot: root,
431
- branch: git(wt, ["branch", "--show-current"]) ?? "",
622
+ branch,
432
623
  mode,
624
+ branchWarning,
433
625
  owned: fs.existsSync(marker),
434
626
  rebaseConflict,
435
627
  sentinel,
436
628
  logDir,
437
- baseSha: git(wt, ["merge-base", ORIGIN_DEV, "HEAD"]),
629
+ baseRef,
630
+ baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
631
+ carriedSha: carried?.sha ?? null,
632
+ carriedDropped: carried?.dropped ?? [],
438
633
  copied,
439
634
  copyMissing,
635
+ direnvAllowed,
440
636
  installed: wantInstall && installStatus === 0,
637
+ ...(shared === undefined
638
+ ? {}
639
+ : { startSha: shared.startSha, aheadAtStart: shared.aheadAtStart }),
441
640
  });
442
641
  if (sentinel !== null)
443
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",