@cbartens/bkit 6.1.0 → 6.2.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 (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -19,10 +19,15 @@ import * as os from "node:os";
19
19
  import * as path from "node:path";
20
20
 
21
21
  import { gitEnv } from "../../ledgers/telemetry.js";
22
- import { actionHash, actionKey, alreadyDone, recordAction } from "../../ledgers/status.js";
22
+ import {
23
+ actionHash,
24
+ actionKey,
25
+ alreadyDone,
26
+ recordAction,
27
+ withTargetLock,
28
+ } from "../../ledgers/status.js";
23
29
  import {
24
30
  bodySkipToken,
25
- classifyLockExit,
26
31
  CommandError,
27
32
  DEV,
28
33
  EXIT,
@@ -35,7 +40,6 @@ import {
35
40
  runGh,
36
41
  runGit,
37
42
  SKIP_CI_TOKEN,
38
- testsLockHolder,
39
43
  wholeNumber,
40
44
  type CommandSpec,
41
45
  type RunContext,
@@ -50,12 +54,15 @@ import { DEV_REFSPEC, fetchDev, landBackoffMs, landDir, pushToDev, sleep } from
50
54
  import { TIMEOUTS } from "../../shared/timeouts.js";
51
55
  import {
52
56
  activeRecord,
57
+ bookPathspecs,
58
+ checkOnlyBookkeeping,
53
59
  commitBookkeeping,
54
60
  markRecordPushed,
55
61
  recordOnBranch,
56
62
  type SharedCheckoutRecord,
57
63
  } from "./ledgers.js";
58
64
  import { releaseLock, resolveMonth, workflowLockPath } from "./locks.js";
65
+ import { underTestsLock } from "./junit.js";
59
66
  import {
60
67
  EXIT_BASE_NOT_DEV,
61
68
  FORCE_BUILD,
@@ -68,12 +75,16 @@ import {
68
75
  import { AUTO_LABEL, AUTO_ROUTE_SUFFIX } from "./issues.js";
69
76
  import { appendFeature } from "./roadmap.js";
70
77
  import { detect } from "./runtime.js";
78
+ import { defaultRange } from "./feature-base.js";
71
79
  import { readRuns, readStatusRows, readStatusRowsAt } from "./status.js";
72
80
  import { declaredName, testSource } from "./test-blocks.js";
73
81
  import {
74
82
  addAllButCopied,
83
+ assertShipEligible,
75
84
  copyExcludes,
76
85
  hasLeftovers,
86
+ notOnDev,
87
+ rebaseNoteFile,
77
88
  recordRebase,
78
89
  removeWorktree,
79
90
  worktreeDir,
@@ -605,16 +616,15 @@ export function resolveRebase(
605
616
  } else {
606
617
  return refuse("REFUSE — git rebase --skip failed", null, "git rebase --skip failed");
607
618
  }
608
- } else if (!quietGit(top, ["rebase", "--continue"]).ok) {
619
+ } else {
620
+ const cont = quietGit(top, ["rebase", "--continue"]);
609
621
  // The next commit conflicted (next round handles it), or the rebase is stuck.
610
- if (unmergedPaths(top).length === 0) {
611
- return refuse(
612
- "REFUSE — git rebase --continue failed with no unmerged paths",
613
- null,
614
- "git rebase --continue failed with no unmerged paths",
615
- );
622
+ if (!cont.ok && unmergedPaths(top).length === 0) {
623
+ const why = (cont.stderr || cont.stdout).replace(/\s*\n\s*/g, " ");
624
+ const reason = `git rebase --continue failed with no unmerged paths: ${why || "git gave no reason"}`;
625
+ return refuse(`REFUSE — ${reason}`, null, reason);
616
626
  }
617
- continue;
627
+ if (!cont.ok) continue;
618
628
  }
619
629
 
620
630
  if (!rebaseInProgress(top)) {
@@ -771,11 +781,21 @@ function topLevel(cwd: string): string {
771
781
  return top;
772
782
  }
773
783
 
774
- function appendLog(ctx: RunContext, file: string | undefined, lines: string[]): void {
775
- if (file === undefined || lines.length === 0) return;
784
+ /**
785
+ * Appends the resolution lines to the run's log, after the note `worktrees setup`
786
+ * held outside the tree while the rebase was paused (`rebaseNoteFile`), then drops
787
+ * the note. Called only once the rebase has finished or been aborted.
788
+ */
789
+ function appendLog(ctx: RunContext, top: string, file: string | undefined, lines: string[]): void {
790
+ if (file === undefined) return;
791
+ const noteFile = rebaseNoteFile(top);
792
+ const note =
793
+ noteFile !== null && fs.existsSync(noteFile) ? fs.readFileSync(noteFile, "utf-8") : "";
794
+ if (note === "" && lines.length === 0) return;
776
795
  const abs = path.resolve(ctx.cwd, file);
777
796
  fs.mkdirSync(path.dirname(abs), { recursive: true });
778
- fs.appendFileSync(abs, lines.map((l) => `[bkit-rebase] ${l}\n`).join(""));
797
+ fs.appendFileSync(abs, note + lines.map((l) => `[bkit-rebase] ${l}\n`).join(""));
798
+ if (noteFile !== null) fs.rmSync(noteFile, { force: true });
779
799
  }
780
800
 
781
801
  function rebaseVerb(ctx: RunContext): number {
@@ -814,7 +834,7 @@ function rebaseVerb(ctx: RunContext): number {
814
834
  },
815
835
  );
816
836
  }
817
- appendLog(ctx, str(ctx.flags.logFile), result.log);
837
+ appendLog(ctx, top, str(ctx.flags.logFile), result.log);
818
838
  if (!result.ok && sentinelPath) {
819
839
  fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
820
840
  fs.writeFileSync(sentinelPath, "");
@@ -867,23 +887,23 @@ export interface PushOutcome {
867
887
  };
868
888
  }
869
889
 
870
- /** Git collapses a failing pre-push hook's status; classify its exact tests-lock markers. */
890
+ /** Git collapses a failing pre-push hook's status, so the hook's tests-lock status file alone decides. */
871
891
  function runPush(cwd: string, args: string[], branch: string) {
872
892
  const who = `bkit branches push ${branch}`;
873
893
  const wait = wholeNumber(process.env.BKIT_LOCK_WAIT_S, "BKIT_LOCK_WAIT_S", 60);
874
- const res = runGit(cwd, args, {
875
- LOCAL_STACK_LOCK_WAIT_S: String(wait),
876
- LOCAL_STACK_LOCK_WHO: who,
894
+ let res: ReturnType<typeof runGit> | undefined;
895
+ const { status, lock } = underTestsLock((lockEnv) => {
896
+ res = runGit(cwd, args, {
897
+ LOCAL_STACK_LOCK_WAIT_S: String(wait),
898
+ LOCAL_STACK_LOCK_WHO: who,
899
+ ...lockEnv,
900
+ });
901
+ return res.ok ? 0 : null;
877
902
  });
878
- const log = [res.stdout, res.stderr].filter(Boolean).join("\n");
879
- const lockHolder = res.ok ? null : testsLockHolder(log, who);
880
- const outcome = res.ok
881
- ? "gate"
882
- : classifyLockExit({ exitCode: lockHolder === null ? 73 : 75, log, who });
883
903
  return {
884
- ...res,
885
- lockHolder,
886
- lockExit: outcome === "lock-wait" ? EXIT.AGENT_WAIT : outcome === "could-not-run" ? 4 : null,
904
+ ...res!,
905
+ lockHolder: lock === "lock-wait" ? (status?.holder ?? null) : null,
906
+ lockExit: lock === "lock-wait" ? EXIT.AGENT_WAIT : lock === "could-not-run" ? 4 : null,
887
907
  };
888
908
  }
889
909
 
@@ -1642,7 +1662,7 @@ export function disabledTestsIn(diff: string, root: string): DisabledTest[] {
1642
1662
  }
1643
1663
 
1644
1664
  function scanDiffVerb(ctx: RunContext): number {
1645
- const base = String(ctx.flags.base);
1665
+ const explicitBase = str(ctx.flags.base);
1646
1666
  const pattern = str(ctx.flags.paths);
1647
1667
  const marker = str(ctx.flags.marker);
1648
1668
  const code = ctx.flags.code === true;
@@ -1668,7 +1688,9 @@ function scanDiffVerb(ctx: RunContext): number {
1668
1688
  }
1669
1689
  }
1670
1690
  const top = topLevel(ctx.cwd);
1671
- const fetched = fetchRemoteRef(top, base);
1691
+ const fallback = explicitBase === undefined ? defaultRange(top, ctx.log) : null;
1692
+ const base = explicitBase ?? fallback!.base;
1693
+ const fetched = explicitBase === undefined ? null : fetchRemoteRef(top, base);
1672
1694
  if (fetched !== null && !fetched.ok) {
1673
1695
  ctx.log(`git fetch for ${base} failed: ${fetched.stderr} — diffing against the local ref`);
1674
1696
  }
@@ -1676,7 +1698,7 @@ function scanDiffVerb(ctx: RunContext): number {
1676
1698
  ctx.log(`unknown base: ${base}`);
1677
1699
  return EXIT_DIFF_FAILED;
1678
1700
  }
1679
- const range = `${base}...HEAD`;
1701
+ const range = fallback?.range ?? `${base}...HEAD`;
1680
1702
  if (disabled) {
1681
1703
  const diff = quietGit(top, ["diff", "--no-renames", range, "--", ".", ":(exclude)docs/plans"]);
1682
1704
  if (!diff.ok) {
@@ -2211,6 +2233,7 @@ export interface DevMerge {
2211
2233
 
2212
2234
  interface MergeDevOptions {
2213
2235
  branch: string;
2236
+ target?: string;
2214
2237
  policy: MergePolicy;
2215
2238
  /** The feature id in the commit messages (default: the branch name without feat/). */
2216
2239
  fid?: string;
@@ -2245,6 +2268,8 @@ function mergeDev(top: string, o: MergeDevOptions, log: (m: string) => void): De
2245
2268
  before: null,
2246
2269
  };
2247
2270
  const full = o.policy === "full";
2271
+ const target = o.target ?? UPSTREAM;
2272
+ const targetName = o.target ?? DEV;
2248
2273
  const fid = o.fid ?? o.branch.replace(/^feat\//, "");
2249
2274
  const refuse = (why: string): DevMerge => {
2250
2275
  const abort = runGit(top, ["merge", "--abort"]);
@@ -2253,25 +2278,33 @@ function mergeDev(top: string, o: MergeDevOptions, log: (m: string) => void): De
2253
2278
  return { ...out, code: EXIT_MERGE_CONFLICT, outcome: "refused" };
2254
2279
  };
2255
2280
  if (mergeInProgress(top)) {
2281
+ const merging = git(top, ["rev-parse", "--verify", "MERGE_HEAD"]);
2282
+ const expected = git(top, ["rev-parse", "--verify", `${target}^{commit}`]);
2283
+ if (merging === null || expected === null || merging !== expected) {
2284
+ log(
2285
+ `the pending merge targets ${merging ?? "an unreadable ref"}, not ${target}; finish that merge first`,
2286
+ );
2287
+ return { ...out, code: EXIT_REFUSED, outcome: "refused" };
2288
+ }
2256
2289
  out.before = git(top, ["rev-parse", "--verify", "--quiet", "ORIG_HEAD"]);
2257
- log(`a merge of ${UPSTREAM} is in progress — continuing it`);
2290
+ log(`a merge of ${target} is in progress — continuing it`);
2258
2291
  } else {
2259
2292
  if (o.current) return { ...out, outcome: "current" };
2260
2293
  if (full && hasLeftovers(top)) {
2261
- const message = `chore(${fid}): carry uncommitted work before merging ${DEV}`;
2294
+ const message = `chore(${fid}): carry uncommitted work before merging ${targetName}`;
2262
2295
  if (!addAllButCopied(top).ok || !quietGit(top, ["commit", "-q", "-m", message]).ok) {
2263
2296
  log("the uncommitted work could not be committed before the merge");
2264
2297
  return { ...out, code: EXIT_REFUSED, outcome: "refused" };
2265
2298
  }
2266
2299
  out.carried = git(top, ["rev-parse", "HEAD"]);
2267
- log(`committed the uncommitted work as ${out.carried} before merging ${UPSTREAM}`);
2300
+ log(`committed the uncommitted work as ${out.carried} before merging ${target}`);
2268
2301
  }
2269
2302
  out.before = git(top, ["rev-parse", "HEAD"]);
2270
- const message = `chore(${fid}): merge ${DEV}`;
2271
- const merge = quietGit(top, ["merge", "--no-edit", "-m", message, UPSTREAM]);
2303
+ const message = `chore(${fid}): merge ${targetName}`;
2304
+ const merge = quietGit(top, ["merge", "--no-edit", "-m", message, target]);
2272
2305
  if (!merge.ok && !mergeInProgress(top)) {
2273
2306
  // Not a conflict: git refused to start the merge at all.
2274
- log(`git merge ${UPSTREAM} failed: ${merge.stderr.trim()}`);
2307
+ log(`git merge ${target} failed: ${merge.stderr.trim()}`);
2275
2308
  return { ...out, code: EXIT_MERGE_CONFLICT, outcome: "refused" };
2276
2309
  }
2277
2310
  }
@@ -2296,12 +2329,12 @@ function mergeDev(top: string, o: MergeDevOptions, log: (m: string) => void): De
2296
2329
  return refuse("the merge could not be committed");
2297
2330
  }
2298
2331
  out.merged = true;
2299
- log(`merged ${UPSTREAM} into ${o.branch} as ${git(top, ["rev-parse", "HEAD"])}`);
2332
+ log(`merged ${target} into ${o.branch} as ${git(top, ["rev-parse", "HEAD"])}`);
2300
2333
  if (o.generate) {
2301
2334
  out.rebuilt = rebuildRegisters(
2302
2335
  top,
2303
2336
  out.resolved,
2304
- (files) => `chore(${fid}): rebuild ${files.join(" ")} after merging ${DEV}`,
2337
+ (files) => `chore(${fid}): rebuild ${files.join(" ")} after merging ${targetName}`,
2305
2338
  log,
2306
2339
  );
2307
2340
  out.generated = regenerate(top, o.branch, log, { fid });
@@ -2325,9 +2358,218 @@ function recordMerge(statusFile: string, before: string | null, after: string |
2325
2358
  });
2326
2359
  }
2327
2360
 
2361
+ function reconcileFeature(
2362
+ ctx: RunContext,
2363
+ top: string,
2364
+ branch: string,
2365
+ observed: { remoteHead: string | null },
2366
+ ): number {
2367
+ if (branch === "" || isSharedBranch(branch)) {
2368
+ throw new CommandError(EXIT.USAGE, "feature reconciliation needs a checked-out feature branch");
2369
+ }
2370
+ const remote = `${REMOTE}/${branch}`;
2371
+ const probeResult = spawnSync("git", ["ls-remote", "--exit-code", "--heads", REMOTE, branch], {
2372
+ cwd: top,
2373
+ encoding: "utf-8",
2374
+ env: gitEnv(),
2375
+ });
2376
+ const probe = { ok: probeResult.status === 0, stderr: probeResult.stderr ?? "" };
2377
+ if (!probe.ok && probeResult.status !== 2) {
2378
+ ctx.log(`cannot fetch ${remote}: ${probe.stderr}`);
2379
+ return EXIT_FETCH_FAILED;
2380
+ }
2381
+ if (probe.ok) {
2382
+ const fetched = fetchRemoteRef(top, remote);
2383
+ if (fetched === null || !fetched.ok) {
2384
+ ctx.log(`git fetch ${remote} failed: ${fetched?.stderr ?? "unknown remote ref"}`);
2385
+ return EXIT_FETCH_FAILED;
2386
+ }
2387
+ observed.remoteHead = git(top, [
2388
+ "rev-parse",
2389
+ "--verify",
2390
+ "--quiet",
2391
+ `refs/remotes/${remote}^{commit}`,
2392
+ ]);
2393
+ if (observed.remoteHead === null) {
2394
+ ctx.log(`cannot read the freshly fetched feature ${remote}`);
2395
+ return EXIT_FETCH_FAILED;
2396
+ }
2397
+ }
2398
+ assertShipEligible(top, "HEAD");
2399
+ if (probe.ok) assertShipEligible(top, remote);
2400
+ const headFlag = str(ctx.flags.head);
2401
+ if (
2402
+ headFlag !== undefined &&
2403
+ git(top, ["rev-parse", "--verify", "--quiet", `${headFlag}^{commit}`]) === null
2404
+ ) {
2405
+ throw new CommandError(EXIT.USAGE, `--head ${headFlag} does not name a commit`);
2406
+ }
2407
+ if (!mergeInProgress(top) && hasLeftovers(top)) {
2408
+ const statusFile = str(ctx.flags.file);
2409
+ const relative =
2410
+ statusFile && path.relative(top, path.resolve(ctx.cwd, statusFile)).split(path.sep).join("/");
2411
+ const scope = relative && /^docs\/plans\/(\d{6})\/logs\/([^/]+)\/status\.jsonl$/.exec(relative);
2412
+ const fid = str(ctx.flags.fid) || branch.replace(/^feat\//, "");
2413
+ if (!scope || scope[2] !== fid) {
2414
+ ctx.log("feature branch has uncommitted work — commit that work before reconciliation");
2415
+ return EXIT_REFUSED;
2416
+ }
2417
+ const outside = runGit(top, [
2418
+ "status",
2419
+ "--porcelain=v1",
2420
+ "-z",
2421
+ "--untracked-files=all",
2422
+ "--",
2423
+ ".",
2424
+ ...copyExcludes(top),
2425
+ ...bookPathspecs(scope[1]!, fid, "core").map((spec) => `:(exclude)${spec}`),
2426
+ ]);
2427
+ if (!outside.ok || outside.stdout !== "") {
2428
+ ctx.log(
2429
+ "feature branch has unrelated uncommitted work — commit that work before reconciliation",
2430
+ );
2431
+ return EXIT_REFUSED;
2432
+ }
2433
+ const carried = commitBookkeeping(
2434
+ {
2435
+ root: top,
2436
+ month: scope[1]!,
2437
+ fid,
2438
+ scope: "core",
2439
+ mode: "commit",
2440
+ message: `chore(${fid}): carry ship bookkeeping before reconciliation`,
2441
+ },
2442
+ ctx.log,
2443
+ );
2444
+ if (carried.outcome !== "committed") {
2445
+ ctx.log("the workflow bookkeeping could not be committed before reconciliation");
2446
+ return EXIT_REFUSED;
2447
+ }
2448
+ }
2449
+ const fid = str(ctx.flags.fid) || branch.replace(/^feat\//, "");
2450
+ const merge = (target: string, current: boolean) => {
2451
+ const m = mergeDev(
2452
+ top,
2453
+ { branch, target, policy: "full", fid, generate: true, current },
2454
+ ctx.log,
2455
+ );
2456
+ const after = git(top, ["rev-parse", "HEAD"]);
2457
+ const file = str(ctx.flags.file);
2458
+ if (m.merged && file !== undefined) recordMerge(path.resolve(ctx.cwd, file), m.before, after);
2459
+ if (m.code !== EXIT.OK) {
2460
+ ctx.emit({ branch, head: after, remoteHead: observed.remoteHead, ...m, target });
2461
+ }
2462
+ return m.code;
2463
+ };
2464
+ if (mergeInProgress(top)) {
2465
+ const pending = git(top, ["rev-parse", "--verify", "MERGE_HEAD"]);
2466
+ if (
2467
+ pending === null ||
2468
+ !probe.ok ||
2469
+ !runGit(top, ["merge-base", "--is-ancestor", pending, remote]).ok
2470
+ ) {
2471
+ ctx.log(
2472
+ "the pending merge is not the fetched feature merge — finish it before reconciliation",
2473
+ );
2474
+ return EXIT_REFUSED;
2475
+ }
2476
+ const code = merge(pending, false);
2477
+ if (code !== EXIT.OK) return code;
2478
+ }
2479
+ if (probe.ok) {
2480
+ const local = git(top, ["rev-parse", "HEAD"]);
2481
+ if (local === null) return EXIT_REFUSED;
2482
+ const ancestor = (a: string, b: string) =>
2483
+ spawnSync("git", ["merge-base", "--is-ancestor", a, b], { cwd: top, env: gitEnv() }).status;
2484
+ const behind = ancestor("HEAD", remote);
2485
+ const ahead = ancestor(remote, "HEAD");
2486
+ if ((behind !== 0 && behind !== 1) || (ahead !== 0 && ahead !== 1)) {
2487
+ ctx.log(`cannot compare the local feature with ${remote}`);
2488
+ return EXIT_REFUSED;
2489
+ }
2490
+ if (behind === 0 && ahead !== 0) {
2491
+ const ff = quietGit(top, ["merge", "--ff-only", remote]);
2492
+ if (!ff.ok) {
2493
+ ctx.log(`cannot fast-forward the feature: ${ff.stderr}`);
2494
+ return EXIT_REFUSED;
2495
+ }
2496
+ const file = str(ctx.flags.file);
2497
+ if (file !== undefined)
2498
+ recordMerge(path.resolve(ctx.cwd, file), local, git(top, ["rev-parse", "HEAD"]));
2499
+ } else if (ahead !== 0) {
2500
+ const code = merge(remote, false);
2501
+ if (code !== EXIT.OK) return code;
2502
+ }
2503
+ }
2504
+ assertShipEligible(top, "HEAD");
2505
+ const unpublished = !probe.ok || commitsAhead(top, remote) > 0;
2506
+ if (unpublished && SKIP_CI_TOKEN.test(git(top, ["log", "-1", "--format=%B"]) ?? "")) {
2507
+ const trigger = quietGit(top, [
2508
+ "commit",
2509
+ "--allow-empty",
2510
+ "-m",
2511
+ `chore(${fid}): validate reconciled feature`,
2512
+ ]);
2513
+ if (!trigger.ok) {
2514
+ ctx.log(`cannot create a CI-running feature head: ${trigger.stderr}`);
2515
+ return EXIT_REFUSED;
2516
+ }
2517
+ }
2518
+ return EXIT.OK;
2519
+ }
2520
+
2521
+ /** Merge-aware coverage identity; omit a dev merge only when Git proves its result automatic. */
2522
+ function featureCodeState(top: string, head: string, month: string, fid: string): string {
2523
+ const commits = runGit(top, ["rev-list", "--parents", `${UPSTREAM}..${head}`]);
2524
+ if (!commits.ok) throw new CommandError(EXIT_DIFF_FAILED, commits.stderr);
2525
+ const retained: string[] = [];
2526
+ for (const line of commits.stdout.split("\n").filter(Boolean)) {
2527
+ const [sha, first, second, ...other] = line.split(" ");
2528
+ if (!sha || !first)
2529
+ throw new CommandError(EXIT_DIFF_FAILED, "feature coverage needs readable commit parents");
2530
+ const bookkeeping = checkOnlyBookkeeping(top, { month, fid, from: first, to: sha });
2531
+ if (bookkeeping.kind === "ok") continue;
2532
+ if (bookkeeping.kind !== "outside")
2533
+ throw new CommandError(
2534
+ EXIT_DIFF_FAILED,
2535
+ `feature coverage classification: ${bookkeeping.kind}`,
2536
+ );
2537
+ if (second && other.length === 0) {
2538
+ const devParent = runGit(top, ["merge-base", "--is-ancestor", second, UPSTREAM]);
2539
+ if (devParent.ok) {
2540
+ const automatic = git(top, ["merge-tree", "--write-tree", first, second]);
2541
+ const tree = git(top, ["rev-parse", `${sha}^{tree}`]);
2542
+ if (automatic && tree && automatic.split("\n")[0] === tree) continue;
2543
+ }
2544
+ }
2545
+ retained.push(sha);
2546
+ }
2547
+ return `v1:${retained.sort().join(",")}`;
2548
+ }
2549
+
2328
2550
  function syncVerb(ctx: RunContext): number {
2329
2551
  const mergeDocs = ctx.flags.mergeDocs === true;
2330
2552
  const merge = ctx.flags.merge === true;
2553
+ const reconcile = ctx.flags.reconcileFeature === true;
2554
+ const featureState = ctx.flags.featureState === true;
2555
+ const month = str(ctx.flags.month);
2556
+ const coverageFid = str(ctx.flags.fid);
2557
+ if (
2558
+ featureState &&
2559
+ (mergeDocs || merge || reconcile || !month || !/^\d{6}$/.test(month) || !coverageFid)
2560
+ )
2561
+ throw new CommandError(
2562
+ EXIT.USAGE,
2563
+ "--feature-state needs --month=YYYYMM and --fid, separately from reconciliation or merging",
2564
+ );
2565
+ const targetFlag = str(ctx.flags.target);
2566
+ if (targetFlag !== undefined && (!merge || targetFlag === "" || targetFlag.startsWith("-")))
2567
+ throw new CommandError(EXIT.USAGE, "--target needs --merge and a commit ref");
2568
+ if (reconcile && (mergeDocs || merge))
2569
+ throw new CommandError(
2570
+ EXIT.USAGE,
2571
+ "give --reconcile-feature separately from --merge or --merge-docs",
2572
+ );
2331
2573
  const headFlag = str(ctx.flags.head);
2332
2574
  if ((mergeDocs || merge) && headFlag !== undefined) {
2333
2575
  throw new CommandError(
@@ -2341,15 +2583,31 @@ function syncVerb(ctx: RunContext): number {
2341
2583
  const sentinelPath = sentinel === undefined ? undefined : path.resolve(ctx.cwd, sentinel);
2342
2584
  if (merge && sentinelPath) fs.rmSync(sentinelPath, { force: true });
2343
2585
  const top = topLevel(ctx.cwd);
2586
+ const target =
2587
+ targetFlag === undefined
2588
+ ? undefined
2589
+ : git(top, ["rev-parse", "--verify", "--quiet", `${targetFlag}^{commit}`]);
2590
+ if (targetFlag !== undefined && !target)
2591
+ throw new CommandError(EXIT.USAGE, `--target ${targetFlag} does not name a commit`);
2344
2592
  const fetch = fetchDev(top);
2345
2593
  if (!fetch.ok) {
2346
2594
  ctx.log(`git fetch ${REMOTE} ${DEV} failed: ${fetch.stderr}`);
2347
2595
  return EXIT_FETCH_FAILED;
2348
2596
  }
2349
- const head = git(top, ["rev-parse", "--verify", "--quiet", `${headFlag ?? "HEAD"}^{commit}`]);
2597
+ const branch = currentBranch(top);
2598
+ const observed = { remoteHead: null as string | null };
2599
+ if (reconcile) {
2600
+ const code = reconcileFeature(ctx, top, branch, observed);
2601
+ if (code !== EXIT.OK) return code;
2602
+ }
2603
+ const head = git(top, [
2604
+ "rev-parse",
2605
+ "--verify",
2606
+ "--quiet",
2607
+ `${reconcile ? "HEAD" : (headFlag ?? "HEAD")}^{commit}`,
2608
+ ]);
2350
2609
  if (!head)
2351
2610
  throw new CommandError(EXIT.USAGE, `--head ${headFlag ?? "HEAD"} does not name a commit`);
2352
- const branch = currentBranch(top);
2353
2611
 
2354
2612
  const ancestor = spawnSync("git", ["merge-base", "--is-ancestor", UPSTREAM, head], {
2355
2613
  cwd: top,
@@ -2367,6 +2625,10 @@ function syncVerb(ctx: RunContext): number {
2367
2625
  const out = {
2368
2626
  branch: branch === "" ? null : branch,
2369
2627
  head,
2628
+ ...(reconcile ? { remoteHead: observed.remoteHead, reconciledHead: head } : {}),
2629
+ ...(featureState
2630
+ ? { featureCodeState: featureCodeState(top, head, month!, coverageFid!) }
2631
+ : {}),
2370
2632
  basePath: ancestor.status === 0 ? "A" : "B",
2371
2633
  behind,
2372
2634
  docsBehind,
@@ -2405,7 +2667,16 @@ function syncVerb(ctx: RunContext): number {
2405
2667
  const fid = str(ctx.flags.fid) || branch.replace(/^feat\//, "");
2406
2668
  const m = mergeDev(
2407
2669
  top,
2408
- { branch, policy: "full", fid, generate: true, current: out.basePath === "A" },
2670
+ {
2671
+ branch,
2672
+ policy: "full",
2673
+ fid,
2674
+ generate: true,
2675
+ ...(target ? { target } : {}),
2676
+ current: target
2677
+ ? runGit(top, ["merge-base", "--is-ancestor", target, "HEAD"]).ok
2678
+ : out.basePath === "A",
2679
+ },
2409
2680
  ctx.log,
2410
2681
  );
2411
2682
  const refused = m.outcome === "refused";
@@ -2416,6 +2687,7 @@ function syncVerb(ctx: RunContext): number {
2416
2687
  const newHead = git(top, ["rev-parse", "HEAD"]) ?? head;
2417
2688
  ctx.emit({
2418
2689
  ...out,
2690
+ ...(target ? { target } : {}),
2419
2691
  head: newHead,
2420
2692
  merged: m.merged,
2421
2693
  resolved: m.resolved,
@@ -2437,7 +2709,7 @@ function syncVerb(ctx: RunContext): number {
2437
2709
  }
2438
2710
 
2439
2711
  /**
2440
- * Ship Step 13: after the merge, bring local dev up to origin/dev by a pure
2712
+ * Ship Step 11: after the merge, bring local dev up to origin/dev by a pure
2441
2713
  * fast-forward without checking anything out, then a frozen install when the
2442
2714
  * main checkout is on dev and moved. Never pushes.
2443
2715
  */
@@ -2553,13 +2825,16 @@ function restoreBranchRows(dir: string, branch: string): void {
2553
2825
  for (const p of changed) {
2554
2826
  const before = new Set(revLines(dir, base, p));
2555
2827
  const file = path.join(dir, p);
2556
- const text = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
2557
- const have = new Set(text.split("\n").map((l) => l.trim()));
2558
- const missing = revLines(dir, branch, p).filter((l) => !before.has(l) && !have.has(l));
2559
- if (missing.length === 0) continue;
2560
- const sep = text !== "" && !text.endsWith("\n") ? "\n" : "";
2561
- fs.mkdirSync(path.dirname(file), { recursive: true });
2562
- fs.appendFileSync(file, `${sep}${missing.join("\n")}\n`);
2828
+ const wrote = withTargetLock(file, () => {
2829
+ const text = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
2830
+ const have = new Set(text.split("\n").map((l) => l.trim()));
2831
+ const missing = revLines(dir, branch, p).filter((l) => !before.has(l) && !have.has(l));
2832
+ if (missing.length === 0) return false;
2833
+ const sep = text !== "" && !text.endsWith("\n") ? "\n" : "";
2834
+ fs.appendFileSync(file, `${sep}${missing.join("\n")}\n`);
2835
+ return true;
2836
+ });
2837
+ if (!wrote) continue;
2563
2838
  runGit(dir, ["add", "--", p]);
2564
2839
  }
2565
2840
  }
@@ -2883,32 +3158,6 @@ function fastForwardDev(
2883
3158
  return "fast-forwarded";
2884
3159
  }
2885
3160
 
2886
- /**
2887
- * What `branch` changed that origin/dev does not hold, compared file by file
2888
- * against the branch's fork point: a file whose dev copy differs from the
2889
- * branch's, or (a `.jsonl` ledger, union-merged) a line the branch added that
2890
- * dev's copy lacks. `docs/roadmap.md` is re-rendered on every close, so it is
2891
- * not compared. The branch and its worktree are deleted only when this is empty.
2892
- */
2893
- function notOnDev(root: string, branch: string): string[] {
2894
- const base = git(root, ["merge-base", UPSTREAM, branch]);
2895
- if (base === null) return [`${branch}: no common history with ${UPSTREAM}`];
2896
- const lines = (rev: string, p: string) => revLines(root, rev, p);
2897
- return (git(root, ["diff", "--name-only", "--no-renames", "--diff-filter=d", base, branch]) ?? "")
2898
- .split("\n")
2899
- .filter((p) => p !== "" && p !== "docs/roadmap.md")
2900
- .filter((p) => {
2901
- if (!p.endsWith(".jsonl"))
2902
- return (
2903
- git(root, ["rev-parse", `${branch}:${p}`]) !==
2904
- git(root, ["rev-parse", "-q", "--verify", `${UPSTREAM}:${p}`])
2905
- );
2906
- const before = new Set(lines(base, p));
2907
- const onDev = new Set(lines(UPSTREAM, p));
2908
- return lines(branch, p).some((l) => !before.has(l) && !onDev.has(l));
2909
- });
2910
- }
2911
-
2912
3161
  /**
2913
3162
  * Those of `paths` whose content at `spec(p)` is already local `dev`'s: work the
2914
3163
  * branch carries because `dev` is unpushed, not work a run in this branch made.
@@ -3227,6 +3476,17 @@ export const branchesCommand: CommandSpec = {
3227
3476
  summary: `Fetch ${UPSTREAM}; report whether it is an ancestor of HEAD (Path A/B) and how far docs/ and the ledgers are behind; optionally merge it in.`,
3228
3477
  use: "workflow",
3229
3478
  flags: [
3479
+ {
3480
+ name: "feature-state",
3481
+ type: "boolean",
3482
+ help: "report merge-aware feature coverage, excluding bookkeeping and proven automatic dev-only merges; needs --month and --fid",
3483
+ },
3484
+ { name: "month", type: "string", help: "--feature-state: bookkeeping month YYYYMM" },
3485
+ {
3486
+ name: "reconcile-feature",
3487
+ type: "boolean",
3488
+ help: "ship: fetch and reconcile the feature branch before classifying its base; preserve divergent work through a merge and ensure unpublished work has a CI-running head",
3489
+ },
3230
3490
  {
3231
3491
  name: "head",
3232
3492
  type: "string",
@@ -3237,6 +3497,11 @@ export const branchesCommand: CommandSpec = {
3237
3497
  type: "boolean",
3238
3498
  help: `ship Step 4: merge ${UPSTREAM} into the checked-out feature branch — the run's uncommitted work is committed first, ledger conflicts union, a lockfile regenerates from ${DEV}'s copy, a generated register takes ${DEV}'s copy and is rebuilt after the merge, a doc embedding the register's generated block takes ${DEV}'s block and merges the rest, the install record (.bkit/version) merges entry by entry with ${DEV}'s value where both changed, any other conflict stays in the tree with the merge in progress for a hand resolution (exit 24; run again after git add), then a declared bkit:generate runs and its output is committed; never a rebase or force-push, never on ${DEV} / main`,
3239
3499
  },
3500
+ {
3501
+ name: "target",
3502
+ type: "string",
3503
+ help: "--merge: exact recorded merge target (default origin/dev); continuation refuses a different MERGE_HEAD",
3504
+ },
3240
3505
  {
3241
3506
  name: "merge-docs",
3242
3507
  type: "boolean",
@@ -3261,6 +3526,13 @@ export const branchesCommand: CommandSpec = {
3261
3526
  output: {
3262
3527
  branch: "current branch (null when detached)",
3263
3528
  head: "commit compared (after a merge: the new HEAD)",
3529
+ remoteHead:
3530
+ "--reconcile-feature: the freshly observed remote feature commit, or null when absent",
3531
+ reconciledHead:
3532
+ "--reconcile-feature: the resulting local feature commit used for base classification",
3533
+ featureCodeState:
3534
+ "--feature-state: versioned identity of feature commits and semantic merge results",
3535
+ target: "--merge --target: the resolved commit being merged or continued",
3264
3536
  basePath: `A when ${UPSTREAM} is an ancestor of head (nothing to integrate), else B`,
3265
3537
  behind: `commits on ${UPSTREAM} not in head`,
3266
3538
  docsBehind: `of those, commits touching docs/ or a ledger path (LEDGERS)`,
@@ -3279,6 +3551,8 @@ export const branchesCommand: CommandSpec = {
3279
3551
  sentinel: "--merge: the sentinel written on refusal (null otherwise)",
3280
3552
  },
3281
3553
  exitCodes: {
3554
+ [EXIT_DIFF_FAILED]:
3555
+ "--feature-state: commit ancestry or bookkeeping classification could not be read",
3282
3556
  [EXIT_REFUSED]: "--merge: the uncommitted work could not be committed before the merge",
3283
3557
  [EXIT_DETACHED]: "--merge / --merge-docs with no branch checked out",
3284
3558
  [EXIT_FETCH_FAILED]: `git fetch ${REMOTE} ${DEV} failed`,
@@ -3326,7 +3600,7 @@ export const branchesCommand: CommandSpec = {
3326
3600
  },
3327
3601
  push: {
3328
3602
  summary:
3329
- "Push the current branch with exactly one git push: plain for dev/main, --force-with-lease otherwise; 81 tests lock held.",
3603
+ "Push the current branch with exactly one git push: plain for dev/main, --force-with-lease otherwise; when the pre-push hook's lock status file says so, 81 tests lock held, 4 tests lock refused the run or stopped it at the hold limit.",
3330
3604
  use: "workflow",
3331
3605
  flags: [
3332
3606
  {
@@ -3433,8 +3707,7 @@ export const branchesCommand: CommandSpec = {
3433
3707
  {
3434
3708
  name: "base",
3435
3709
  type: "string",
3436
- required: true,
3437
- help: "diff <base>...HEAD; an origin/<branch> base is fetched first",
3710
+ help: "diff <base>...HEAD; an origin/<branch> base is fetched first (default: the feature base, where the branch's own work starts)",
3438
3711
  },
3439
3712
  {
3440
3713
  name: "paths",