@cbartens/bkit 5.5.1 → 6.1.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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -13,15 +13,20 @@
13
13
  // a human, so local dev is routinely ahead, and a worktree without those commits
14
14
  // builds against superseded work.
15
15
  import { spawnSync } from "node:child_process";
16
+ import { createHash } from "node:crypto";
16
17
  import * as fs from "node:fs";
17
18
  import * as path from "node:path";
18
- import { gitEnv } from "../../ledgers/telemetry.js";
19
+ import { actionHash, actionKey, lastRun, recordAction } from "../../ledgers/status.js";
20
+ import { APPEND_LEDGERS, gitEnv } from "../../ledgers/telemetry.js";
21
+ import { parseJson } from "../../shared/json.js";
19
22
  import { readBkitConfig } from "../../shared/settings.js";
20
23
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
21
- import { CommandError, DEV, EXIT, git, isSharedBranch, repoRoot, runGit, } from "../lib.js";
24
+ import { CommandError, DEV, EXIT, git, isIgnoredPath, isSharedBranch, MAIN, mainCheckoutRoot, repoRoot, runGit, } from "../lib.js";
22
25
  import { ensureDiskSpace } from "./disk.js";
26
+ import { listRecords, newRecord, readRecord, removeRecord, withSetupGuard, writeRecord, } from "./ledgers.js";
27
+ import { workflowLockFresh, workflowLockLive } from "./locks.js";
23
28
  import { detect } from "./runtime.js";
24
- import { WORKFLOW_FLAG } from "./status.js";
29
+ import { WORKFLOW_FLAG, readRuns } from "./status.js";
25
30
  const WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
26
31
  const ORIGIN_DEV = `origin/${DEV}`;
27
32
  export const EXIT_REBASE_CONFLICT = 3;
@@ -34,6 +39,7 @@ export const EXIT_REBASE_NOT_STARTED = 9;
34
39
  export const EXIT_NOT_A_WORKTREE = 10;
35
40
  export const EXIT_REMOVE = 11;
36
41
  export const EXIT_DISK_FULL = 12;
42
+ export const EXIT_SHARED_BUSY = 13;
37
43
  const FID_FLAG = { name: "fid", type: "string", required: true, help: "feature id" };
38
44
  function fidOf(value) {
39
45
  const fid = String(value);
@@ -87,6 +93,38 @@ function fetchBranch(cwd, branch) {
87
93
  throw new CommandError(EXIT_FETCH, `could not fetch origin ${branch}: ${res.stderr}`);
88
94
  }
89
95
  }
