@cbartens/bkit 5.5.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -11,6 +11,7 @@ import * as fs from "node:fs";
11
11
  import * as path from "node:path";
12
12
 
13
13
  import { CommandError, EXIT, type CommandSpec, type FlagSpec, type RunContext } from "../lib.js";
14
+ import { COMMENT_FILE_OUTPUT, GENERATED_MARKER, commentFileOf, stampMarker } from "./tracker.js";
14
15
 
15
16
  /** Exit code: no workstream parsed — the workflow's Failure Path. */
16
17
  export const EXIT_NONE = 3;
@@ -91,14 +92,15 @@ export function commentBody(
91
92
  ): string {
92
93
  const doc = `docs/plans/${opts.month}/${opts.fid}-design.md`;
93
94
  const url = `https://github.com/${opts.ownerRepo}/blob/dev/${doc}`;
94
- return [
95
- "###### bkit:generated",
95
+ const lines = [
96
+ GENERATED_MARKER,
96
97
  "### Step 11 — Suggested Workstreams",
97
98
  "Advisory only. NEVER auto-trigger.",
98
99
  ...ws.map((w) => `- ${w.id}: ${w.name}. Requires: ${requiresList(w)}`),
99
100
  `Filing one issue per workstream: put \`**Parent design:** [${opts.fid}-design.md](${url})\` in its body, and list the issues it requires in a blocked-by block (.bkit/trackers.md § Issue shapes).`,
100
101
  `[${doc}](${url})`,
101
- ].join("\n");
102
+ ];
103
+ return stampMarker(lines.join("\n"));
102
104
  }
103
105
 
104
106
  const ARTIFACT_FLAG: FlagSpec = {
@@ -149,7 +151,11 @@ export const workstreamsCommand: CommandSpec = {
149
151
  help: "owner/repo for the design doc link",
150
152
  },
151
153
  ],
152
- output: { comment: "the comment body", workstreams: "the parsed workstreams" },
154
+ output: {
155
+ comment: "the comment body",
156
+ commentFile: COMMENT_FILE_OUTPUT,
157
+ workstreams: "the parsed workstreams",
158
+ },
153
159
  exitCodes: { [EXIT_NONE]: "no workstream parsed (Failure Path)" },
154
160
  run: (ctx) => {
155
161
  const workstreams = read(ctx);
@@ -158,7 +164,7 @@ export const workstreamsCommand: CommandSpec = {
158
164
  month: String(ctx.flags.month),
159
165
  fid: String(ctx.flags.fid),
160
166
  });
161
- ctx.emit({ comment: body, workstreams });
167
+ ctx.emit({ comment: body, commentFile: commentFileOf(ctx.cwd, body), workstreams });
162
168
  return EXIT.OK;
163
169
  },
164
170
  },
@@ -8,12 +8,16 @@
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
 
13
16
  import { spawnSync } from "node:child_process";
14
17
  import * as fs from "node:fs";
15
18
  import * as path from "node:path";
16
19
 
20
+ import { lastRun } from "../../ledgers/status.js";
17
21
  import { gitEnv } from "../../ledgers/telemetry.js";
18
22
  import { readBkitConfig } from "../../shared/settings.js";
19
23
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
@@ -23,13 +27,23 @@ import {
23
27
  EXIT,
24
28
  git,
25
29
  isSharedBranch,
30
+ MAIN,
26
31
  repoRoot,
27
32
  runGit,
28
33
  type CommandSpec,
29
34
  } from "../lib.js";
30
35
  import { ensureDiskSpace } from "./disk.js";
36
+ import {
37
+ listRecords,
38
+ newRecord,
39
+ readRecord,
40
+ removeRecord,
41
+ withSetupGuard,
42
+ writeRecord,
43
+ } from "./ledgers.js";
44
+ import { workflowLockFresh, workflowLockLive } from "./locks.js";
31
45
  import { detect } from "./runtime.js";
32
- import { WORKFLOW_FLAG } from "./status.js";
46
+ import { WORKFLOW_FLAG, readRuns } from "./status.js";
33
47
 
34
48
  const WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
35
49
  const ORIGIN_DEV = `origin/${DEV}`;
@@ -44,6 +58,7 @@ export const EXIT_REBASE_NOT_STARTED = 9;
44
58
  export const EXIT_NOT_A_WORKTREE = 10;
45
59
  export const EXIT_REMOVE = 11;
46
60
  export const EXIT_DISK_FULL = 12;
