@cbartens/bkit 6.0.0 → 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 (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -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 +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  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 +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -13,13 +13,15 @@
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 { lastRun } from "../../ledgers/status.js";
19
- 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";
20
22
  import { readBkitConfig } from "../../shared/settings.js";
21
23
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
22
- import { CommandError, DEV, EXIT, git, isSharedBranch, MAIN, repoRoot, runGit, } from "../lib.js";
24
+ import { CommandError, DEV, EXIT, git, isIgnoredPath, isSharedBranch, MAIN, mainCheckoutRoot, repoRoot, runGit, } from "../lib.js";
23
25
  import { ensureDiskSpace } from "./disk.js";
24
26
  import { listRecords, newRecord, readRecord, removeRecord, withSetupGuard, writeRecord, } from "./ledgers.js";
25
27
  import { workflowLockFresh, workflowLockLive } from "./locks.js";
@@ -152,12 +154,54 @@ export function devBase(cwd, log) {
152
154
  }
153
155
  return ORIGIN_DEV;
154
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
+ }
155
199
  /**
156
200
  * `git worktree add` for `branch`: the local branch, else a tracking branch off
157
- * `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
158
202
  * fetch. Returns false when there was nothing to add and `mayCreate` is off.
159
203
  */
160
- function addWorktree(root, wt, branch, mayCreate, log) {
204
+ function addWorktree(root, wt, branch, mayCreate, workflow, log) {
161
205
  let args;
162
206
  if (hasLocal(root, branch)) {
163
207
  args = [wt, branch];
@@ -173,7 +217,7 @@ function addWorktree(root, wt, branch, mayCreate, log) {
173
217
  }
174
218
  else if (mayCreate) {
175
219
  fetchBranch(root, DEV);
176
- args = [wt, "-b", branch, devBase(root, log)];
220
+ args = [wt, "-b", branch, worktreeBase(root, workflow, log)];
177
221
  }
178
222
  else {
179
223
  return false;
@@ -184,6 +228,20 @@ function addWorktree(root, wt, branch, mayCreate, log) {
184
228
  throw new CommandError(EXIT_WORKTREE_ADD, `git worktree add failed: ${res.stderr}`);
185
229
  return true;
186
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
+ }
187
245
  function rebaseInProgress(wt) {
188
246
  return ["rebase-merge", "rebase-apply"].some((p) => {
189
247
  const dir = git(wt, ["rev-parse", "--path-format=absolute", "--git-path", p]);
@@ -191,42 +249,154 @@ function rebaseInProgress(wt) {
191
249
  });
192
250
  }
193
251
  /**
194
- * `git add -A` in `tree`, leaving out the `bkit.workflows.worktree.copy` entries setup
195
- * copies in from the main checkout (`.env` and the like): no bkit commit may
196
- * carry them, gitignored or not.
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.
197
274
  */
198
- export function addAllButCopied(tree, copied = readBkitConfig(tree).worktreeCopy) {
199
- const keep = copied.map((e) => `:(exclude)${path.normalize(e)}`);
200
- return runGit(tree, ["add", "-A", "--", ".", ...keep]);
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 "";
201
361
  }
202
362
  /**
203
363
  * Commit what an earlier run left uncommitted in a resumed worktree, so the
204
364
  * resume rebase can start: a failed ship's flush lands its record on dev and
205
365
  * leaves the worktree as it was, for whatever runs next. An untracked file in a
206
366
  * log folder of this feature that `onto` already holds is dropped first: dev's
207
- * copy, landed by that flush, wins, and a second copy would stop the rebase.
208
- * The `worktreeCopy` entries setup copies in are never committed. Clean tree →
209
- * null; a failed commit is narrated and leaves the tree for the rebase to refuse.
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.
210
372
  */
211
373
  function carryLeftovers(wt, o, log) {
212
- const dirty = () => (git(wt, ["status", "--porcelain", "--untracked-files=all"]) ?? "") !== "";
213
- if (!dirty())
374
+ if (!hasLeftovers(wt))
214
375
  return null;
215
376
  const logs = new RegExp(`^docs/plans/[^/]+/logs/${o.fid.replace(/\./g, "\\.")}/`);
216
377
  const dropped = (git(wt, ["ls-files", "--others", "--exclude-standard"]) ?? "")
217
378
  .split("\n")
218
379
  .filter((f) => logs.test(f) && runGit(wt, ["cat-file", "-e", `${o.onto}:${f}`]).ok);
219
- for (const f of dropped)
220
- fs.rmSync(path.join(wt, f));
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
+ }
221
391
  if (dropped.length > 0)
222
392
  log(`dropped ${dropped.length} untracked log(s) ${o.onto} already holds: ${dropped.join(", ")}`);
223
- if (!dirty())
393
+ if (!hasLeftovers(wt))
224
394
  return { sha: null, dropped };
225
395
  const prior = fs.existsSync(o.statusFile) ? readRuns(o.statusFile).at(-1) : undefined;
226
396
  const what = prior === undefined
227
397
  ? "uncommitted work left in the worktree"
228
398
  : `the ${prior.status === "FAILED" ? "failed " : ""}${prior.workflow} record left uncommitted`;
229
- addAllButCopied(wt, o.copied);
399
+ addAllButCopied(wt);
230
400
  const made = runGit(wt, ["commit", "-m", `chore(${o.fid}): carry ${what} bkit`]);
231
401
  if (!made.ok) {
232
402
  log(`could not commit what an earlier run left in ${wt}: ${made.stderr || made.stdout}`);
@@ -244,7 +414,7 @@ function copyListed(root, wt, entries, log) {
244
414
  const copyMissing = [];
245
415
  for (const entry of entries) {
246
416
  const rel = path.normalize(entry);
247
- if (rel.startsWith("..") || path.isAbsolute(rel)) {
417
+ if (!insideCheckout(rel)) {
248
418
  log(`worktree copy: ${entry} is outside the main checkout — skipped`);
249
419
  continue;
250
420
  }
@@ -261,6 +431,61 @@ function copyListed(root, wt, entries, log) {
261
431
  }
262
432
  return { copied, copyMissing };
263
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
+ }
264
489
  /**
265
490
  * `direnv allow` the worktree's `.envrc` when it matches the main checkout's
266
491
  * byte for byte, so the worktree inherits the trust given there and nothing
@@ -402,6 +627,7 @@ export const worktreesCommand = {
402
627
  verbs: {
403
628
  setup: {
404
629
  summary: "Create, resume or adopt the feature's worktree (Step 2 — Worktree Setup).",
630
+ use: "workflow",
405
631
  flags: [
406
632
  WORKFLOW_FLAG,
407
633
  FID_FLAG,
@@ -419,7 +645,7 @@ export const worktreesCommand = {
419
645
  {
420
646
  name: "branch",
421
647
  type: "string",
422
- 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",
423
649
  },
424
650
  {
425
651
  name: "issue",
@@ -440,9 +666,10 @@ export const worktreesCommand = {
440
666
  baseRef: "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
441
667
  baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
442
668
  carriedSha: "resume: the commit holding what an earlier run left uncommitted (a failed ship's record), made before the rebase; else null",
443
- carriedDropped: "resume: untracked logs of this feature dropped because baseRef already holds them (dev's copy wins)",
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",
444
670
  copied: "worktree copy entries copied from the main checkout",
445
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",
446
673
  direnvAllowed: "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
447
674
  installed: "dependencies were installed",
448
675
  startSha: "in place on dev (debug): HEAD when the run started, recorded in the shared-checkout record; absent otherwise",
@@ -453,7 +680,7 @@ export const worktreesCommand = {
453
680
  [EXIT_FETCH]: "could not fetch from origin",
454
681
  [EXIT_INSTALL]: "dependency install failed",
455
682
  [EXIT_INSTALL_COULD_NOT_RUN]: "the package manager could not run (exit 126 / 127)",
456
- [EXIT_REFUSED]: "refused: main as the working branch (dev too, except debug in place), ship of dev / main, detached HEAD, or ship could not switch to its branch (a missing feat/{fid} is named)",
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)",
457
684
  [EXIT_WORKTREE_ADD]: "git worktree add failed",
458
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)",
459
686
  [EXIT_NOT_A_WORKTREE]: ".worktrees/{fid} exists but is not a registered git worktree",
@@ -471,8 +698,8 @@ export const worktreesCommand = {
471
698
  if (!/^[0-9]{6}$/.test(month))
472
699
  throw new CommandError(EXIT.USAGE, "--month must be YYYYMM");
473
700
  const named = f.branch === undefined ? undefined : String(f.branch);
474
- if (named !== undefined && workflow !== "ship") {
475
- 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");
476
703
  }
477
704
  if (f.issue !== undefined && workflow !== "ship") {
478
705
  throw new CommandError(EXIT.USAGE, "--issue is ship only");
@@ -486,12 +713,22 @@ export const worktreesCommand = {
486
713
  if (workflow === "debug" && session === "") {
487
714
  throw new CommandError(EXIT_REFUSED, "detached HEAD — check out a branch before debugging");
488
715
  }
489
- const target = workflow === "ship" ? shipBranch(root, fid, named, session) : `feat/${fid}`;
490
- if (isSharedBranch(target)) {
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)) {
491
722
  throw new CommandError(EXIT_REFUSED, workflow === "ship"
492
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.`
493
724
  : `refusing to ship ${target} as a feature branch`);
494
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`);
731
+ }
495
732
  // Ship mints only when the session is not already on the branch it ships:
496
733
  // that branch cannot be checked out in two places.
497
734
  if (f.worktrees === true && f.detect === true)
@@ -517,11 +754,16 @@ export const worktreesCommand = {
517
754
  if (real(git(wtDir, ["rev-parse", "--show-toplevel"]) ?? "") !== real(wtDir)) {
518
755
  throw new CommandError(EXIT_NOT_A_WORKTREE, `${wtDir} is not a registered git worktree`);
519
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
+ }
520
762
  mode = "resumed";
521
763
  }
522
764
  else if (workflow !== "debug" || session !== target) {
523
765
  // Debug adopts an existing feat/{fid}; it never mints a branch of its own.
524
- if (addWorktree(root, wtDir, target, workflow !== "debug", ctx.log))
766
+ if (addWorktree(root, wtDir, target, workflow !== "debug", workflow, ctx.log))
525
767
  mode = "created";
526
768
  }
527
769
  }
@@ -529,6 +771,9 @@ export const worktreesCommand = {
529
771
  const logDir = logDirOf(wt, month, fid);
530
772
  const marker = ownershipMarker(root, fid);
531
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
+ }
532
777
  if (workflow === "ship" && git(root, ["branch", "--show-current"]) !== target) {
533
778
  const sw = runGit(root, ["switch", target]);
534
779
  if (!sw.ok) {
@@ -555,6 +800,16 @@ export const worktreesCommand = {
555
800
  let sentinel = null;
556
801
  let carried = null;
557
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
+ }
558
813
  if (mode === "resumed" && workflow !== "ship") {
559
814
  // Cleared before every attempt: a sentinel left by an earlier run would
560
815
  // send this one to the Failure Path after a clean rebase.
@@ -564,26 +819,36 @@ export const worktreesCommand = {
564
819
  failure = {
565
820
  conflict: true,
566
821
  detail: "a rebase is already in progress",
567
- onto: devBase(wt),
822
+ onto: worktreeBase(wt, workflow),
568
823
  };
569
824
  }
570
825
  else {
571
826
  fetchBranch(wt, DEV);
572
- const onto = devBase(wt, ctx.log);
573
- carried = carryLeftovers(wt, {
574
- fid,
575
- onto,
576
- statusFile: path.join(logDir, "status.jsonl"),
577
- copied: config.worktreeCopy,
578
- }, ctx.log);
579
- const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
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);
580
843
  // The rebase replays the carry commit on top: report the replayed one.
581
844
  if (rb.ok && carried?.sha)
582
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"]));
583
848
  if (!rb.ok) {
584
849
  failure = {
585
850
  conflict: rebaseInProgress(wt),
586
- detail: [rb.stdout, rb.stderr].filter(Boolean).join("\n"),
851
+ detail: [rb.stdout, rb.stderr, unput].filter(Boolean).join("\n"),
587
852
  onto,
588
853
  };
589
854
  }
@@ -606,10 +871,11 @@ export const worktreesCommand = {
606
871
  const { copied, copyMissing } = done
607
872
  ? copyListed(root, wt, config.worktreeCopy, ctx.log)
608
873
  : { copied: [], copyMissing: [] };
874
+ const bkitEnv = done ? linkBkitEnv(root, wt, fid, ctx.log) : null;
609
875
  const direnvAllowed = done && allowDirenv(root, wt, ctx.log);
610
- const wantInstall = done && config.worktreeInstall;
876
+ const wantInstall = done && config.worktreeInstall && fs.existsSync(path.join(wt, "package.json"));
611
877
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
612
- const baseRef = devBase(wt);
878
+ const baseRef = worktreeBase(wt, workflow);
613
879
  const branch = git(wt, ["branch", "--show-current"]) ?? "";
614
880
  const branchWarning = workflow === "ship"
615
881
  ? shipBranchWarning(branch, fid, f.issue === undefined ? undefined : String(f.issue))
@@ -632,6 +898,7 @@ export const worktreesCommand = {
632
898
  carriedDropped: carried?.dropped ?? [],
633
899
  copied,
634
900
  copyMissing,
901
+ bkitEnv,
635
902
  direnvAllowed,
636
903
  installed: wantInstall && installStatus === 0,
637
904
  ...(shared === undefined
@@ -653,6 +920,7 @@ export const worktreesCommand = {
653
920
  },
654
921
  remove: {
655
922
  summary: "Remove .worktrees/{fid} when a workflow created it, prune stale entries, and delete the feature branch.",
923
+ use: "workflow",
656
924
  flags: [
657
925
  FID_FLAG,
658
926
  {