96
+ /**
97
+ * The shared-checkout record for an in-place run on `dev`. Another feature's
98
+ * record with a live workflow lock means that run owns the checkout; one
99
+ * without is left over and removed. The same feature with an open run in
100
+ * `{logDir}/status.jsonl` is a resume and keeps its record; a new run rewrites it.
101
+ */
102
+ function openSharedRecord(root, fid, workflow, logDir) {
103
+ 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`);
104
+ const guarded = withSetupGuard(root, () => {
105
+ for (const other of listRecords(root)) {
106
+ if (other.fid === fid)
107
+ continue;
108
+ // A closed run that has not released its lock still pushes and waits for CI.
109
+ if (workflowLockLive(root, other.fid) || workflowLockFresh(root, other.fid)) {
110
+ throw busy(other.fid);
111
+ }
112
+ removeRecord(root, other.fid);
113
+ }
114
+ const existing = readRecord(root, fid);
115
+ const statusFile = path.join(logDir, "status.jsonl");
116
+ const open = fs.existsSync(statusFile) &&
117
+ lastRun(readRuns(statusFile), workflow)?.status === "IN_PROGRESS";
118
+ if (existing !== null && existing.branch === DEV && open)
119
+ return existing;
120
+ const fresh = newRecord(root, fid, DEV);
121
+ writeRecord(root, fresh);
122
+ return fresh;
123
+ });
124
+ if (guarded === null)
125
+ throw busy("another run");
126
+ return guarded.value;
127
+ }
90
128
  /** Ship's branch: the one the prompt names, else `feat/{fid}` when it exists, else the session's. */
91
129
  function shipBranch(root, fid, named, session) {
92
130
  if (named)
@@ -116,12 +154,54 @@ export function devBase(cwd, log) {
116
154
  }
117
155
  return ORIGIN_DEV;
118
156
  }
157
+ /** Workflows whose close lands docs and ledgers only: their branch may carry no unpushed dev work. */
158
+ const DOCS_ONLY_WORKFLOWS = ["design", "plan"];
159
+ /**
160
+ * The ref a feature branch starts from and rebases onto. A docs-only workflow
161
+ * (design, plan) always starts from `origin/dev`: its close lands docs and
162
+ * ledgers on `origin/dev` and may carry nothing else, so a branch holding
163
+ * unpushed `dev` commits could never land (issue #639). Every other workflow
164
+ * keeps `devBase`'s choice — local `dev` while it is a fast-forward of `origin/dev`.
165
+ */
166
+ export function worktreeBase(cwd, workflow, log) {
167
+ if (!DOCS_ONLY_WORKFLOWS.includes(workflow))
168
+ return devBase(cwd, log);
169
+ const local = git(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${DEV}`]);
170
+ const remote = git(cwd, ["rev-parse", "-q", "--verify", `refs/remotes/${ORIGIN_DEV}`]);
171
+ if (local !== null &&
172
+ remote !== null &&
173
+ local !== remote &&
174
+ runGit(cwd, ["merge-base", "--is-ancestor", remote, local]).ok) {
175
+ const count = git(cwd, ["rev-list", "--count", `${remote}..${local}`]) ?? "?";
176
+ log?.(`local ${DEV} is ${count} commit(s) ahead of ${ORIGIN_DEV} — basing this ${workflow} branch on ${ORIGIN_DEV}: its close lands docs and ledgers only`);
177
+ }
178
+ return ORIGIN_DEV;
179
+ }
180
+ /**
181
+ * The commits `branch` carries that local `dev` holds and `origin/dev` does not:
182
+ * work inherited from unpushed `dev`. A docs-only close lands on `origin/dev` and
183
+ * may bring docs and ledgers only, so such a branch can never land.
184
+ */
185
+ function inheritedDevCommits(root, branch) {
186
+ const unpushed = new Set((git(root, ["rev-list", `${ORIGIN_DEV}..${DEV}`]) ?? "").split("\n").filter(Boolean));
187
+ if (unpushed.size === 0)
188
+ return [];
189
+ return (git(root, ["rev-list", branch, "--not", ORIGIN_DEV]) ?? "")
190
+ .split("\n")
191
+ .filter((c) => unpushed.has(c));
192
+ }
193
+ /** Why a docs-only branch carrying unpushed `dev` cannot land, and what unblocks it. */
194
+ function inheritedDevRefusal(root, target, workflow, count) {
195
+ const ahead = git(root, ["rev-list", "--count", `${ORIGIN_DEV}..${DEV}`]) ?? "?";
196
+ const tip = git(root, ["rev-parse", "--short", DEV]) ?? DEV;
197
+ return `${target} carries ${count} commit(s) of unpushed ${DEV} (tip ${tip}, ${ahead} commit(s) ahead of ${ORIGIN_DEV}), and a ${workflow} close lands docs and ledgers only — this branch cannot land. Publish ${DEV} (git push origin ${DEV}), then re-run.`;
198
+ }
119
199
  /**
120
200
  * `git worktree add` for `branch`: the local branch, else a tracking branch off
121
- * `origin`, else (when `mayCreate`) a new branch off `devBase` after a fresh
201
+ * `origin`, else (when `mayCreate`) a new branch off `worktreeBase` after a fresh
122
202
  * fetch. Returns false when there was nothing to add and `mayCreate` is off.
123
203
  */