61
+ export const EXIT_SHARED_BUSY = 13;
47
62
 
48
63
  const FID_FLAG = { name: "fid", type: "string", required: true, help: "feature id" } as const;
49
64
 
@@ -108,6 +123,41 @@ function fetchBranch(cwd: string, branch: string): void {
108
123
  }
109
124
  }
110
125
 
126
+ /**
127
+ * The shared-checkout record for an in-place run on `dev`. Another feature's
128
+ * record with a live workflow lock means that run owns the checkout; one
129
+ * without is left over and removed. The same feature with an open run in
130
+ * `{logDir}/status.jsonl` is a resume and keeps its record; a new run rewrites it.
131
+ */
132
+ function openSharedRecord(root: string, fid: string, workflow: string, logDir: string) {
133
+ const busy = (other: string) =>
134
+ new CommandError(
135
+ EXIT_SHARED_BUSY,
136
+ `${other} is running in this checkout (workflow lock held) — wait for it to finish, then re-run`,
137
+ );
138
+ const guarded = withSetupGuard(root, () => {
139
+ for (const other of listRecords(root)) {
140
+ if (other.fid === fid) continue;
141
+ // A closed run that has not released its lock still pushes and waits for CI.
142
+ if (workflowLockLive(root, other.fid) || workflowLockFresh(root, other.fid)) {
143
+ throw busy(other.fid);
144
+ }
145
+ removeRecord(root, other.fid);
146
+ }
147
+ const existing = readRecord(root, fid);
148
+ const statusFile = path.join(logDir, "status.jsonl");
149
+ const open =
150
+ fs.existsSync(statusFile) &&
151
+ lastRun(readRuns(statusFile), workflow)?.status === "IN_PROGRESS";
152
+ if (existing !== null && existing.branch === DEV && open) return existing;
153
+ const fresh = newRecord(root, fid, DEV);
154
+ writeRecord(root, fresh);
155
+ return fresh;
156
+ });
157
+ if (guarded === null) throw busy("another run");
158
+ return guarded.value;
159
+ }
160
+
111
161
  /** Ship's branch: the one the prompt names, else `feat/{fid}` when it exists, else the session's. */
112
162
  function shipBranch(root: string, fid: string, named: string | undefined, session: string) {
113
163
  if (named) return named;
@@ -116,12 +166,42 @@ function shipBranch(root: string, fid: string, named: string | undefined, sessio
116
166
  return isSharedBranch(session) || session === "" ? feat : session;
117
167
  }
118
168
 
169
+ /**
170
+ * The ref a feature branch starts from and rebases onto: local `dev` when it is
171
+ * strictly ahead of `origin/dev` (a fast-forward of it), else `origin/dev`. With
172
+ * `log`, says why when the two differ. Fetch first for a current answer.
173
+ */
174
+ export function devBase(cwd: string, log?: (m: string) => void): string {
175
+ const local = git(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${DEV}`]);
176
+ const remote = git(cwd, ["rev-parse", "-q", "--verify", `refs/remotes/${ORIGIN_DEV}`]);
177
+ if (local === null || remote === null || local === remote) return ORIGIN_DEV;
178
+ const count = (range: string) => git(cwd, ["rev-list", "--count", range]) ?? "?";
179
+ if (runGit(cwd, ["merge-base", "--is-ancestor", remote, local]).ok) {
180
+ log?.(
181
+ `local ${DEV} is ${count(`${remote}..${local}`)} commit(s) ahead of ${ORIGIN_DEV} — basing on local ${DEV}; push ${DEV} before the feature PR`,
182
+ );
183
+ return DEV;
184
+ }
185
+ if (!runGit(cwd, ["merge-base", "--is-ancestor", local, remote]).ok) {
186
+ log?.(
187
+ `local ${DEV} and ${ORIGIN_DEV} have diverged — basing on ${ORIGIN_DEV}; local ${DEV}'s ${count(`${remote}..${local}`)} commit(s) are not in this worktree`,
188
+ );
189
+ }
190
+ return ORIGIN_DEV;
191
+ }
192
+
119
193
  /**
120
194
  * `git worktree add` for `branch`: the local branch, else a tracking branch off
121
- * `origin`, else (when `mayCreate`) a new branch off a freshly fetched
122
- * `origin/dev`. Returns false when there was nothing to add and `mayCreate` is off.
195
+ * `origin`, else (when `mayCreate`) a new branch off `devBase` after a fresh
196
+ * fetch. Returns false when there was nothing to add and `mayCreate` is off.
123
197
  */
