@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
@@ -6,13 +6,20 @@
6
6
  // dev and push again, with backoff. Used by the design / plan close, the
7
7
  // build / debug roadmap mirror, ship's close and FAILED record, and the
8
8
  // own-commit push of a debug run in place on dev, which replays the run's
9
- // commits. The throwaway runs no git hooks: it lands bookkeeping (docs, logs,
10
- // ledgers, `[skip ci]`) or the commits a debug run on dev made.
9
+ // commits. The throwaway runs its declared gate explicitly before pushing.
11
10
 
11
+ import { spawnSync } from "node:child_process";
12
12
  import * as fs from "node:fs";
13
13
  import * as path from "node:path";
14
14
  import { CommandError, DEV, EXIT, git, runGit } from "./lib.js";
15
15
  import { TIMEOUTS } from "../shared/timeouts.js";
16
+ import { gitEnv } from "../ledgers/telemetry.js";
17
+ import { readBkitConfig } from "../shared/settings.js";
18
+ import { readPackageJson } from "../shared/package-json.js";
19
+ import { installCommand } from "../shared/package-manager.js";
20
+ import { minPushPathspecs } from "./ci/ci.js";
21
+ import { requiredPushGate, runPushGate } from "./ci/push-gate.js";
22
+ import { changedOutside } from "./workflow/ledgers.js";
16
23
 
17
24
  const REMOTE = "origin";
18
25
  const UPSTREAM = `${REMOTE}/${DEV}`;
@@ -25,6 +32,23 @@ const MOVED_DURING =
25
32
  /** The server turned the push away: branch protection, a ruleset, an HTTP 403. */
26
33
  const REFUSED = /\[remote rejected\]|returned error: 403|\bGH0\d\d\b/;
27
34
 
35
+ /**
36
+ * The refspec every dev fetch uses. A bare `git fetch origin dev` writes only
37
+ * FETCH_HEAD when the clone's fetch refspec does not cover `dev` (a single-branch
38
+ * clone), leaving `origin/dev` stale; a landing built on it is rejected on every push.
39
+ */
40
+ export const DEV_REFSPEC = `+refs/heads/${DEV}:refs/remotes/${UPSTREAM}`;
41
+
42
+ /** Fetch origin's dev into `origin/dev`, whatever the clone's fetch refspec covers. */
43
+ export const fetchDev = (cwd: string) => runGit(cwd, ["fetch", REMOTE, DEV_REFSPEC]);
44
+
45
+ /**
46
+ * A dev fetch that failed only because another git process in this clone (a
47
+ * second landing's fetch or push) updated or held `origin/dev` while it ran.
48
+ */
49
+ const DEV_REF_RACE = new RegExp(`cannot lock ref 'refs/remotes/${UPSTREAM}'`);
50
+ export const devRefRace = (stderr: string) => DEV_REF_RACE.test(stderr);
51
+
28
52
  /** A dev push rejected only because dev moved: rebuild on the new dev, push again. */
29
53
  export const devMoved = (stderr: string) => MOVED_BEFORE.test(stderr) || MOVED_DURING.test(stderr);
30
54
 
@@ -106,12 +130,94 @@ export type DevPush =
106
130
  | { kind: "fetch-failed"; stderr: string }
107
131
  | { kind: "setup-failed"; stderr: string };
108
132
 