124
- function addWorktree(root, wt, branch, mayCreate, log) {
204
+ function addWorktree(root, wt, branch, mayCreate, workflow, log) {
125
205
  let args;
126
206
  if (hasLocal(root, branch)) {
127
207
  args = [wt, branch];
@@ -137,7 +217,7 @@ function addWorktree(root, wt, branch, mayCreate, log) {
137
217
  }
138
218
  else if (mayCreate) {
139
219
  fetchBranch(root, DEV);
140
- args = [wt, "-b", branch, devBase(root, log)];
220
+ args = [wt, "-b", branch, worktreeBase(root, workflow, log)];
141
221
  }
142
222
  else {
143
223
  return false;
@@ -148,12 +228,183 @@ function addWorktree(root, wt, branch, mayCreate, log) {
148
228
  throw new CommandError(EXIT_WORKTREE_ADD, `git worktree add failed: ${res.stderr}`);
149
229
  return true;
150
230
  }
231
+ /**
232
+ * An engine-action row for a rebase that rewrote the branch, keyed on the tip it
233
+ * replaced, so the run's record shows the rewrite. Nothing when HEAD did not move.
234
+ */
235
+ export function recordRebase(statusFile, before, after) {
236
+ if (before === null || after === null || before === after)
237
+ return;
238
+ recordAction(statusFile, {
239
+ action: "rebase",
240
+ key: actionKey("rebase", before),
241
+ hash: actionHash(`${before}..${after}`),
242
+ ref: after,
243
+ });
244
+ }
151
245
  function rebaseInProgress(wt) {
152
246
  return ["rebase-merge", "rebase-apply"].some((p) => {
153
247
  const dir = git(wt, ["rev-parse", "--path-format=absolute", "--git-path", p]);
154
248
  return dir !== null && fs.existsSync(dir);
155
249
  });
156
250
  }
251
+ /**
252
+ * bkit's own worktree copy entry, excluded from every bkit commit beside
253
+ * `bkit.workflows.worktree.copy`: it holds the sign-in tokens, and a consumer whose
254
+ * `.gitignore` lost bkit's `.bkit/.env` line would otherwise commit a link to them.
255
+ */
256
+ export const BKIT_OWN_COPY = [".bkit/.env"];
257
+ /** A normalized copy entry inside the checkout: neither absolute nor climbing out with `..`. */
258
+ const insideCheckout = (rel) => !path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${path.sep}`);
259
+ /**
260
+ * Every `bkit.workflows.worktree.copy` entry setup may have copied into `tree`: the
261
+ * tree's own `package.json` list and the main checkout's, which setup copies by and
262
+ * which an uncommitted edit or the feature branch can make differ.
263
+ */
264
+ function worktreeCopyLists(tree) {
265
+ const main = mainCheckoutRoot(tree) ?? tree;
266
+ return [...new Set([...readBkitConfig(tree).worktreeCopy, ...readBkitConfig(main).worktreeCopy])];
267
+ }
268
+ /**
269
+ * `:(exclude)` pathspecs for the entries setup copies into `tree` (`copied`, default
270
+ * every list that may name one) and `BKIT_OWN_COPY`. An entry outside the tree is left
271
+ * out: git refuses it as a pathspec (exit 128) and setup never copies it. So is one git
272
+ * already ignores: naming it in a `:(exclude)` pathspec trips git's ignored-paths guard
273
+ * and fails the whole `add`, and `git add -A` skips an ignored file anyway.
274
+ */
275
+ export function copyExcludes(tree, copied = worktreeCopyLists(tree)) {
276
+ return [...copied, ...BKIT_OWN_COPY]
277
+ .map((e) => path.normalize(e))
278
+ .filter((e) => insideCheckout(e) && !isIgnoredPath(tree, e))
279
+ .map((e) => `:(exclude)${e}`);
280
+ }
281
+ /**
282
+ * `git add -A` in `tree`, leaving out the entries setup copies in from the main
283
+ * checkout (`.env` and the like) and `BKIT_OWN_COPY` (`copyExcludes`): no bkit commit
284
+ * may carry them, gitignored or not.
285
+ */
286
+ export function addAllButCopied(tree, copied) {
287
+ return runGit(tree, ["add", "-A", "--", ".", ...copyExcludes(tree, copied)]);
288
+ }
289
+ /** Whether `wt` holds changes beyond the entries setup copies in (`copyExcludes`). */
290
+ export const hasLeftovers = (wt) => (git(wt, ["status", "--porcelain", "--untracked-files=all", "--", ".", ...copyExcludes(wt)]) ??
291
+ "") !== "";
292
+ /**
293
+ * The rows the dispatch seam appended after the last commit, by tracked path, when they
294
+ * are the only changes in `wt`: `engine-call` rows at the end of `statusFile`, and
295
+ * `friction` rows at the end of `.bkit/friction.jsonl` (a hook-launched command's
296
+ * unexpected exit). Null when anything else changed.
297
+ */
298
+ function journalRowsAppended(wt, statusFile) {
299
+ const allowed = new Map([
300
+ [path.relative(wt, statusFile), (row) => row["type"] === "engine-call"],
301
+ [APPEND_LEDGERS.friction.file, (row) => row["kind"] === "friction"],
302
+ ]);
303
+ const changed = (git(wt, ["status", "--porcelain", "--untracked-files=all", "--", ".", ...copyExcludes(wt)]) ??
304
+ "")
305
+ .split("\n")
306
+ .filter((l) => l !== "");
307
+ if (changed.length === 0)
308
+ return null;
309
+ const out = new Map();
310
+ for (const line of changed) {
311
+ const rel = [...allowed.keys()].find((r) => line.endsWith(` ${r}`));
312
+ const appended = rel === undefined ? null : appendedRows(wt, rel, allowed.get(rel));
313
+ if (rel === undefined || appended === null)
314
+ return null;
315
+ out.set(rel, appended);
316
+ }
317
+ return out;
318
+ }
319
+ /** `rel` as its committed text plus one or more appended rows `accepts` takes; null otherwise. */
320
+ function appendedRows(wt, rel, accepts) {
321
+ const committed = git(wt, ["cat-file", "blob", `HEAD:${rel}`]);
322
+ const file = path.join(wt, rel);
323
+ if (committed === null || !fs.existsSync(file))
324
+ return null;
325
+ const text = fs.readFileSync(file, "utf-8");
326
+ if (!text.startsWith(committed))
327
+ return null;
328
+ // `git` trims its output: the committed text's own last newline comes back with it.
329
+ const rest = text.slice(committed.length);
330
+ const lead = rest.startsWith("\n") ? "\n" : "";
331
+ const rows = rest.slice(lead.length);
332
+ const added = rows.split("\n").filter((l) => l.trim() !== "");
333
+ const ok = added.length > 0 &&
334
+ added.every((l) => {
335
+ const parsed = parseJson(l);
336
+ return (parsed.ok &&
337
+ parsed.value !== null &&
338
+ typeof parsed.value === "object" &&
339
+ !Array.isArray(parsed.value) &&
340
+ accepts(parsed.value));
341
+ });
342
+ return ok ? { committed: text.slice(0, committed.length) + lead, rows } : null;
343
+ }
344
+ /**
345
+ * Appends the rows `journalRowsAppended` set aside back onto their files and returns "".
346
+ * A rebase that stopped part-way cannot continue past unstaged rows, so then nothing is
347
+ * appended and the rows come back as text for the rebase log.
348
+ */
349
+ function putJournalRowsBack(wt, journal) {
350
+ if (rebaseInProgress(wt)) {
351
+ return [...journal]
352
+ .map(([rel, a]) => `rows set aside from ${rel}; append them once the rebase finishes:\n${a.rows}`)
353
+ .join("");
354
+ }
355
+ for (const [rel, a] of journal) {
356
+ const file = path.join(wt, rel);
357
+ const text = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
358
+ fs.appendFileSync(file, `${text !== "" && !text.endsWith("\n") ? "\n" : ""}${a.rows}`);
359
+ }
360
+ return "";
361
+ }
362
+ /**
363
+ * Commit what an earlier run left uncommitted in a resumed worktree, so the
364
+ * resume rebase can start: a failed ship's flush lands its record on dev and
365
+ * leaves the worktree as it was, for whatever runs next. An untracked file in a
366
+ * log folder of this feature that `onto` already holds is dropped first: dev's
367
+ * copy, landed by that flush, wins, and a second copy would stop the rebase. One
368
+ * whose content differs from `onto`'s is moved to the feature's outbox folder
369
+ * (`dropped-logs/{time}/`), never deleted. The entries setup copies in are never
370
+ * committed and alone do not count as leftovers. No leftovers → null; a failed
371
+ * commit is narrated and leaves the tree for the rebase to refuse.
372
+ */
373
+ function carryLeftovers(wt, o, log) {
374
+ if (!hasLeftovers(wt))
375
+ return null;
376
+ const logs = new RegExp(`^docs/plans/[^/]+/logs/${o.fid.replace(/\./g, "\\.")}/`);
377
+ const dropped = (git(wt, ["ls-files", "--others", "--exclude-standard"]) ?? "")
378
+ .split("\n")
379
+ .filter((f) => logs.test(f) && runGit(wt, ["cat-file", "-e", `${o.onto}:${f}`]).ok);
380
+ const keepDir = path.join(path.dirname(ownershipMarker(wt, o.fid)), "dropped-logs", new Date().toISOString().replace(/[:.]/g, "-"));
381
+ for (const f of dropped) {
382
+ const file = path.join(wt, f);
383
+ if (git(wt, ["hash-object", "--", f]) !== git(wt, ["rev-parse", `${o.onto}:${f}`])) {
384
+ const kept = path.join(keepDir, f);
385
+ fs.mkdirSync(path.dirname(kept), { recursive: true });
386
+ fs.cpSync(file, kept);
387
+ log(`moved ${f} to ${kept}: it differs from ${o.onto}'s copy, which wins in the worktree`);
388
+ }
389
+ fs.rmSync(file);
390
+ }
391
+ if (dropped.length > 0)
392
+ log(`dropped ${dropped.length} untracked log(s) ${o.onto} already holds: ${dropped.join(", ")}`);
393
+ if (!hasLeftovers(wt))
394
+ return { sha: null, dropped };
395
+ const prior = fs.existsSync(o.statusFile) ? readRuns(o.statusFile).at(-1) : undefined;
396
+ const what = prior === undefined
397
+ ? "uncommitted work left in the worktree"
398
+ : `the ${prior.status === "FAILED" ? "failed " : ""}${prior.workflow} record left uncommitted`;
399
+ addAllButCopied(wt);
400
+ const made = runGit(wt, ["commit", "-m", `chore(${o.fid}): carry ${what} bkit`]);
401
+ if (!made.ok) {
402
+ log(`could not commit what an earlier run left in ${wt}: ${made.stderr || made.stdout}`);
403
+ return { sha: null, dropped };
404
+ }
405
+ log(`committed ${what} before the resume rebase`);
406
+ return { sha: git(wt, ["rev-parse", "HEAD"]), dropped };
407
+ }
157
408
  // ---------------------------------------------------------------------------
158
409
  // Copy and install
159
410
  // ---------------------------------------------------------------------------
@@ -163,7 +414,7 @@ function copyListed(root, wt, entries, log) {
163
414
  const copyMissing = [];
164
415
  for (const entry of entries) {
165
416
  const rel = path.normalize(entry);
166
- if (rel.startsWith("..") || path.isAbsolute(rel)) {
417
+ if (!insideCheckout(rel)) {
167
418
  log(`worktree copy: ${entry} is outside the main checkout — skipped`);
168
419
  continue;
169
420
  }
@@ -180,6 +431,61 @@ function copyListed(root, wt, entries, log) {
180
431
  }
181
432
  return { copied, copyMissing };
182
433
  }
434
+ const sha256 = (content) => createHash("sha256").update(content).digest("hex");
435
+ /**
436
+ * bkit's own token file, `.bkit/.env`, in a worktree. `copyListed` covers the app env
437
+ * files a repo configures; this one is bkit's, and it is gitignored — so a fresh
438
+ * checkout has none, `.envrc`'s `dotenv_if_exists .bkit/.env` loads nothing and says
439
+ * nothing, and every sign-in here fails with nothing looking wrong.
440
+ *
441
+ * Link to the main checkout's copy: one source of truth, so rotating a token needs no
442
+ * second edit and no copy goes stale. Fall back to a copy where the filesystem refuses
443
+ * a symlink, recording its hash in the feature's outbox folder (`.bkit-env-copy`): a
444
+ * copy bkit made is replaced on the next setup, so a rotated token reaches it too. Any
445
+ * other regular file that differs from the main checkout's is left for a human to read,
446
+ * like a differing `.envrc`; `none` means the main checkout holds no `.bkit/.env` to
447
+ * bring in, which the tip and the advisory then report; `failed` means neither the link
448
+ * nor the copy could be written, narrated.
449
+ */
450
+ function linkBkitEnv(root, wt, fid, log) {
451
+ const main = path.join(root, ".bkit", ".env");
452
+ if (!fs.existsSync(main))
453
+ return "none";
454
+ const dest = path.join(wt, ".bkit", ".env");
455
+ const record = path.join(path.dirname(ownershipMarker(root, fid)), ".bkit-env-copy");
456
+ // lstat, so a dangling link is seen (and replaced) rather than followed and missed.
457
+ const stat = fs.lstatSync(dest, { throwIfNoEntry: false });
458
+ if (stat?.isSymbolicLink() && fs.existsSync(dest))
459
+ return "unchanged";
460
+ if (stat?.isFile()) {
461
+ const here = fs.readFileSync(dest);
462
+ const bkitMade = fs.existsSync(record) && fs.readFileSync(record, "utf-8") === sha256(here);
463
+ if (!bkitMade && !here.equals(fs.readFileSync(main))) {
464
+ log(`bkit-env: ${dest} differs from the main checkout's — left as it is; delete it to link the main checkout's copy`);
465
+ return "differs";
466
+ }
467
+ }
468
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
469
+ fs.rmSync(dest, { recursive: true, force: true });
470
+ try {
471
+ fs.symlinkSync(main, dest);
472
+ fs.rmSync(record, { force: true });
473
+ return "linked";
474
+ }
475
+ catch (err) {
476
+ try {
477
+ fs.cpSync(main, dest);
478
+ }
479
+ catch (copyErr) {
480
+ log(`bkit-env: could not link or copy the main checkout's .bkit/.env to ${dest} (${err.message}; ${copyErr.message}) — sign-ins in this worktree fail until it is there`);
481
+ return "failed";
482
+ }
483
+ fs.mkdirSync(path.dirname(record), { recursive: true });
484
+ fs.writeFileSync(record, sha256(fs.readFileSync(dest)));
485
+ log(`bkit-env: symlink failed (${err.message}) — copied the main checkout's .bkit/.env`);
486
+ return "copied";
487
+ }
488
+ }
183
489
  /**
184
490
  * `direnv allow` the worktree's `.envrc` when it matches the main checkout's
185
491
  * byte for byte, so the worktree inherits the trust given there and nothing
@@ -304,12 +610,24 @@ export function removeWorktree(cwd, fid, branch, log) {
304
610
  // ---------------------------------------------------------------------------
305
611
  // Command
306
612
  // ---------------------------------------------------------------------------
613
+ /**
614
+ * The warning ship prints when the branch it ships names neither the FID nor the
615
+ * issue (case-insensitive); null when it names one. A hand-made branch still ships.
616
+ */
617
+ export function shipBranchWarning(branch, fid, issue) {
618
+ const b = branch.toLowerCase();
619
+ const id = (issue ?? "").replace(/^#/, "").toLowerCase();
620
+ if (b.includes(fid.toLowerCase()) || (id !== "" && b.includes(id)))
621
+ return null;
622
+ return `[bkit-ship] WARNING branch ${branch} not named for ${fid} — shipping it as named`;
623
+ }
307
624
  export const worktreesCommand = {
308
625
  noun: "worktrees",
309
626
  summary: "Set up and remove the per-feature worktrees under .worktrees/.",
310
627
  verbs: {
311
628
  setup: {
312
629
  summary: "Create, resume or adopt the feature's worktree (Step 2 — Worktree Setup).",
630
+ use: "workflow",
313
631
  flags: [
314
632
  WORKFLOW_FLAG,
315
633
  FID_FLAG,
@@ -327,7 +645,12 @@ export const worktreesCommand = {
327
645
  {
328
646
  name: "branch",
329
647
  type: "string",
330
- help: "ship only: the branch the session prompt names (default: feat/{fid} when it exists, else the session branch)",
648
+ help: "ship or debug: an existing branch the session prompt names; debug refuses a conflicting checkout",
649
+ },
650
+ {
651
+ name: "issue",
652
+ type: "string",
653
+ help: "ship only: the issue id; a branch naming it (or the FID) prints no branchWarning",
331
654
  },
332
655
  ],
333
656
  output: {
@@ -335,27 +658,34 @@ export const worktreesCommand = {
335
658
  repoRoot: "the main checkout",
336
659
  branch: "branch checked out at worktreePath",
337
660
  mode: "created | resumed | adopted",
661
+ branchWarning: "ship: the warning printed when the branch names neither the FID nor --issue, else null",
338
662
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
339
663
  rebaseConflict: "a resume rebase onto baseRef stopped on a conflict and is left in progress",
340
664
  sentinel: "the .rebase-failed sentinel written on a failed rebase, else null",
341
665
  logDir: "docs/plans/{month}/logs/{fid} under worktreePath (created)",
342
666
  baseRef: "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
343
667
  baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
668
+ carriedSha: "resume: the commit holding what an earlier run left uncommitted (a failed ship's record), made before the rebase; else null",
669
+ carriedDropped: "resume: untracked logs of this feature dropped because baseRef already holds them (dev's copy wins); one whose content differs is first moved to the feature's outbox folder (dropped-logs/), named in the log",
344
670
  copied: "worktree copy entries copied from the main checkout",
345
671
  copyMissing: "worktree copy entries absent from the main checkout",
672
+ bkitEnv: "bkit's own .bkit/.env: linked to the main checkout's copy, or copied where a symlink is refused (a copy bkit made is refreshed on the next setup); unchanged when already linked, differs when a differing file was left to read, none when the main checkout holds none, failed when neither the link nor the copy could be written, null in adopt mode",
346
673
  direnvAllowed: "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
347
674
  installed: "dependencies were installed",
675
+ startSha: "in place on dev (debug): HEAD when the run started, recorded in the shared-checkout record; absent otherwise",
676
+ aheadAtStart: "in place on dev (debug): commits local dev held beyond origin/dev when the run started; absent otherwise",
348
677
  },
349
678
  exitCodes: {
350
679
  [EXIT_REBASE_CONFLICT]: "resume rebase stopped on a conflict, left in progress — run `bkit branches rebase`, then re-run setup; on its failure, Failure Path",
351
680
  [EXIT_FETCH]: "could not fetch from origin",
352
681
  [EXIT_INSTALL]: "dependency install failed",
353
682
  [EXIT_INSTALL_COULD_NOT_RUN]: "the package manager could not run (exit 126 / 127)",
354
- [EXIT_REFUSED]: "refused: dev / main as the working branch, detached HEAD, or ship could not switch to its branch",
683
+ [EXIT_REFUSED]: "refused: main as the working branch (dev too, except debug in place), ship of dev / main, detached HEAD, ship could not switch to its branch (a missing feat/{fid} is named), or a design / plan branch carrying unpushed dev commits (publish dev, then re-run)",
355
684
  [EXIT_WORKTREE_ADD]: "git worktree add failed",
356
- [EXIT_REBASE_NOT_STARTED]: "resume rebase could not start (e.g. uncommitted changes)",
685
+ [EXIT_REBASE_NOT_STARTED]: "resume rebase could not start, even after committing what an earlier run left (e.g. a commit hook refused that commit)",
357
686
  [EXIT_NOT_A_WORKTREE]: ".worktrees/{fid} exists but is not a registered git worktree",
358
- [EXIT_DISK_FULL]: "free disk under bkit.disk.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
687
+ [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",
688
+ [EXIT_DISK_FULL]: "free disk under bkit.workflows.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
359
689
  },
360
690
  run: async (ctx) => {
361
691
  const f = ctx.flags;
@@ -368,8 +698,11 @@ export const worktreesCommand = {
368
698
  if (!/^[0-9]{6}$/.test(month))
369
699
  throw new CommandError(EXIT.USAGE, "--month must be YYYYMM");
370
700
  const named = f.branch === undefined ? undefined : String(f.branch);
371
- if (named !== undefined && workflow !== "ship") {
372
- throw new CommandError(EXIT.USAGE, "--branch is ship only");
701
+ if (named !== undefined && workflow !== "ship" && workflow !== "debug") {
702
+ throw new CommandError(EXIT.USAGE, "--branch is ship or debug only");
703
+ }
704
+ if (f.issue !== undefined && workflow !== "ship") {
705
+ throw new CommandError(EXIT.USAGE, "--issue is ship only");
373
706
  }
374
707
  if (named !== undefined && !runGit(ctx.cwd, ["check-ref-format", "--branch", named]).ok) {
375
708
  throw new CommandError(EXIT.USAGE, `--branch "${named}" is not a valid branch name`);
@@ -380,9 +713,21 @@ export const worktreesCommand = {
380
713
  if (workflow === "debug" && session === "") {
381
714
  throw new CommandError(EXIT_REFUSED, "detached HEAD — check out a branch before debugging");
382
715
  }
383
- const target = workflow === "ship" ? shipBranch(root, fid, named, session) : `feat/${fid}`;
384
- if (isSharedBranch(target)) {
385
- throw new CommandError(EXIT_REFUSED, `refusing to ship ${target} as a feature branch`);
716
+ const target = workflow === "ship"
717
+ ? shipBranch(root, fid, named, session)
718
+ : workflow === "debug" && named
719
+ ? named
720
+ : `feat/${fid}`;
721
+ if (isSharedBranch(target) && !(workflow === "debug" && target === DEV)) {
722
+ throw new CommandError(EXIT_REFUSED, workflow === "ship"
723
+ ? `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.`
724
+ : `refusing to ship ${target} as a feature branch`);
725
+ }
726
+ if (workflow === "debug" &&
727
+ named &&
728
+ !hasLocal(root, target) &&
729
+ !runGit(root, ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${target}`]).ok) {
730
+ throw new CommandError(EXIT_REFUSED, `${target} does not exist — debug adopts an existing branch`);
386
731
  }
387
732
  // Ship mints only when the session is not already on the branch it ships:
388
733
  // that branch cannot be checked out in two places.
@@ -409,11 +754,16 @@ export const worktreesCommand = {
409
754
  if (real(git(wtDir, ["rev-parse", "--show-toplevel"]) ?? "") !== real(wtDir)) {
410
755
  throw new CommandError(EXIT_NOT_A_WORKTREE, `${wtDir} is not a registered git worktree`);
411
756
  }
757
+ if (workflow === "debug" &&
758
+ named &&
759
+ git(wtDir, ["branch", "--show-current"]) !== target) {
760
+ throw new CommandError(EXIT_REFUSED, `${wtDir} is on another branch; requested ${target} — leave its work intact and use the matching checkout`);
761
+ }
412
762
  mode = "resumed";
413
763
  }
414
764
  else if (workflow !== "debug" || session !== target) {
415
765
  // Debug adopts an existing feat/{fid}; it never mints a branch of its own.
416
- if (addWorktree(root, wtDir, target, workflow !== "debug", ctx.log))
766
+ if (addWorktree(root, wtDir, target, workflow !== "debug", workflow, ctx.log))
417
767
  mode = "created";
418
768
  }
419
769
  }
@@ -421,23 +771,45 @@ export const worktreesCommand = {
421
771
  const logDir = logDirOf(wt, month, fid);
422
772
  const marker = ownershipMarker(root, fid);
423
773
  if (mode === "adopted") {
774
+ if (workflow === "debug" && named && git(root, ["branch", "--show-current"]) !== target) {
775
+ throw new CommandError(EXIT_REFUSED, `adopt mode: checkout does not hold requested ${target}; use its existing checkout or enable worktrees`);
776
+ }
424
777
  if (workflow === "ship" && git(root, ["branch", "--show-current"]) !== target) {
425
778
  const sw = runGit(root, ["switch", target]);
426
779
  if (!sw.ok) {
780
+ if (!hasLocal(root, target) && remoteHas(root, target) !== "yes") {
781
+ throw new CommandError(EXIT_REFUSED, `${target} does not exist — name the feature branch to ship`);
782
+ }
427
783
  throw new CommandError(EXIT_REFUSED, `adopt mode: cannot switch to ${target} — commit or stash local changes, then re-run (${sw.stderr})`);
428
784
  }
429
785
  }
430
786
  const here = git(root, ["branch", "--show-current"]) ?? "";
431
- const refused = workflow === "debug" ? "main" : DEV;
432
- if (here === "" || here === refused) {
787
+ // Debug may work in place on dev (its shared-checkout path); nothing works in place on main.
788
+ if (here === "" || here === MAIN || (here === DEV && workflow !== "debug")) {
433
789
  throw new CommandError(EXIT_REFUSED, here === ""
434
790
  ? "adopt mode: detached HEAD — check out the feature branch"
435
791
  : `adopt mode: current branch is ${here} — refusing to work in place on ${here}`);
436
792
  }
437
793
  }
794
+ // An in-place run on a shared branch records what was dirty before it, so its
795
+ // commits and push take only its own work.
796
+ const shared = mode === "adopted" && isSharedBranch(git(root, ["branch", "--show-current"]) ?? "")
797
+ ? openSharedRecord(root, fid, workflow, logDir)
798
+ : undefined;
438
799
  let rebaseConflict = false;
439
800
  let sentinel = null;
801
+ let carried = null;
440
802
  const sentinelPath = path.join(logDir, ".rebase-failed");
803
+ // A docs-only branch cannot land while it carries unpushed dev work: refuse
804
+ // now, not after the whole phase. Checked before the resume rebase, which
805
+ // replays such commits under new SHAs this commit-by-commit check no longer
806
+ // knows; the close itself names them then.
807
+ if (DOCS_ONLY_WORKFLOWS.includes(workflow) && mode !== "adopted") {
808
+ const inherited = inheritedDevCommits(root, target);
809
+ if (inherited.length > 0) {
810
+ throw new CommandError(EXIT_REFUSED, inheritedDevRefusal(root, target, workflow, inherited.length));
811
+ }
812
+ }
441
813
  if (mode === "resumed" && workflow !== "ship") {
442
814
  // Cleared before every attempt: a sentinel left by an earlier run would
443
815
  // send this one to the Failure Path after a clean rebase.
@@ -447,17 +819,36 @@ export const worktreesCommand = {
447
819
  failure = {
448
820
  conflict: true,
449
821
  detail: "a rebase is already in progress",
450
- onto: devBase(wt),
822
+ onto: worktreeBase(wt, workflow),
451
823
  };
452
824
  }
453
825
  else {
454
826
  fetchBranch(wt, DEV);
455
- const onto = devBase(wt, ctx.log);
456
- const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
827
+ const onto = worktreeBase(wt, workflow, ctx.log);
828
+ const statusFile = path.join(logDir, "status.jsonl");
829
+ carried = carryLeftovers(wt, { fid, onto, statusFile }, ctx.log);
830
+ // Journal rows a hook appended after the carry commit go aside by hand and
831
+ // back after the rebase, never through `--autostash`: a dev that appended to
832
+ // the same file makes the autostash pop conflict, and git still exits 0.
833
+ const journal = hasLeftovers(wt) ? journalRowsAppended(wt, statusFile) : null;
834
+ for (const [rel, a] of journal ?? [])
835
+ fs.writeFileSync(path.join(wt, rel), a.committed);
836
+ // A tracked copy entry setup copied over (a committed placeholder `.env`) is
837
+ // never committed, so the rebase sets it aside and puts it back. Only when
838
+ // nothing else is left: a refused carry commit still stops the rebase.
839
+ const aside = hasLeftovers(wt) ? [] : ["--autostash"];
840
+ const before = git(wt, ["rev-parse", "HEAD"]);
841
+ const rb = runGit(wt, ["rebase", "--rebase-merges", ...aside, onto]);
842
+ const unput = journal === null ? "" : putJournalRowsBack(wt, journal);
843
+ // The rebase replays the carry commit on top: report the replayed one.
844
+ if (rb.ok && carried?.sha)
845
+ carried.sha = git(wt, ["rev-parse", "HEAD"]);
846
+ if (rb.ok)
847
+ recordRebase(path.join(logDir, "status.jsonl"), before, git(wt, ["rev-parse", "HEAD"]));
457
848
  if (!rb.ok) {
458
849
  failure = {
459
850
  conflict: rebaseInProgress(wt),
460
- detail: [rb.stdout, rb.stderr].filter(Boolean).join("\n"),
851
+ detail: [rb.stdout, rb.stderr, unput].filter(Boolean).join("\n"),
461
852
  onto,
462
853
  };
463
854
  }
@@ -480,25 +871,39 @@ export const worktreesCommand = {
480
871
  const { copied, copyMissing } = done
481
872
  ? copyListed(root, wt, config.worktreeCopy, ctx.log)
482
873
  : { copied: [], copyMissing: [] };
874
+ const bkitEnv = done ? linkBkitEnv(root, wt, fid, ctx.log) : null;
483
875
  const direnvAllowed = done && allowDirenv(root, wt, ctx.log);
484
- const wantInstall = done && config.worktreeInstall;
876
+ const wantInstall = done && config.worktreeInstall && fs.existsSync(path.join(wt, "package.json"));
485
877
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
486
- const baseRef = devBase(wt);
878
+ const baseRef = worktreeBase(wt, workflow);
879
+ const branch = git(wt, ["branch", "--show-current"]) ?? "";
880
+ const branchWarning = workflow === "ship"
881
+ ? shipBranchWarning(branch, fid, f.issue === undefined ? undefined : String(f.issue))
882
+ : null;
883
+ if (branchWarning !== null)
884
+ ctx.log(branchWarning);
487
885
  ctx.emit({
488
886
  worktreePath: wt,
489
887
  repoRoot: root,
490
- branch: git(wt, ["branch", "--show-current"]) ?? "",
888
+ branch,
491
889
  mode,
890
+ branchWarning,
492
891
  owned: fs.existsSync(marker),
493
892
  rebaseConflict,
494
893
  sentinel,
495
894
  logDir,
496
895
  baseRef,
497
896
  baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
897
+ carriedSha: carried?.sha ?? null,
898
+ carriedDropped: carried?.dropped ?? [],
498
899
  copied,
499
900
  copyMissing,
901
+ bkitEnv,
500
902
  direnvAllowed,
501
903
  installed: wantInstall && installStatus === 0,
904
+ ...(shared === undefined
905
+ ? {}
906
+ : { startSha: shared.startSha, aheadAtStart: shared.aheadAtStart }),
502
907
  });
503
908
  if (sentinel !== null)
504
909
  return rebaseConflict ? EXIT_REBASE_CONFLICT : EXIT_REBASE_NOT_STARTED;
@@ -515,6 +920,7 @@ export const worktreesCommand = {
515
920
  },
516
921
  remove: {
517
922
  summary: "Remove .worktrees/{fid} when a workflow created it, prune stale entries, and delete the feature branch.",
923
+ use: "workflow",
518
924
  flags: [
519
925
  FID_FLAG,
520
926
  {