124
- function addWorktree(root: string, wt: string, branch: string, mayCreate: boolean): boolean {
198
+ function addWorktree(
199
+ root: string,
200
+ wt: string,
201
+ branch: string,
202
+ mayCreate: boolean,
203
+ log: (m: string) => void,
204
+ ): boolean {
125
205
  let args: string[];
126
206
  if (hasLocal(root, branch)) {
127
207
  args = [wt, branch];
@@ -135,7 +215,7 @@ function addWorktree(root: string, wt: string, branch: string, mayCreate: boolea
135
215
  args = [wt, "--track", "-b", branch, `origin/${branch}`];
136
216
  } else if (mayCreate) {
137
217
  fetchBranch(root, DEV);
138
- args = [wt, "-b", branch, ORIGIN_DEV];
218
+ args = [wt, "-b", branch, devBase(root, log)];
139
219
  } else {
140
220
  return false;
141
221
  }
@@ -152,6 +232,61 @@ function rebaseInProgress(wt: string): boolean {
152
232
  });
153
233
  }
154
234
 
235
+ /**
236
+ * `git add -A` in `tree`, leaving out the `bkit.workflows.worktree.copy` entries setup
237
+ * copies in from the main checkout (`.env` and the like): no bkit commit may
238
+ * carry them, gitignored or not.
239
+ */
240
+ export function addAllButCopied(
241
+ tree: string,
242
+ copied: string[] = readBkitConfig(tree).worktreeCopy,
243
+ ): ReturnType<typeof runGit> {
244
+ const keep = copied.map((e) => `:(exclude)${path.normalize(e)}`);
245
+ return runGit(tree, ["add", "-A", "--", ".", ...keep]);
246
+ }
247
+
248
+ /**
249
+ * Commit what an earlier run left uncommitted in a resumed worktree, so the
250
+ * resume rebase can start: a failed ship's flush lands its record on dev and
251
+ * leaves the worktree as it was, for whatever runs next. An untracked file in a
252
+ * log folder of this feature that `onto` already holds is dropped first: dev's
253
+ * copy, landed by that flush, wins, and a second copy would stop the rebase.
254
+ * The `worktreeCopy` entries setup copies in are never committed. Clean tree →
255
+ * null; a failed commit is narrated and leaves the tree for the rebase to refuse.
256
+ */
257
+ function carryLeftovers(
258
+ wt: string,
259
+ o: { fid: string; onto: string; statusFile: string; copied: string[] },
260
+ log: (m: string) => void,
261
+ ): { sha: string | null; dropped: string[] } | null {
262
+ const dirty = () => (git(wt, ["status", "--porcelain", "--untracked-files=all"]) ?? "") !== "";
263
+ if (!dirty()) return null;
264
+ const logs = new RegExp(`^docs/plans/[^/]+/logs/${o.fid.replace(/\./g, "\\.")}/`);
265
+ const dropped = (git(wt, ["ls-files", "--others", "--exclude-standard"]) ?? "")
266
+ .split("\n")
267
+ .filter((f) => logs.test(f) && runGit(wt, ["cat-file", "-e", `${o.onto}:${f}`]).ok);
268
+ for (const f of dropped) fs.rmSync(path.join(wt, f));
269
+ if (dropped.length > 0)
270
+ log(
271
+ `dropped ${dropped.length} untracked log(s) ${o.onto} already holds: ${dropped.join(", ")}`,
272
+ );
273
+ if (!dirty()) return { sha: null, dropped };
274
+
275
+ const prior = fs.existsSync(o.statusFile) ? readRuns(o.statusFile).at(-1) : undefined;
276
+ const what =
277
+ prior === undefined
278
+ ? "uncommitted work left in the worktree"
279
+ : `the ${prior.status === "FAILED" ? "failed " : ""}${prior.workflow} record left uncommitted`;
280
+ addAllButCopied(wt, o.copied);
281
+ const made = runGit(wt, ["commit", "-m", `chore(${o.fid}): carry ${what} bkit`]);
282
+ if (!made.ok) {
283
+ log(`could not commit what an earlier run left in ${wt}: ${made.stderr || made.stdout}`);
284
+ return { sha: null, dropped };
285
+ }
286
+ log(`committed ${what} before the resume rebase`);
287
+ return { sha: git(wt, ["rev-parse", "HEAD"]), dropped };
288
+ }
289
+
155
290
  // ---------------------------------------------------------------------------
156
291
  // Copy and install
157
292
  // ---------------------------------------------------------------------------
@@ -180,6 +315,34 @@ function copyListed(root: string, wt: string, entries: string[], log: (m: string
180
315
  return { copied, copyMissing };
181
316
  }
182
317
 
318
+ /**
319
+ * `direnv allow` the worktree's `.envrc` when it matches the main checkout's
320
+ * byte for byte, so the worktree inherits the trust given there and nothing
321
+ * more; a differing file is left for a human to read. No `.envrc`, direnv
322
+ * missing or failing → false, narrated, never fatal.
323
+ */
324
+ function allowDirenv(root: string, wt: string, log: (m: string) => void): boolean {
325
+ const envrc = path.join(wt, ".envrc");
326
+ if (!fs.existsSync(envrc)) return false;
327
+ const main = path.join(root, ".envrc");
328
+ if (!fs.existsSync(main) || !fs.readFileSync(main).equals(fs.readFileSync(envrc))) {
329
+ log(
330
+ `direnv: ${envrc} differs from the main checkout's — not allowed; read it, then run direnv allow`,
331
+ );
332
+ return false;
333
+ }
334
+ const res = spawnSync("direnv", ["allow", wt], { cwd: wt, encoding: "utf-8" });
335
+ if (res.error || res.status === 127) {
336
+ log("direnv: not installed — run direnv allow in the worktree once it is");
337
+ return false;
338
+ }
339
+ if (res.status !== 0) {
340
+ log(`direnv allow failed (exit ${res.status}): ${(res.stderr ?? "").trim()}`);
341
+ return false;
342
+ }
343
+ return true;
344
+ }
345
+
183
346
  /** Run the frozen install in `wt`; the exit status, with a spawn failure read as "could not run". */
184
347
  function install(wt: string, log: (m: string) => void): number {
185
348
  const [cmd, ...args] = installCommand({ frozen: true });
@@ -298,6 +461,17 @@ export function removeWorktree(
298
461
  // Command
299
462
  // ---------------------------------------------------------------------------
300
463
 
464
+ /**
465
+ * The warning ship prints when the branch it ships names neither the FID nor the
466
+ * issue (case-insensitive); null when it names one. A hand-made branch still ships.
467
+ */
468
+ export function shipBranchWarning(branch: string, fid: string, issue?: string): string | null {
469
+ const b = branch.toLowerCase();
470
+ const id = (issue ?? "").replace(/^#/, "").toLowerCase();
471
+ if (b.includes(fid.toLowerCase()) || (id !== "" && b.includes(id))) return null;
472
+ return `[bkit-ship] WARNING branch ${branch} not named for ${fid} — shipping it as named`;
473
+ }
474
+
301
475
  export const worktreesCommand: CommandSpec = {
302
476
  noun: "worktrees",
303
477
  summary: "Set up and remove the per-feature worktrees under .worktrees/.",
@@ -323,21 +497,40 @@ export const worktreesCommand: CommandSpec = {
323
497
  type: "string",
324
498
  help: "ship only: the branch the session prompt names (default: feat/{fid} when it exists, else the session branch)",
325
499
  },
500
+ {
501
+ name: "issue",
502
+ type: "string",
503
+ help: "ship only: the issue id; a branch naming it (or the FID) prints no branchWarning",
504
+ },
326
505
  ],
327
506
  output: {
328
507
  worktreePath: "directory the workflow must cd into",
329
508
  repoRoot: "the main checkout",
330
509
  branch: "branch checked out at worktreePath",
331
510
  mode: "created | resumed | adopted",
511
+ branchWarning:
512
+ "ship: the warning printed when the branch names neither the FID nor --issue, else null",
332
513
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
333
514
  rebaseConflict:
334
- "a resume rebase onto origin/dev stopped on a conflict and is left in progress",
515
+ "a resume rebase onto baseRef stopped on a conflict and is left in progress",
335
516
  sentinel: "the .rebase-failed sentinel written on a failed rebase, else null",
336
517
  logDir: "docs/plans/{month}/logs/{fid} under worktreePath (created)",
337
- baseSha: "git merge-base origin/dev HEAD at worktreePath, or null",
518
+ baseRef:
519
+ "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
520
+ baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
521
+ carriedSha:
522
+ "resume: the commit holding what an earlier run left uncommitted (a failed ship's record), made before the rebase; else null",
523
+ carriedDropped:
524
+ "resume: untracked logs of this feature dropped because baseRef already holds them (dev's copy wins)",
338
525
  copied: "worktree copy entries copied from the main checkout",
339
526
  copyMissing: "worktree copy entries absent from the main checkout",
527
+ direnvAllowed:
528
+ "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
340
529
  installed: "dependencies were installed",
530
+ startSha:
531
+ "in place on dev (debug): HEAD when the run started, recorded in the shared-checkout record; absent otherwise",
532
+ aheadAtStart:
533
+ "in place on dev (debug): commits local dev held beyond origin/dev when the run started; absent otherwise",
341
534
  },
342
535
  exitCodes: {
343
536
  [EXIT_REBASE_CONFLICT]:
@@ -346,12 +539,15 @@ export const worktreesCommand: CommandSpec = {
346
539
  [EXIT_INSTALL]: "dependency install failed",
347
540
  [EXIT_INSTALL_COULD_NOT_RUN]: "the package manager could not run (exit 126 / 127)",
348
541
  [EXIT_REFUSED]:
349
- "refused: dev / main as the working branch, detached HEAD, or ship could not switch to its branch",
542
+ "refused: main as the working branch (dev too, except debug in place), ship of dev / main, detached HEAD, or ship could not switch to its branch (a missing feat/{fid} is named)",
350
543
  [EXIT_WORKTREE_ADD]: "git worktree add failed",
351
- [EXIT_REBASE_NOT_STARTED]: "resume rebase could not start (e.g. uncommitted changes)",
544
+ [EXIT_REBASE_NOT_STARTED]:
545
+ "resume rebase could not start, even after committing what an earlier run left (e.g. a commit hook refused that commit)",
352
546
  [EXIT_NOT_A_WORKTREE]: ".worktrees/{fid} exists but is not a registered git worktree",
547
+ [EXIT_SHARED_BUSY]:
548
+ "in place on dev: another feature's run holds this checkout (its shared-checkout record has a live workflow lock); nothing written",
353
549
  [EXIT_DISK_FULL]:
354
- "free disk under bkit.disk.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
550
+ "free disk under bkit.workflows.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
355
551
  },
356
552
  run: async (ctx) => {
357
553
  const f = ctx.flags;
@@ -366,6 +562,9 @@ export const worktreesCommand: CommandSpec = {
366
562
  if (named !== undefined && workflow !== "ship") {
367
563
  throw new CommandError(EXIT.USAGE, "--branch is ship only");
368
564
  }
565
+ if (f.issue !== undefined && workflow !== "ship") {
566
+ throw new CommandError(EXIT.USAGE, "--issue is ship only");
567
+ }
369
568
  if (named !== undefined && !runGit(ctx.cwd, ["check-ref-format", "--branch", named]).ok) {
370
569
  throw new CommandError(EXIT.USAGE, `--branch "${named}" is not a valid branch name`);
371
570
  }
@@ -381,7 +580,12 @@ export const worktreesCommand: CommandSpec = {
381
580
  }
382
581
  const target = workflow === "ship" ? shipBranch(root, fid, named, session) : `feat/${fid}`;
383
582
  if (isSharedBranch(target)) {
384
- throw new CommandError(EXIT_REFUSED, `refusing to ship ${target} as a feature branch`);
583
+ throw new CommandError(
584
+ EXIT_REFUSED,
585
+ workflow === "ship"
586
+ ? `refusing to ship ${target}: /bkit-ship ships a feature branch into ${DEV} only; it never opens a PR from ${DEV} into ${MAIN} or merges into ${MAIN}, releases stay manual. Name the feature branch to ship.`
587
+ : `refusing to ship ${target} as a feature branch`,
588
+ );
385
589
  }
386
590
 
387
591
  // Ship mints only when the session is not already on the branch it ships:
@@ -415,7 +619,7 @@ export const worktreesCommand: CommandSpec = {
415
619
  mode = "resumed";
416
620
  } else if (workflow !== "debug" || session !== target) {
417
621
  // Debug adopts an existing feat/{fid}; it never mints a branch of its own.
418
- if (addWorktree(root, wtDir, target, workflow !== "debug")) mode = "created";
622
+ if (addWorktree(root, wtDir, target, workflow !== "debug", ctx.log)) mode = "created";
419
623
  }
420
624
  }
421
625
  const wt = mode === "adopted" ? root : wtDir;
@@ -426,6 +630,12 @@ export const worktreesCommand: CommandSpec = {
426
630
  if (workflow === "ship" && git(root, ["branch", "--show-current"]) !== target) {
427
631
  const sw = runGit(root, ["switch", target]);
428
632
  if (!sw.ok) {
633
+ if (!hasLocal(root, target) && remoteHas(root, target) !== "yes") {
634
+ throw new CommandError(
635
+ EXIT_REFUSED,
636
+ `${target} does not exist — name the feature branch to ship`,
637
+ );
638
+ }
429
639
  throw new CommandError(
430
640
  EXIT_REFUSED,
431
641
  `adopt mode: cannot switch to ${target} — commit or stash local changes, then re-run (${sw.stderr})`,
@@ -433,8 +643,8 @@ export const worktreesCommand: CommandSpec = {
433
643
  }
434
644
  }
435
645
  const here = git(root, ["branch", "--show-current"]) ?? "";
436
- const refused = workflow === "debug" ? "main" : DEV;
437
- if (here === "" || here === refused) {
646
+ // Debug may work in place on dev (its shared-checkout path); nothing works in place on main.
647
+ if (here === "" || here === MAIN || (here === DEV && workflow !== "debug")) {
438
648
  throw new CommandError(
439
649
  EXIT_REFUSED,
440
650
  here === ""
@@ -444,23 +654,49 @@ export const worktreesCommand: CommandSpec = {
444
654
  }
445
655
  }
446
656
 
657
+ // An in-place run on a shared branch records what was dirty before it, so its
658
+ // commits and push take only its own work.
659
+ const shared =
660
+ mode === "adopted" && isSharedBranch(git(root, ["branch", "--show-current"]) ?? "")
661
+ ? openSharedRecord(root, fid, workflow, logDir)
662
+ : undefined;
663
+
447
664
  let rebaseConflict = false;
448
665
  let sentinel: string | null = null;
666
+ let carried: ReturnType<typeof carryLeftovers> = null;
449
667
  const sentinelPath = path.join(logDir, ".rebase-failed");
450
668
  if (mode === "resumed" && workflow !== "ship") {
451
669
  // Cleared before every attempt: a sentinel left by an earlier run would
452
670
  // send this one to the Failure Path after a clean rebase.
453
671
  fs.rmSync(sentinelPath, { force: true });
454
- let failure: { conflict: boolean; detail: string } | undefined;
672
+ let failure: { conflict: boolean; detail: string; onto: string } | undefined;
455
673
  if (rebaseInProgress(wt)) {
456
- failure = { conflict: true, detail: "a rebase is already in progress" };
674
+ failure = {
675
+ conflict: true,
676
+ detail: "a rebase is already in progress",
677
+ onto: devBase(wt),
678
+ };
457
679
  } else {
458
680
  fetchBranch(wt, DEV);
459
- const rb = runGit(wt, ["rebase", "--rebase-merges", ORIGIN_DEV]);
681
+ const onto = devBase(wt, ctx.log);
682
+ carried = carryLeftovers(
683
+ wt,
684
+ {
685
+ fid,
686
+ onto,
687
+ statusFile: path.join(logDir, "status.jsonl"),
688
+ copied: config.worktreeCopy,
689
+ },
690
+ ctx.log,
691
+ );
692
+ const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
693
+ // The rebase replays the carry commit on top: report the replayed one.
694
+ if (rb.ok && carried?.sha) carried.sha = git(wt, ["rev-parse", "HEAD"]);
460
695
  if (!rb.ok) {
461
696
  failure = {
462
697
  conflict: rebaseInProgress(wt),
463
698
  detail: [rb.stdout, rb.stderr].filter(Boolean).join("\n"),
699
+ onto,
464
700
  };
465
701
  }
466
702
  }
@@ -468,10 +704,12 @@ export const worktreesCommand: CommandSpec = {
468
704
  fs.mkdirSync(logDir, { recursive: true });
469
705
  fs.appendFileSync(
470
706
  path.join(logDir, "rebase-resolve-log.md"),
471
- `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${ORIGIN_DEV} stopped\n${failure.detail}\n`,
707
+ `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${failure.onto} stopped\n${failure.detail}\n`,
472
708
  );
473
709
  fs.writeFileSync(sentinelPath, "");
474
- ctx.log(`rebase onto ${ORIGIN_DEV} failed in ${wt}: ${failure.detail.split("\n")[0]}`);
710
+ ctx.log(
711
+ `rebase onto ${failure.onto} failed in ${wt}: ${failure.detail.split("\n")[0]}`,
712
+ );
475
713
  rebaseConflict = failure.conflict;
476
714
  sentinel = sentinelPath;
477
715
  }
@@ -486,22 +724,38 @@ export const worktreesCommand: CommandSpec = {
486
724
  const { copied, copyMissing } = done
487
725
  ? copyListed(root, wt, config.worktreeCopy, ctx.log)
488
726
  : { copied: [], copyMissing: [] };
727
+ const direnvAllowed = done && allowDirenv(root, wt, ctx.log);
489
728
  const wantInstall = done && config.worktreeInstall;
490
729
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
491
730
 
731
+ const baseRef = devBase(wt);
732
+ const branch = git(wt, ["branch", "--show-current"]) ?? "";
733
+ const branchWarning =
734
+ workflow === "ship"
735
+ ? shipBranchWarning(branch, fid, f.issue === undefined ? undefined : String(f.issue))
736
+ : null;
737
+ if (branchWarning !== null) ctx.log(branchWarning);
492
738
  ctx.emit({
493
739
  worktreePath: wt,
494
740
  repoRoot: root,
495
- branch: git(wt, ["branch", "--show-current"]) ?? "",
741
+ branch,
496
742
  mode,
743
+ branchWarning,
497
744
  owned: fs.existsSync(marker),
498
745
  rebaseConflict,
499
746
  sentinel,
500
747
  logDir,
501
- baseSha: git(wt, ["merge-base", ORIGIN_DEV, "HEAD"]),
748
+ baseRef,
749
+ baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
750
+ carriedSha: carried?.sha ?? null,
751
+ carriedDropped: carried?.dropped ?? [],
502
752
  copied,
503
753
  copyMissing,
754
+ direnvAllowed,
504
755
  installed: wantInstall && installStatus === 0,
756
+ ...(shared === undefined
757
+ ? {}
758
+ : { startSha: shared.startSha, aheadAtStart: shared.aheadAtStart }),
505
759
  });
506
760
  if (sentinel !== null)
507
761
  return rebaseConflict ? EXIT_REBASE_CONFLICT : EXIT_REBASE_NOT_STARTED;
@@ -65,7 +65,7 @@ export type ModuleName =
65
65
  export const ISSUE_TRACKERS = ["github", "linear", "jira", "none"] as const;
66
66
  export type IssueTracker = (typeof ISSUE_TRACKERS)[number];
67
67
 
68
- /** Default tracker when consumer manifest has no `bkit.issueTracker` field. */
68
+ /** Default tracker when consumer manifest has no `bkit.tracker.default` field. */
69
69
  export const DEFAULT_ISSUE_TRACKER: IssueTracker = "none";
70
70
 
71
71
  /**
@@ -94,17 +94,17 @@ export function parseIssueTracker(value: unknown): IssueTracker | null {
94
94
  * presence). Requires `tracker=github` + local opencode host (`bkit install --opencode=<provider>`).
95
95
  * - `none` — explicit opt-out; silences the post-install nudge advisory.
96
96
  *
97
- * Recorded in `package.json` `bkit.cloudAgents`. Presence of the adopted copy
97
+ * Recorded in `package.json` `bkit.cloud.agent`. Presence of the adopted copy
98
98
  * (`bkit-cloud.yml` for github-host variants; `.cursor/Dockerfile` for cursor) is the authoritative
99
99
  * "active" signal; the package.json field only distinguishes an opt-out from
100
100
  * an undecided install.
101
101
  *
102
- * Single self-describing field (mirrors `bkit.issueTracker`).
102
+ * Single self-describing field (mirrors `bkit.tracker.default`).
103
103
  */
104
104
  export const CLOUD_MODES = ["claude", "cursor", "opencode", "none"] as const;
105
105
  export type CloudAgents = (typeof CLOUD_MODES)[number];
106
106
 
107
- /** Default when consumer manifest has no `bkit.cloudAgents` field (undecided). */
107
+ /** Default when consumer manifest has no `bkit.cloud.agent` field (undecided). */
108
108
  export const DEFAULT_CLOUD_AGENTS: CloudAgents = "none";
109
109
 
110
110
  /** Narrow an unknown string to `CloudAgents` or return `null` if invalid. */
@@ -138,6 +138,7 @@ const CORE_MANIFEST: ManifestEntry[] = [
138
138
  // consumer copies are force-overwritten mirrors (writeTier1) so a consumer can read
139
139
  // them in-repo. Whole file is bkit-owned → byte-equal-text (refreshed every install);
140
140
  // prompts.md and lite.md are markered-text, keeping the consumer section below `bkit:end`.
141
+ { path: ".bkit/authoring.md", format: "byte-equal-text", module: "core" },
141
142
  { path: ".bkit/cloud.md", format: "byte-equal-text", module: "core" },
142
143
  { path: ".bkit/comparison.md", format: "byte-equal-text", module: "core" },
143
144
  { path: ".bkit/install.md", format: "byte-equal-text", module: "core" },
@@ -208,7 +209,7 @@ const CLAUDE_MANIFEST: ManifestEntry[] = [
208
209
  // (bkit-tests-static / -unit / -integration / -e2e / -live). Where a step is not a
209
210
  // tier (`format`, the ship gate) the name spells out the actual steps. One exception:
210
211
  // `min` sits off the chain: the least a push runs, on a push that changes no code
211
- // (`bkit.minPushPaths`); its steps are whatever that push can still break.
212
+ // (`bkit.testing.minPushPaths`); its steps are whatever that push can still break.
212
213
  //
213
214
  // The consumer owns every value: a turbo monorepo writes `turbo run … --filter`,
214
215
  // a Python repo writes `ruff check && pytest`. bkit never reads a value — only
@@ -238,7 +239,7 @@ export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
238
239
  // `.husky/pre-commit`: prettier --write over staged files, and nothing else —
239
240
  // seconds, not minutes. Prose is a whole-repo scan, so it gates at pre-push.
240
241
  "bkit:gate:format": "pnpm lint-staged",
241
- // `.husky/pre-push` on a min push (every file matches `bkit.minPushPaths`): no code, so
242
+ // `.husky/pre-push` on a min push (every file matches `bkit.testing.minPushPaths`): no code, so
242
243
  // no typecheck, lint or tests. Off the chain. Add any test that reads a min-push file.
243
244
  "bkit:gate:min": "pnpm format:check && pnpm lint:prose && pnpm slop:delta",
244
245
  // Everything that needs no test runner. Every part has a matching step in the
@@ -248,7 +249,7 @@ export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
248
249
  "bkit:gate:static":
249
250
  "pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta",
250
251
  // The default local gate: `.husky/pre-push` (when no `…-integration` gate is declared),
251
- // build Step 14, the remediates. `pnpm test` is the unit tier only: a test file the
252
+ // build Step 11, the remediates. `pnpm test` is the unit tier only: a test file the
252
253
  // integration gate also runs must not match it.
253
254
  "bkit:gate:static-unit": "pnpm bkit:gate:static && pnpm test",
254
255
  // Ship's conflict-resolve, the only caller whose dependency graph may have just
@@ -277,11 +278,12 @@ export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
277
278
  export const BKIT_DEBUG_GATES: readonly string[] = [
278
279
  "bkit:gate:static-unit-integration-e2e-live",
279
280
  "bkit:gate:static-unit-integration-e2e",
281
+ "bkit:gate:static-unit-integration",
280
282
  "bkit:gate:static-unit",
281
283
  ];
282
284
 
283
285
  /**
284
- * What `/bkit-build` Step 14 will run, in DESCENDING order — first one declared wins.
286
+ * What `/bkit-build` Step 11 will run, in DESCENDING order — first one declared wins.
285
287
  *
286
288
  * Build stops at integration; E2E and live are not in this list.
287
289
  *
@@ -497,7 +499,7 @@ export const ANTIGRAVITY_MANIFEST: ManifestEntry[] = [
497
499
  // (bkit-cloud.yml), bkit-cloud-bootstrap.sh and the Cursor Background Agent files
498
500
  // (.cursor/Dockerfile, .cursor/environment.json) ship as templates
499
501
  // (`.bkit/templates.md`); the consumer copies and owns them. Each variant only
500
- // records `bkit.cloudAgents` and prints its setup advisories.
502
+ // records `bkit.cloud.agent` and prints its setup advisories.
501
503
  export const CLOUD_MANIFEST_CLAUDE: ManifestEntry[] = [];
502
504
 
503
505
  export const CLOUD_MANIFEST_OPENCODE: ManifestEntry[] = [];