133
+ /** Copy ignored inputs without replacing anything in the built checkout. */
134
+ function prepareLandInputs(root: string, dir: string, log: (line: string) => void): void {
135
+ const config = readBkitConfig(dir);
136
+ const sourceRoot = fs.realpathSync(root);
137
+ for (const entry of config.worktreeCopy) {
138
+ const relative = path.normalize(entry);
139
+ if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) {
140
+ log(`landing input is outside the checkout — skipped: ${entry}`);
141
+ continue;
142
+ }
143
+ const source = path.join(root, relative);
144
+ const destination = path.join(dir, relative);
145
+ const tracked = runGit(dir, ["ls-files", "--", relative]);
146
+ if (!tracked.ok) throw new CommandError(EXIT.NO, `cannot inspect landing input: ${entry}`);
147
+ if (tracked.stdout || fs.existsSync(destination)) continue;
148
+ if (!runGit(dir, ["check-ignore", "-q", "--", relative]).ok) continue;
149
+ if (!fs.existsSync(source)) {
150
+ log(`landing input absent in the main checkout: ${entry}`);
151
+ continue;
152
+ }
153
+ fs.mkdirSync(path.dirname(destination), { recursive: true });
154
+ fs.cpSync(source, destination, {
155
+ recursive: true,
156
+ dereference: true,
157
+ filter: (file) => {
158
+ const actual = fs.realpathSync(file);
159
+ if (actual !== sourceRoot && !actual.startsWith(`${sourceRoot}${path.sep}`)) {
160
+ throw new CommandError(EXIT.NO, `landing input resolves outside the checkout: ${entry}`);
161
+ }
162
+ return true;
163
+ },
164
+ });
165
+ }
166
+ if (config.worktreeInstall) {
167
+ const [command, ...args] = installCommand({ frozen: true });
168
+ if (!fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) args.push("--ignore-workspace");
169
+ log("installing frozen dependencies in the throwaway dev checkout");
170
+ const result = spawnSync(command!, args, {
171
+ cwd: dir,
172
+ env: gitEnv(),
173
+ encoding: "utf8",
174
+ maxBuffer: 1 << 26,
175
+ });
176
+ if (result.error || result.status !== 0) {
177
+ for (const line of `${result.stdout ?? ""}${result.stderr ?? ""}`
178
+ .trim()
179
+ .split("\n")
180
+ .slice(-20))
181
+ log(line);
182
+ throw new CommandError(EXIT.NO, "landing dependency install failed — nothing pushed");
183
+ }
184
+ }
185
+ }
186
+
187
+ /** Validate the committed landing against the freshly fetched base before sending it. */
188
+ function checkLanding(root: string, dir: string, base: string, log: (line: string) => void): void {
189
+ const head = git(dir, ["rev-parse", "HEAD"]);
190
+ const unchanged = () =>
191
+ head !== null &&
192
+ git(dir, ["rev-parse", "HEAD"]) === head &&
193
+ git(dir, ["status", "--porcelain", "--untracked-files=all", "--ignore-submodules=none"]) === "";
194
+ if (!unchanged())
195
+ throw new CommandError(EXIT.NO, "landing checkout is not clean — nothing pushed");
196
+ if (!readPackageJson(dir).ok)
197
+ throw new CommandError(EXIT.NO, "landing package.json is unreadable — nothing pushed");
198
+ const diff = changedOutside(dir, base, head!, minPushPathspecs(readBkitConfig(dir)));
199
+ if (!diff.ok) throw new CommandError(EXIT.NO, `cannot classify landing: ${diff.stderr}`);
200
+ const gate = diff.outside.length === 0 ? "bkit:gate:min" : requiredPushGate(dir);
201
+ if (!gate) throw new CommandError(EXIT.NO, "landing has no declared full gate — nothing pushed");
202
+ prepareLandInputs(root, dir, log);
203
+ if (!unchanged())
204
+ throw new CommandError(EXIT.NO, "landing preparation changed the checkout — nothing pushed");
205
+ const status = runPushGate(dir, gate, log);
206
+ if (status !== 0)
207
+ throw new CommandError(EXIT.NO, `landing ${gate} failed (exit ${status}) — nothing pushed`);
208
+ if (!unchanged())
209
+ throw new CommandError(EXIT.NO, "landing gate changed the checkout — nothing pushed");
210
+ }
211
+
109
212
  /**
110
213
  * Land on dev what `build` makes: per attempt, fetch dev, add `dir` detached at
111
214
  * origin/dev, let `build` make one or more commits there (a bookkeeping commit,
112
- * or a replay of a run's commits), push `HEAD:dev` — git hooks off. `build`
215
+ * or a replay of a run's commits), validate the checkout, then push `HEAD:dev`.
216
+ * Git hooks are off; the minimum or full local gate runs explicitly. `build`
113
217
  * throwing stops the landing with that throw. A server refusal runs `refused` on
114
- * the built commits first, when given. `dir` is removed on every path.
218
+ * the built commits first, when given. dev moving, or another landing in this
219
+ * clone updating `origin/dev` during the fetch, retries with backoff within
220
+ * LAND_ATTEMPTS. `dir` is removed on every path.
115
221
  */
116
222
  export async function pushToDev(o: {
117
223
  root: string;
@@ -121,18 +227,24 @@ export async function pushToDev(o: {
121
227
  log: (line: string) => void;
122
228
  }): Promise<DevPush> {
123
229
  o.log(
124
- "git hooks skipped in the throwaway dev checkout — it lands bookkeeping, or the commits a debug run on dev made",
230
+ "git hooks skipped in the throwaway dev checkout — its declared minimum or full gate runs explicitly",
125
231
  );
126
232
  for (let attempt = 1; ; attempt++) {
127
233
  let wait = 0;
128
234
  dropLandTree(o.root, o.dir);
129
235
  try {
130
- const outcome = await withoutHooks(async (): Promise<DevPush | null> => {
131
- const fetched = runGit(o.root, ["fetch", REMOTE, DEV]);
132
- if (!fetched.ok) return { kind: "fetch-failed", stderr: fetched.stderr };
236
+ const outcome = await withoutHooks(async (): Promise<DevPush | "moved" | "raced"> => {
237
+ const fetched = fetchDev(o.root);
238
+ if (!fetched.ok) {
239
+ if (devRefRace(fetched.stderr) && attempt < TIMEOUTS.LAND_ATTEMPTS) return "raced";
240
+ return { kind: "fetch-failed", stderr: fetched.stderr };
241
+ }
133
242
  const added = runGit(o.root, ["worktree", "add", "--detach", o.dir, UPSTREAM]);
134
243
  if (!added.ok) return { kind: "setup-failed", stderr: added.stderr };
244
+ const base = git(o.dir, ["rev-parse", "HEAD"]);
245
+ if (!base) throw new CommandError(EXIT.NO, "cannot read the fetched landing base");
135
246
  o.build(o.dir, attempt);
247
+ checkLanding(o.root, o.dir, base, o.log);
136
248
  const pushed = runGit(o.dir, ["push", REMOTE, `HEAD:${DEV}`]);
137
249
  if (pushed.ok) {
138
250
  return {
@@ -146,13 +258,16 @@ export async function pushToDev(o: {
146
258
  return { kind: "refused", stderr: pushed.stderr };
147
259
  }
148
260
  if (!devMoved(pushed.stderr)) return { kind: "push-failed", stderr: pushed.stderr };
149
- return null;
261
+ return "moved";
150
262
  });
151
- if (outcome !== null) return outcome;
263
+ if (typeof outcome !== "string") return outcome;
152
264
  if (attempt >= TIMEOUTS.LAND_ATTEMPTS) return { kind: "exhausted", attempts: attempt };
153
265
  wait = landBackoffMs(attempt);
266
+ const s = (wait / 1000).toFixed(1);
154
267
  o.log(
155
- `dev moved before push ${attempt} of ${TIMEOUTS.LAND_ATTEMPTS} — rebuilding on the new dev in ${(wait / 1000).toFixed(1)}s`,
268
+ outcome === "moved"
269
+ ? `dev moved before push ${attempt} of ${TIMEOUTS.LAND_ATTEMPTS} — rebuilding on the new dev in ${s}s`
270
+ : `another git process updated ${UPSTREAM} during the fetch of try ${attempt} of ${TIMEOUTS.LAND_ATTEMPTS} — fetching again in ${s}s`,
156
271
  );
157
272
  } finally {
158
273
  dropLandTree(o.root, o.dir);
@@ -13,7 +13,19 @@ import * as fs from "node:fs";
13
13
  import * as os from "node:os";
14
14
  import * as path from "node:path";
15
15
 
16
- import { gitEnv } from "../ledgers/telemetry.js";
16
+ import {
17
+ appendFrictionRow,
18
+ appendJournalRow,
19
+ engineCallRow,
20
+ frictionRow,
21
+ journalEnabled,
22
+ launchedByGit,
23
+ rebasePaused,
24
+ shouldRecordFriction,
25
+ } from "../ledgers/journal.js";
26
+ import { fold, type StatusEvent } from "../ledgers/status.js";
27
+ import { gitEnv, resolveGitSha } from "../ledgers/telemetry.js";
28
+ import { parseJson } from "../shared/json.js";
17
29
  import { renderText } from "../shared/text.js";
18
30
 
19
31
  // ---------------------------------------------------------------------------
@@ -80,6 +92,51 @@ export interface FlagSpec {
80
92
 
81
93
  export type FlagValue = string | boolean | string[] | undefined;
82
94
 
95
+ /** Parse a whole-number flag, using its fallback only when absent. */
96
+ export const wholeNumber = (v: FlagValue, flag: string, fallback: number, min = 0): number => {
97
+ if (v === undefined) return fallback;
98
+ const s = String(v);
99
+ if (!/^[0-9]+$/.test(s) || Number(s) < min) {
100
+ throw new CommandError(EXIT.USAGE, `--${flag} takes a whole number >= ${min} (got "${s}")`);
101
+ }
102
+ return Number(s);
103
+ };
104
+
105
+ /** The holder named by this run when its tests-lock wait gave up. */
106
+ export function testsLockHolder(log: string, who: string): string | null {
107
+ const prefix = `[machine-lock] ❌ ${who} gave up after `;
108
+ for (const line of log.split(/\r?\n/)) {
109
+ if (!line.startsWith(prefix)) continue;
110
+ const holder = /^\d+s waiting for tests, in use by (.+)$/.exec(line.slice(prefix.length));
111
+ if (holder) return holder[1]!;
112
+ }
113
+ return null;
114
+ }
115
+
116
+ /** Classify only a tests-lock outcome, leaving gate and nested-lock failures intact. */
117
+ export function classifyLockExit({
118
+ exitCode,
119
+ log,
120
+ who,
121
+ }: {
122
+ exitCode: number;
123
+ log: string;
124
+ who: string;
125
+ }): "gate" | "lock-wait" | "could-not-run" {
126
+ const lines = log.split(/\r?\n/);
127
+ if (exitCode === 75 && testsLockHolder(log, who) !== null) return "lock-wait";
128
+ if (
129
+ exitCode === 73 &&
130
+ lines.some((line) =>
131
+ /^\[machine-lock\] ❌ (?:could not take the lock for tests:|cannot take tests while holding )/.test(
132
+ line,
133
+ ),
134
+ )
135
+ )
136
+ return "could-not-run";
137
+ return "gate";
138
+ }
139
+
83
140
  export interface RunContext {
84
141
  /** Parsed flags, keyed by camelCase name. */
85
142
  flags: Record<string, FlagValue>;
@@ -102,8 +159,16 @@ export interface RunContext {
102
159
  export type TextOmit =
103
160
  string | { key: string; when: (value: unknown, output: Record<string, unknown>) => boolean };
104
161
 
162
+ /**
163
+ * Who runs a verb. `by-hand`: safe and useful outside a workflow run (reads, or a job of
164
+ * its own). `workflow`: a workflow step only (writes run state, takes locks, commits,
165
+ * pushes or posts). `.bkit/cli.md` shows it per verb.
166
+ */
167
+ export type VerbUse = "by-hand" | "workflow";
168
+
105
169
  export interface VerbSpec {
106
170
  summary: string;
171
+ use: VerbUse;
107
172
  flags: FlagSpec[];
108
173
  /** Output key -> meaning. Keys are camelCase, matching `status.jsonl`. */
109
174
  output: Record<string, string>;
@@ -306,6 +371,187 @@ function omitNote(spec: VerbSpec, key: string): string {
306
371
  return typeof o === "string" ? " (--json only)" : " (text: only when it matters)";
307
372
  }
308
373
 
374
+ // ---------------------------------------------------------------------------
375
+ // Journal seam — what `runCommand` records while a workflow run is active
376
+ // ---------------------------------------------------------------------------
377
+
378
+ export interface JournalInput {
379
+ noun: string;
380
+ verb: string;
381
+ /** The argv after the verb; the journal keeps flag names only. */
382
+ argv: string[];
383
+ flags: Record<string, FlagValue>;
384
+ cwd: string;
385
+ }
386
+
387
+ /** The two writes the seam makes; injectable so a test can make either throw. */
388
+ export interface Journal {
389
+ /** One `engine-call` row at dispatch entry. */
390
+ call(input: JournalInput): void;
391
+ /** One `tool-failure` friction row; `code` is null when the command threw. */
392
+ failure(input: JournalInput & { code: number | null }): void;
393
+ }
394
+
395
+ /** The active run a call is attributed to: its `status.jsonl` and the root its other books live under. */
396
+ export interface ActiveRun {
397
+ workflow: string;
398
+ file: string;
399
+ bookRoot: string;
400
+ }
401
+
402
+ /** Row types `fold` reads; the other rows a `status.jsonl` carries (engine-call, ...) stay out of it. */
403
+ const FOLD_TYPES = new Set([
404
+ "workflow-started",
405
+ "step-done",
406
+ "workflow-meta",
407
+ "workflow-done",
408
+ "workflow-failed",
409
+ ]);
410
+
411
+ /** Most `status.jsonl` files `resolveActiveRun` reads when it walks a checkout. */
412
+ const ACTIVE_RUN_SCAN_CAP = 500;
413
+
414
+ /** The workflow of the last run in `file` when that run is IN_PROGRESS, else undefined. */
415
+ function inProgressWorkflow(file: string): string | undefined {
416
+ if (!fs.existsSync(file)) return undefined;
417
+ const events: StatusEvent[] = [];
418
+ for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
419
+ if (line.trim() === "") continue;
420
+ const parsed = parseJson(line);
421
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") continue;
422
+ const type = (parsed.value as { type?: unknown }).type;
423
+ if (typeof type === "string" && FOLD_TYPES.has(type)) events.push(parsed.value as StatusEvent);
424
+ }
425
+ const last = fold(events).at(-1);
426
+ return last?.status === "IN_PROGRESS" ? last.workflow : undefined;
427
+ }
428
+
429
+ /** The directories under `dir`, by name; none when `dir` is missing. */
430
+ function subdirs(dir: string): string[] {
431
+ if (!fs.existsSync(dir)) return [];
432
+ return fs
433
+ .readdirSync(dir, { withFileTypes: true })
434
+ .filter((e) => e.isDirectory())
435
+ .map((e) => e.name);
436
+ }
437
+
438
+ /**
439
+ * The run a command call belongs to, or undefined. In order: the command's own
440
+ * `--file`; `--fid` (+ `--month`, default this UTC month) through `statusLocation`;
441
+ * the single IN_PROGRESS run among the `docs/plans/<month>/logs/<fid>/status.jsonl`
442
+ * files under the cwd's git toplevel (capped), only `--fid`'s own when it is set, so a
443
+ * run from an earlier month is found and another feature's run never is. From the main checkout a feature
444
+ * worktree's run is not found, so an out-of-worktree call is skipped, never
445
+ * attributed to another run. Reads with this module's own `node:fs` and `parseJson`
446
+ * and folds with `ledgers/status.ts`, so it never imports a `commands/**` module.
447
+ */
448
+ export function resolveActiveRun(opts: {
449
+ cwd: string;
450
+ file?: string;
451
+ fid?: string;
452
+ month?: string;
453
+ workflow?: string;
454
+ }): ActiveRun | undefined {
455
+ // A `--file` that is a run's `status.jsonl` names that run; any other file (a plan or
456
+ // design doc) says nothing about the run and falls through to `--fid` and the scan.
457
+ if (opts.file !== undefined && path.basename(opts.file) === "status.jsonl") {
458
+ const file = path.resolve(opts.cwd, opts.file);
459
+ const workflow = inProgressWorkflow(file);
460
+ const logs = path.dirname(path.dirname(file));
461
+ if (
462
+ workflow === undefined ||
463
+ path.basename(logs) !== "logs" ||
464
+ path.basename(path.dirname(path.dirname(logs))) !== "plans"
465
+ ) {
466
+ return undefined;
467
+ }
468
+ return {
469
+ workflow,
470
+ file,
471
+ bookRoot: path.dirname(path.dirname(path.dirname(path.dirname(logs)))),
472
+ };
473
+ }
474
+ if (opts.fid !== undefined) {
475
+ try {
476
+ const loc = statusLocation({
477
+ cwd: opts.cwd,
478
+ workflow: opts.workflow ?? "build",
479
+ fid: opts.fid,
480
+ month: opts.month ?? utcMonth(),
481
+ });
482
+ const workflow = inProgressWorkflow(loc.path);
483
+ if (workflow !== undefined) return { workflow, file: loc.path, bookRoot: loc.bookRoot };
484
+ } catch (err) {
485
+ if (!(err instanceof CommandError)) throw err;
486
+ }
487
+ }
488
+ const top = git(opts.cwd, ["rev-parse", "--show-toplevel"]);
489
+ if (top === null) return undefined;
490
+ const found: ActiveRun[] = [];
491
+ let read = 0;
492
+ for (const month of subdirs(path.join(top, "docs", "plans"))) {
493
+ for (const fid of subdirs(path.join(top, "docs", "plans", month, "logs"))) {
494
+ if (++read > ACTIVE_RUN_SCAN_CAP) return undefined;
495
+ if (opts.fid !== undefined && fid !== opts.fid) continue;
496
+ const file = path.join(top, statusRelPath(month, fid));
497
+ const workflow = inProgressWorkflow(file);
498
+ if (workflow !== undefined) found.push({ workflow, file, bookRoot: top });
499
+ }
500
+ }
501
+ return found.length === 1 ? found[0] : undefined;
502
+ }
503
+
504
+ /** The journal `runCommand` uses unless a caller injects one: writes into the active run's own books. */
505
+ function engineJournal(): Journal {
506
+ let resolved = false;
507
+ let run: ActiveRun | undefined;
508
+ const active = (i: JournalInput): ActiveRun | undefined => {
509
+ if (!resolved) {
510
+ resolved = true;
511
+ const text = (v: FlagValue) => (typeof v === "string" ? v : undefined);
512
+ run = resolveActiveRun({
513
+ cwd: i.cwd,
514
+ file: text(i.flags["file"]),
515
+ fid: text(i.flags["fid"]),
516
+ month: text(i.flags["month"]),
517
+ workflow: text(i.flags["workflow"]),
518
+ });
519
+ }
520
+ return run;
521
+ };
522
+ return {
523
+ call(i) {
524
+ // A call git launched (a hook's `bkit disk prune`) writes no row to the tracked status file.
525
+ if (!journalEnabled() || launchedByGit()) return;
526
+ const r = active(i);
527
+ // A paused rebase refuses `--continue` while the tracked status file has an unstaged row.
528
+ if (r === undefined || rebasePaused(path.dirname(r.file))) return;
529
+ const wrote = appendJournalRow(
530
+ r.file,
531
+ engineCallRow({ workflow: r.workflow, noun: i.noun, verb: i.verb, flags: i.argv }),
532
+ );
533
+ if (!wrote.ok) throw new Error(wrote.error);
534
+ },
535
+ failure(i) {
536
+ if (!journalEnabled()) return;
537
+ const r = active(i);
538
+ if (r === undefined) return;
539
+ const step = i.flags["step"];
540
+ const row = frictionRow({
541
+ workflow: r.workflow,
542
+ step: typeof step === "string" ? step : undefined,
543
+ noun: i.noun,
544
+ verb: i.verb,
545
+ code: i.code,
546
+ bookRoot: r.bookRoot,
547
+ parentSha: resolveGitSha("HEAD", r.bookRoot),
548
+ });
549
+ const wrote = appendFrictionRow(r.bookRoot, row);
550
+ if (!wrote.ok) throw new Error(wrote.error);
551
+ },
552
+ };
553
+ }
554
+
309
555
  /**
310
556
  * Run `argv` (without the leading `bkit`) if it names a registered command.
311
557
  * Returns the exit code, or null when `argv` is not a command, so the caller falls
@@ -317,7 +563,7 @@ function omitNote(spec: VerbSpec, key: string): string {
317
563
  export async function runCommand(
318
564
  argv: string[],
319
565
  commands: readonly CommandSpec[],
320
- options: { classicVerbs: ReadonlySet<string>; cwd?: string; io?: Io },
566
+ options: { classicVerbs: ReadonlySet<string>; cwd?: string; io?: Io; journal?: Journal },
321
567
  ): Promise<number | null> {
322
568
  const io = options.io ?? processIo;
323
569
  const cmd = commands.find((c) => c.noun === argv[0]);
@@ -354,6 +600,25 @@ export async function runCommand(
354
600
  io.stdout(ctx.json ? `${JSON.stringify(output)}\n` : renderText(textOutput(spec, output)));
355
601
  },
356
602
  };
603
+ // The journal never changes the verb's exit code, output or throw: each write is
604
+ // swallowed, and the first failure logs one line.
605
+ const journal = options.journal ?? engineJournal();
606
+ let journalWarned = false;
607
+ const guarded = (write: () => void) => {
608
+ try {
609
+ write();
610
+ } catch (err) {
611
+ if (journalWarned) return;
612
+ journalWarned = true;
613
+ io.stderr(`[bkit-telemetry] journal write failed: ${(err as Error).message}\n`);
614
+ }
615
+ };
616
+ const excluded = new Set(
617
+ [...Object.keys(SHARED_EXIT_CODES), ...Object.keys(spec.exitCodes ?? {})].map(Number),
618
+ );
619
+ let input: JournalInput | undefined;
620
+ /** undefined: not dispatched; null: the verb threw; a number: its exit code. */
621
+ let outcome: number | null | undefined;
357
622
  try {
358
623
  const own = rest.filter((arg) => arg !== JSON_FLAG);
359
624
  if (own.some((arg) => arg.startsWith(`${JSON_FLAG}=`))) {
@@ -361,11 +626,23 @@ export async function runCommand(
361
626
  }
362
627
  ctx.json = own.length !== rest.length;
363
628
  ctx.flags = parseFlags(own, spec.flags);
364
- return await spec.run(ctx);
629
+ input = { noun: cmd.noun, verb, argv: rest, flags: ctx.flags, cwd: ctx.cwd };
630
+ const entered = input;
631
+ guarded(() => journal.call(entered));
632
+ outcome = null;
633
+ const code = await spec.run(ctx);
634
+ outcome = code;
635
+ return code;
365
636
  } catch (err) {
366
637
  if (!(err instanceof CommandError)) throw err;
367
638
  io.stderr(`${tag} ${err.message}\n`);
639
+ outcome = err.code;
368
640
  return err.code;
641
+ } finally {
642
+ if (input !== undefined && outcome !== undefined && shouldRecordFriction(outcome, excluded)) {
643
+ const failed = { ...input, code: outcome };
644
+ guarded(() => journal.failure(failed));
645
+ }
369
646
  }
370
647
  }
371
648
 
@@ -411,6 +688,16 @@ export function git(cwd: string, args: string[]): string | null {
411
688
  return res.ok ? res.stdout : null;
412
689
  }
413
690
 
691
+ /**
692
+ * True when git's ignore rules match `rel` in `cwd`. A tracked file reads as not
693
+ * ignored, so an ignored `rel` is always an untracked file git would refuse to
694
+ * `add` when a pathspec names it (the guard `:(exclude)` and `--pathspec-from-file`
695
+ * trip). Check before naming a path in an add pathspec.
696
+ */
697
+ export function isIgnoredPath(cwd: string, rel: string): boolean {
698
+ return runGit(cwd, ["check-ignore", "-q", "--", rel]).ok;
699
+ }
700
+
414
701
  /** `JSON.parse` as a result instead of a throw; each caller says what bad input means for it. */
415
702
  // Shared with the files that are not commands (checks, install): re-exported here
416
703
  // for the command modules that already import it from this module.
@@ -498,14 +785,24 @@ export function runGh(
498
785
  export const ghUnavailable = (res: GhResult): boolean =>
499
786
  res.missing || res.status === 4 || (!res.ok && /\bHTTP 403\b/.test(res.stderr));
500
787
 
788
+ /**
789
+ * The main checkout's root from any worktree, or `null` when not inside a git repo.
790
+ * `--git-common-dir` points at the shared `.git`, so a linked worktree resolves to the
791
+ * same root as the main one.
792
+ */
793
+ export function mainCheckoutRoot(cwd: string): string | null {
794
+ const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
795
+ return common ? path.dirname(common) : null;
796
+ }
797
+
501
798
  /**
502
799
  * The main checkout's root, from any worktree. `--git-common-dir` points at the
503
800
  * shared `.git`, so a linked worktree resolves to the same root as the main one.
504
801
  */
505
802
  export function repoRoot(cwd: string): string {
506
- const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
507
- if (!common) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
508
- return path.dirname(common);
803
+ const root = mainCheckoutRoot(cwd);
804
+ if (!root) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
805
+ return root;
509
806
  }
510
807
 
511
808
  /** `<git common dir>/bkit-outbox`: per-run scratch files, never committed; null outside a git repo. */
@@ -10,6 +10,7 @@ import type { CommandSpec } from "./lib.js";
10
10
  import { setupCommand } from "./setup/setup.js";
11
11
  import { branchesCommand } from "./workflow/branches.js";
12
12
  import { challengeCommand } from "./workflow/challenge.js";
13
+ import { completenessCommand } from "./workflow/completeness.js";
13
14
  import { contextCommand } from "./workflow/context.js";
14
15
  import { countersCommand } from "./workflow/counters.js";
15
16
  import { decisionsCommand } from "./workflow/decisions.js";
@@ -18,6 +19,7 @@ import { fidsCommand } from "./workflow/fids.js";
18
19
  import { issuesCommand } from "./workflow/issues.js";
19
20
  import { ledgersCommand } from "./workflow/ledgers.js";
20
21
  import { locksCommand } from "./workflow/locks.js";
22
+ import { plansCommand } from "./workflow/plans.js";
21
23
  import { prsCommand } from "./workflow/prs.js";
22
24
  import { repoCommand } from "./workflow/repo.js";
23
25
  import { roadmapCommand } from "./workflow/roadmap.js";
@@ -26,15 +28,16 @@ import { runtimeCommand } from "./workflow/runtime.js";
26
28
  import { skillsCommand } from "./workflow/skills.js";
27
29
  import { statusCommand } from "./workflow/status.js";
28
30
  import { stepsCommand } from "./workflow/steps.js";
31
+ import { tasksCommand } from "./workflow/tasks.js";
29
32
  import { testsCommand } from "./workflow/tests.js";
30
33
  import { workflowsCommand } from "./workflow/workflows.js";
31
- import { workstreamsCommand } from "./workflow/workstreams.js";
32
34
  import { worktreesCommand } from "./workflow/worktrees.js";
33
35
 
34
36
  export const COMMANDS: readonly CommandSpec[] = [
35
37
  statusCommand,
36
38
  countersCommand,
37
39
  stepsCommand,
40
+ tasksCommand,
38
41
  runtimeCommand,
39
42
  repoCommand,
40
43
  fidsCommand,
@@ -53,7 +56,8 @@ export const COMMANDS: readonly CommandSpec[] = [
53
56
  ledgersCommand,
54
57
  contextCommand,
55
58
  roadmapCommand,
56
- workstreamsCommand,
59
+ plansCommand,
60
+ completenessCommand,
57
61
  ciCommand,
58
62
  setupCommand,
59
63
  ];
@@ -149,6 +149,7 @@ export const setupCommand: CommandSpec = {
149
149
  verbs: {
150
150
  "protect-main": {
151
151
  summary: "Apply bkit's branch protection to main, requiring the capstone check.",
152
+ use: "by-hand",
152
153
  flags: [
153
154
  {
154
155
  name: "dry-run",