@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
@@ -2,7 +2,7 @@
2
2
  // task blocks between lowercase HTML-comment markers, each task's uppercase fields.
3
3
  //
4
4
  // <!-- bkit:group N start -->
5
- // ### GROUP N: {title}
5
+ // ### TASK GROUP N: {title} (`### GROUP N: {title}` is read too)
6
6
  // <!-- bkit:task M start -->
7
7
  // - [ ] **TASK M:** {title}
8
8
  // - **UPDATE:** `symbol` in `file`: what changes
@@ -27,18 +27,18 @@ export const PLAN_FIELDS = [
27
27
  "TEST FIRST",
28
28
  "TEST EXCEPTION",
29
29
  ];
30
+ /** Why every plan reader (`tests`, `tasks`, `ledgers triage`) refuses a plan with no task blocks. */
31
+ export const NO_MARKERS_REASON = "this plan has no task markers; run /bkit-build again to convert it";
30
32
  const tableCells = (row) => row
31
33
  .split("|")
32
34
  .slice(1, -1)
33
35
  .map((c) => c.trim());
34
36
  /**
35
- * The plan's Reuse Inventory: the first table under the first heading naming Reuse
36
- * Inventory, before the next heading of the same or a higher level. Each row's `File`
37
- * cell gives its backticked paths, normalised. No heading, table or `File` column → null.
37
+ * The first table under the first heading matching `heading`, before the next heading of
38
+ * the same or a higher level: the header line's index and its cells. No heading or table → null.
38
39
  */
39
- export function reuseInventory(text) {
40
- const lines = text.split(/\r?\n/);
41
- const start = lines.findIndex((l) => /^#{2,4} .*Reuse Inventory/i.test(l));
40
+ function firstTable(lines, heading) {
41
+ const start = lines.findIndex((l) => heading.test(l));
42
42
  if (start < 0)
43
43
  return null;
44
44
  const level = /^#+/.exec(lines[start])[0].length;
@@ -51,13 +51,24 @@ export function reuseInventory(text) {
51
51
  }
52
52
  if (head < 0)
53
53
  return null;
54
- const cols = tableCells(lines[head]);
55
- const file = cols.findIndex((c) => /^file\b/i.test(c));
56
- const decision = cols.findIndex((c) => /^decision\b/i.test(c));
54
+ return { head, cols: tableCells(lines[head]) };
55
+ }
56
+ /**
57
+ * The plan's Reuse Inventory: the first table under the first heading naming Reuse
58
+ * Inventory, before the next heading of the same or a higher level. Each row's `File`
59
+ * cell gives its backticked paths, normalised. No heading, table or `File` column → null.
60
+ */
61
+ export function reuseInventory(text) {
62
+ const lines = text.split(/\r?\n/);
63
+ const table = firstTable(lines, /^#{2,4} .*Reuse Inventory/i);
64
+ if (table === null)
65
+ return null;
66
+ const file = table.cols.findIndex((c) => /^file\b/i.test(c));
67
+ const decision = table.cols.findIndex((c) => /^decision\b/i.test(c));
57
68
  if (file < 0)
58
69
  return null;
59
70
  const rows = [];
60
- for (let i = head + 2; i < lines.length && /^\s*\|/.test(lines[i]); i++) {
71
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]); i++) {
61
72
  const cells = tableCells(lines[i]);
62
73
  rows.push({
63
74
  line: lines[i],
@@ -65,7 +76,60 @@ export function reuseInventory(text) {
65
76
  decision: decision < 0 ? "" : (cells[decision] ?? ""),
66
77
  });
67
78
  }
68
- return { head: lines.slice(head, head + 2), rows };
79
+ return { head: lines.slice(table.head, table.head + 2), rows };
80
+ }
81
+ /** The plan's `Derived Test Matrix` over `tableCells`; null when the plan has no such table. */
82
+ export function derivedTestMatrix(text) {
83
+ const lines = text.split(/\r?\n/);
84
+ const table = firstTable(lines, /^#{2,4} .*Derived Test Matrix/i);
85
+ if (table === null)
86
+ return null;
87
+ const column = table.cols.findIndex((c) => /^task\b/i.test(c));
88
+ const rows = [];
89
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]); i++) {
90
+ const cells = tableCells(lines[i]);
91
+ rows.push({
92
+ line: lines[i],
93
+ number: i + 1,
94
+ cells,
95
+ tasks: column < 0 ? [] : [...(cells[column] ?? "").matchAll(/\d+/g)].map((m) => Number(m[0])),
96
+ });
97
+ }
98
+ return {
99
+ head: lines.slice(table.head, table.head + 2),
100
+ line: table.head + 1,
101
+ taskColumn: column < 0 ? null : column,
102
+ rows,
103
+ };
104
+ }
105
+ /** The plan's `Supersession Inventory` rows over `tableCells`; null when the plan has no such table. */
106
+ export function supersessionInventory(text) {
107
+ const lines = text.split(/\r?\n/);
108
+ const table = firstTable(lines, /^#{2,4} .*Supersession Inventory/i);
109
+ if (table === null)
110
+ return null;
111
+ const column = table.cols.findIndex((c) => /^existing\b/i.test(c));
112
+ const rows = [];
113
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]); i++) {
114
+ const cells = tableCells(lines[i]);
115
+ rows.push({
116
+ line: lines[i],
117
+ number: i + 1,
118
+ files: spansOf(cells[column < 0 ? 0 : column] ?? "").map((f) => path.posix.normalize(f)),
119
+ });
120
+ }
121
+ return rows;
122
+ }
123
+ /** The plan's `Out of Scope` rows over `tableCells`; null when the plan has no such table. */
124
+ export function outOfScope(text) {
125
+ const lines = text.split(/\r?\n/);
126
+ const table = firstTable(lines, /^#{2,4} .*Out of Scope/i);
127
+ if (table === null)
128
+ return null;
129
+ const rows = [];
130
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]); i++)
131
+ rows.push({ line: lines[i], number: i + 1, cells: tableCells(lines[i]) });
132
+ return rows;
69
133
  }
70
134
  /** The error for a code fence opened at `line` and never closed. */
71
135
  export const fenceNeverClosed = (line) => `the code fence at line ${line} is never closed; nothing after it is read`;
@@ -77,7 +141,7 @@ const SINGLE_FIELDS = new Set([
77
141
  "TEST EXCEPTION",
78
142
  ]);
79
143
  const MARKER = /^\s*<!--\s*bkit:(group|task)\s+(\d+)\s+(start|end)\s*-->\s*$/;
80
- const GROUP_HEAD = /^###\s+GROUP\s+(\d+):\s*(.*)$/;
144
+ const GROUP_HEAD = /^###\s+(?:TASK\s+)?GROUP\s+(\d+):\s*(.*)$/;
81
145
  const TASK_HEAD = /^\s*- \[([ xX])\] \*\*TASK (\d+):\*\*\s*(.*)$/;
82
146
  const LABEL_LINE = /^(\s*)(?:- )?\*\*([A-Za-z][A-Za-z -]*?):\*\*\s*(.*)$/;
83
147
  const SUB_BULLET = /^(\s*)- (.*)$/;
@@ -258,7 +322,7 @@ export function parsePlanBlocks(text) {
258
322
  if (want.kind === "group") {
259
323
  const h = GROUP_HEAD.exec(raw);
260
324
  if (h === null)
261
- err(n, `GROUP ${want.n} (line ${want.line}) is not followed by \`### GROUP ${want.n}: {title}\``);
325
+ err(n, `GROUP ${want.n} (line ${want.line}) is not followed by \`### TASK GROUP ${want.n}: {title}\``);
262
326
  else if (Number(h[1]) !== want.n)
263
327
  err(n, `heading says GROUP ${h[1]}, its marker at line ${want.line} says GROUP ${want.n}`);
264
328
  else if (group !== null)
@@ -0,0 +1,205 @@
1
+ // bkit plans parse|comment — design Step 11: read the organised design's
2
+ // `## Suggested Workstreams` and `## Suggested Plans` and build the advisory comment
3
+ // for the feature's own issue.
4
+ //
5
+ // A workstream is a logical unit of the design; a plan is the filed unit (one issue,
6
+ // one plan doc, one branch / PR) covering one or more workstreams. Advisory only.
7
+ // Workflows never create tracker issues, comment on another issue, or set blockers,
8
+ // so nothing here matches plans to issues or builds blocked-by bodies. The tracker
9
+ // write itself stays an MCP call in the workflow; this prepares its body.
10
+ import * as fs from "node:fs";
11
+ import * as path from "node:path";
12
+ import { CommandError, EXIT } from "../lib.js";
13
+ import { COMMENT_FILE_OUTPUT, GENERATED_MARKER, commentFileOf, stampMarker } from "./tracker.js";
14
+ /** Exit code: no workstream parsed — the workflow's Failure Path. */
15
+ export const EXIT_NONE = 3;
16
+ const HEADING = /^(#{1,6})\s+(.*?)\s*$/;
17
+ const INLINE = /^\W*(Requires|Covers)\W*:\**\s*(.*)$/i;
18
+ /**
19
+ * Every `### {PREFIX}-{N}: {NAME}` block under the LAST `## {title}` heading (the
20
+ * organise step appends it after a verbatim copy of the design), with the first
21
+ * value line of each `####` subsection. An inline `Requires: [...]` or `Covers: [...]`
22
+ * line directly under the block heading is read too.
23
+ */
24
+ function sectionBlocks(md, title, prefix) {
25
+ const lines = md.split("\n");
26
+ let start = -1;
27
+ lines.forEach((l, i) => {
28
+ if (new RegExp(`^##\\s+${title}\\s*$`).test(l))
29
+ start = i;
30
+ });
31
+ if (start === -1)
32
+ return [];
33
+ const blockHeading = new RegExp(`^###\\s+${prefix}-(\\d+):\\s*(.*?)\\s*$`);
34
+ const out = [];
35
+ let current;
36
+ /** The `####` subsection the line sits in; undefined directly under the block heading. */
37
+ let sub;
38
+ for (const line of lines.slice(start + 1)) {
39
+ const h = HEADING.exec(line);
40
+ if (h && h[1].length <= 2)
41
+ break;
42
+ const b = blockHeading.exec(line);
43
+ if (b) {
44
+ current = { n: Number(b[1]), name: b[2], fields: {} };
45
+ sub = undefined;
46
+ out.push(current);
47
+ continue;
48
+ }
49
+ if (!current)
50
+ continue;
51
+ if (h) {
52
+ sub = h[2].toLowerCase();
53
+ continue;
54
+ }
55
+ const inline = sub === undefined ? INLINE.exec(line) : null;
56
+ const key = sub ?? inline?.[1].toLowerCase();
57
+ const value = (sub === undefined ? inline?.[2] : line)?.trim();
58
+ if (key !== undefined && value && current.fields[key] === undefined)
59
+ current.fields[key] = value;
60
+ }
61
+ return out;
62
+ }
63
+ const ids = (text, prefix) => text.match(new RegExp(`${prefix}-\\d+`, "g")) ?? [];
64
+ /** Every `### WS-{N}: {NAME}` block under the last `## Suggested Workstreams`, with its `Requires`. */
65
+ export function parseWorkstreams(md) {
66
+ return sectionBlocks(md, "Suggested Workstreams", "WS").map((b) => {
67
+ const requiresText = b.fields.requires ?? "";
68
+ return {
69
+ id: `WS-${b.n}`,
70
+ n: b.n,
71
+ name: b.name,
72
+ requires: ids(requiresText, "WS"),
73
+ requiresText,
74
+ };
75
+ });
76
+ }
77
+ /**
78
+ * Every `### P-{N}: {NAME}` block under the last `## Suggested Plans`, with its
79
+ * `Covers` and `Requires`. A design with no plan block yields one plan per
80
+ * workstream: `P-{N}` covers `WS-{N}`, its `Requires` mapped to plan ids.
81
+ */
82
+ export function parsePlans(md) {
83
+ const plans = sectionBlocks(md, "Suggested Plans", "P").map((b) => {
84
+ const requiresText = b.fields.requires ?? "";
85
+ return {
86
+ id: `P-${b.n}`,
87
+ n: b.n,
88
+ name: b.name,
89
+ covers: ids(b.fields.covers ?? "", "WS"),
90
+ requires: ids(requiresText, "P"),
91
+ requiresText,
92
+ };
93
+ });
94
+ if (plans.length > 0)
95
+ return plans;
96
+ return parseWorkstreams(md).map((w) => ({
97
+ id: `P-${w.n}`,
98
+ n: w.n,
99
+ name: w.name,
100
+ covers: [w.id],
101
+ requires: w.requires.map((r) => r.replace("WS-", "P-")),
102
+ requiresText: w.requiresText.replace(/WS-(\d+)/g, "P-$1"),
103
+ }));
104
+ }
105
+ /** `[]` or `[P-1, P-2]`. */
106
+ export const requiresList = (p) => `[${p.requires.join(", ")}]`;
107
+ /** `WS-1 (Data model), WS-2 (API)`: a plan's covered workstreams with their names. */
108
+ export function coversList(p, ws) {
109
+ return p.covers
110
+ .map((id) => {
111
+ const name = ws.find((w) => w.id === id)?.name;
112
+ return name === undefined ? id : `${id} (${name})`;
113
+ })
114
+ .join(", ");
115
+ }
116
+ /**
117
+ * The Step 11 comment: one line per plan with its covered workstreams, the filing
118
+ * line (one issue per plan; a single plan is planned on this issue), then the design
119
+ * doc link.
120
+ */
121
+ export function commentBody(plans, ws, opts) {
122
+ const doc = `docs/plans/${opts.month}/${opts.fid}-design.md`;
123
+ const url = `https://github.com/${opts.ownerRepo}/blob/dev/${doc}`;
124
+ const filing = plans.length === 1
125
+ ? "One plan covers every workstream: plan it on this issue, no new issue."
126
+ : `Filing one issue per plan: put \`**Parent design:** [${opts.fid}-design.md](${url})\` and \`**Workstreams:** {its Covers ids}\` in its body, and list the plan issues it requires in a blocked-by block (.bkit/trackers.md § Issue shapes).`;
127
+ const lines = [
128
+ GENERATED_MARKER,
129
+ "### Step 11 — Suggested Plans",
130
+ "Advisory only. NEVER auto-trigger.",
131
+ ...plans.map((p) => `- ${p.id}: ${p.name}. Covers: ${coversList(p, ws)}. Requires: ${requiresList(p)}`),
132
+ filing,
133
+ `[${doc}](${url})`,
134
+ ];
135
+ return stampMarker(lines.join("\n"));
136
+ }
137
+ const ARTIFACT_FLAG = {
138
+ name: "artifact",
139
+ type: "string",
140
+ required: true,
141
+ help: "the organised design, docs/plans/{YYYYMM}/logs/{FID}/design-v3-organised.md",
142
+ };
143
+ function read(ctx) {
144
+ const file = path.resolve(ctx.cwd, String(ctx.flags.artifact));
145
+ if (!fs.existsSync(file))
146
+ throw new CommandError(EXIT.USAGE, `--artifact ${file} does not exist`);
147
+ const md = fs.readFileSync(file, "utf-8");
148
+ const workstreams = parseWorkstreams(md);
149
+ if (workstreams.length === 0) {
150
+ throw new CommandError(EXIT_NONE, `no "### WS-{N}: {NAME}" block under "## Suggested Workstreams" in ${file}`);
151
+ }
152
+ return { workstreams, plans: parsePlans(md) };
153
+ }
154
+ export const plansCommand = {
155
+ noun: "plans",
156
+ summary: "Parse the organised design's suggested plans and workstreams and build the advisory comment.",
157
+ verbs: {
158
+ parse: {
159
+ summary: "List each P-{N} with its name, Covers and Requires; one plan per workstream when the design has no Suggested Plans.",
160
+ use: "by-hand",
161
+ flags: [ARTIFACT_FLAG],
162
+ output: {
163
+ plans: "[{id, n, name, covers, requires, requiresText}] in file order",
164
+ workstreams: "[{id, n, name, requires, requiresText}] in file order",
165
+ },
166
+ exitCodes: { [EXIT_NONE]: "no workstream parsed (Failure Path)" },
167
+ run: (ctx) => {
168
+ const { workstreams, plans } = read(ctx);
169
+ ctx.emit({ plans, workstreams });
170
+ return EXIT.OK;
171
+ },
172
+ },
173
+ comment: {
174
+ summary: "The Step 11 comment body for the feature's own issue (posted via MCP by the workflow).",
175
+ use: "workflow",
176
+ flags: [
177
+ ARTIFACT_FLAG,
178
+ { name: "fid", type: "string", required: true, help: "feature id" },
179
+ { name: "month", type: "string", required: true, help: "YYYYMM bucket of the design doc" },
180
+ {
181
+ name: "owner-repo",
182
+ type: "string",
183
+ required: true,
184
+ help: "owner/repo for the design doc link",
185
+ },
186
+ ],
187
+ output: {
188
+ comment: "the comment body",
189
+ commentFile: COMMENT_FILE_OUTPUT,
190
+ plans: "the parsed plans",
191
+ },
192
+ exitCodes: { [EXIT_NONE]: "no workstream parsed (Failure Path)" },
193
+ run: (ctx) => {
194
+ const { workstreams, plans } = read(ctx);
195
+ const body = commentBody(plans, workstreams, {
196
+ ownerRepo: String(ctx.flags.ownerRepo),
197
+ month: String(ctx.flags.month),
198
+ fid: String(ctx.flags.fid),
199
+ });
200
+ ctx.emit({ comment: body, commentFile: commentFileOf(ctx.cwd, body), plans });
201
+ return EXIT.OK;
202
+ },
203
+ },
204
+ },
205
+ };
@@ -392,9 +392,9 @@ export function devRequiresChecks(gh, repo) {
392
392
  return gh(["api", `repos/${repo}/branches/dev/protection/required_status_checks`]).ok;
393
393
  }
394
394
  /**
395
- * Request a server-side base-into-head refresh (ship Step 4 B1). GitHub authors
396
- * the merge commit, so bkit cannot set its message and there is no local head to
397
- * read back — ship's Step 9 poll observes the new head. gh missing →
395
+ * Request a server-side base-into-head refresh. GitHub authors the merge commit,
396
+ * so bkit cannot set its message and there is no local head to read back. Ship
397
+ * does not call it: its Step 4 merges origin/dev locally (`branches sync --merge`). gh missing →
398
398
  * EXIT.USE_MCP (route through `update_pull_request_branch`).
399
399
  *
400
400
  * `onlyIfRequired`: refresh only when dev requires status checks. Otherwise the
@@ -685,6 +685,7 @@ export const prsCommand = {
685
685
  verbs: {
686
686
  open: {
687
687
  summary: "Open a PR whose body carries the bkit:issue / bkit:fid marker (exit 80: use MCP).",
688
+ use: "workflow",
688
689
  flags: [
689
690
  { name: "fid", type: "string", required: true, help: "feature id" },
690
691
  { name: "title", type: "string", required: true, help: "PR title (no skip-CI token)" },
@@ -742,6 +743,7 @@ export const prsCommand = {
742
743
  },
743
744
  probe: {
744
745
  summary: "The open (or open-then-merged) PR for a branch, or one PR by number.",
746
+ use: "by-hand",
745
747
  flags: [
746
748
  HEAD_FLAG,
747
749
  { name: "base", type: "string", help: "only PRs into this base (default: any base)" },
@@ -779,6 +781,7 @@ export const prsCommand = {
779
781
  },
780
782
  merge: {
781
783
  summary: "Squash-merge a PR with an empty body (skipped when already MERGED) and read its state back.",
784
+ use: "workflow",
782
785
  flags: [
783
786
  { name: "number", type: "string", required: true, help: "the PR number" },
784
787
  {
@@ -851,6 +854,7 @@ export const prsCommand = {
851
854
  },
852
855
  "update-branch": {
853
856
  summary: "Refresh a PR's head from its base server-side (exit 80: use update_pull_request_branch).",
857
+ use: "workflow",
854
858
  flags: [
855
859
  { name: "number", type: "string", required: true, help: "the PR number" },
856
860
  {
@@ -880,6 +884,7 @@ export const prsCommand = {
880
884
  },
881
885
  checks: {
882
886
  summary: "A PR's check rollup, classified: green when present and none failed or pending (exit 80: use MCP).",
887
+ use: "by-hand",
883
888
  flags: [{ name: "number", type: "string", required: true, help: "the PR number" }],
884
889
  output: {
885
890
  number: "the PR number",
@@ -905,6 +910,7 @@ export const prsCommand = {
905
910
  },
906
911
  "verbose-ci": {
907
912
  summary: "Add ` bkit [verbose ci]` to a PR title, or strip it (with an optional `bkit ` prefix); a no-op when already so.",
913
+ use: "workflow",
908
914
  flags: [
909
915
  { name: "number", type: "string", required: true, help: "the PR number" },
910
916
  { name: "state", type: "string", required: true, help: "on | off" },
@@ -956,6 +962,7 @@ export const prsCommand = {
956
962
  },
957
963
  "scan-body": {
958
964
  summary: "Check a landed commit's body (not its subject) for a CI-suppressing token.",
965
+ use: "by-hand",
959
966
  flags: [
960
967
  { name: "sha", type: "string", required: true, help: "the landed commit" },
961
968
  {
@@ -974,6 +981,7 @@ export const prsCommand = {
974
981
  },
975
982
  "cross-check": {
976
983
  summary: "An mcp close with gh recorded unavailable must have a transport-fallback row.",
984
+ use: "workflow",
977
985
  flags: [
978
986
  FILE_FLAG,
979
987
  {
@@ -994,6 +1002,7 @@ export const prsCommand = {
994
1002
  },
995
1003
  "transport-row": {
996
1004
  summary: "Append a transport-fallback or close-transport audit row to status.jsonl.",
1005
+ use: "workflow",
997
1006
  flags: [
998
1007
  FILE_FLAG,
999
1008
  { name: "kind", type: "string", required: true, help: "fallback | close" },
@@ -119,6 +119,7 @@ export const repoCommand = {
119
119
  verbs: {
120
120
  info: {
121
121
  summary: "owner/repo (gh, else the origin remote), the current branch, and commits behind origin/dev.",
122
+ use: "by-hand",
122
123
  flags: [
123
124
  {
124
125
  name: "fetch",
@@ -154,6 +155,8 @@ export const repoCommand = {
154
155
  trackerProgress: "the state an issue moves to when work starts: package.json bkit.tracker.<tracker>.progress for the wired tracker, at its default when unset (github `In progress`, linear `started`, jira `In Progress`); null under none",
155
156
  trackerReview: "the state an issue moves to when it is handed to a human: package.json bkit.tracker.<tracker>.review for the wired tracker, at its default when unset (github `In review`, linear `In Review`, jira `In Review`); null under none",
156
157
  tasks: "{maxPerGroup, maxTestsPerGroup, maxTestsPerTask, maxTestFilesPerTask}: the plan caps from package.json bkit.workflows.tasks, each missing or invalid key at its default",
158
+ buildPublishRemote: "boolean: the remote build ending from package.json bkit.workflows.build.publish.remote; always true, a false value is refused",
159
+ buildPublishLocal: "boolean: the local build ending from package.json bkit.workflows.build.publish.local; true publishes, false holds; true when unset or invalid",
157
160
  },
158
161
  exitCodes: {
159
162
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -207,6 +210,8 @@ export const repoCommand = {
207
210
  trackerProgress: states?.progress ?? null,
208
211
  trackerReview: states?.review ?? null,
209
212
  tasks: config.tasks,
213
+ buildPublishRemote: config.buildPublish.remote,
214
+ buildPublishLocal: config.buildPublish.local,
210
215
  });
211
216
  if (branch === null && ctx.flags.allowDetached !== true) {
212
217
  ctx.log("HEAD is detached — no current branch");
@@ -217,6 +222,7 @@ export const repoCommand = {
217
222
  },
218
223
  preflight: {
219
224
  summary: "Advisory: whether gh can read the repo's Actions permissions (dispatch may 403 without them).",
225
+ use: "by-hand",
220
226
  flags: [
221
227
  {
222
228
  name: "owner-repo",
@@ -16,7 +16,7 @@
16
16
  // a bad ledger or an unwritable board, and never gates the caller's close.
17
17
  import * as fs from "node:fs";
18
18
  import * as path from "node:path";
19
- import { SCHEMA, compareTs, mintTs, parse, resolveRepoSlug, validate, } from "../../ledgers/telemetry.js";
19
+ import { SCHEMA, compareTs, mintTs, parse, resolveRepoSlug, validate, withLineage, } from "../../ledgers/telemetry.js";
20
20
  import { readBkitVersion } from "../../install/version-file.js";
21
21
  import { CommandError, DEV, EXIT, git, parseJson, repoRoot, runGit, } from "../lib.js";
22
22
  import { landDir, pushToDev } from "../land.js";
@@ -39,6 +39,20 @@ export const MARKERS = {
39
39
  analysisStart: "<!-- bkit:roadmap-analysis start -->",
40
40
  analysisEnd: "<!-- bkit:roadmap-analysis end -->",
41
41
  };
42
+ /** Title and rules box a new board opens with; the consumer owns both once the file exists. */
43
+ export const SEEDED_HEAD = [
44
+ "# Roadmap",
45
+ "",
46
+ "> [!CAUTION]",
47
+ "> **Purpose:** Phase board of every bkit feature, projected from `.bkit/issues.jsonl`, plus the best-next-step analysis and your notes.",
48
+ ">",
49
+ "> **Rules:**",
50
+ ">",
51
+ "> - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit the parts that are yours.",
52
+ "> - Text above the first marker and the `## Notes` blocks are yours; bkit never overwrites them.",
53
+ "> - Everything between the `bkit:roadmap-status` markers is generated: `bkit roadmap fold` rewrites it on every run, so a hand edit there is lost. Append to `.bkit/issues.jsonl` instead.",
54
+ "> - Everything between the `bkit:roadmap-analysis` markers belongs to `@bkit-utility-update-roadmap`, which rewrites it on every run.",
55
+ ].join("\n");
42
56
  const ANALYSIS_PLACEHOLDER = "_(no analysis yet; run @bkit-utility-update-roadmap to populate)_";
43
57
  const NOTES_PRE_PLACEHOLDER = "## Notes\n\n_(above the bkit list — yours, never overwritten)_";
44
58
  const NOTES_POST_PLACEHOLDER = "## Notes\n\n_(end of the board — yours, never overwritten)_";
@@ -199,7 +213,7 @@ export function foldBoard(p, current, now) {
199
213
  // never rewrites it. The generated-tables warning lives in the status block,
200
214
  // so its wording stays true as the region's rules change.
201
215
  if (blank(head))
202
- head = "# Roadmap";
216
+ head = SEEDED_HEAD;
203
217
  let merge = adopted;
204
218
  if (!blank(tail))
205
219
  merge = appendNotes(merge, tail);
@@ -223,11 +237,15 @@ export function foldBoard(p, current, now) {
223
237
  return { board: `${board}\n`, log };
224
238
  }
225
239
  const EMPTY = { designed: [], planned: [], built: [], debugged: [], shipped: [] };
226
- /** Re-render `<root>/docs/roadmap.md` from `<root>/.bkit/issues.jsonl`; never throws for a bad ledger or board. */
227
- export function foldRoadmap(root, log) {
240
+ /** The `_(refreshed …)_` stamp for this moment, to the second. */
241
+ export const refreshStamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
242
+ /**
243
+ * Re-render `<root>/docs/roadmap.md` from `<root>/.bkit/issues.jsonl`, stamped
244
+ * `now`; never throws for a bad ledger or board.
245
+ */
246
+ export function foldRoadmap(root, log, now = refreshStamp()) {
228
247
  const md = path.join(root, "docs", "roadmap.md");
229
248
  const ledger = path.join(root, ".bkit", "issues.jsonl");
230
- const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
231
249
  let projection = EMPTY;
232
250
  let malformed = 0;
233
251
  const raw = fs.existsSync(ledger) && fs.statSync(ledger).isFile() ? fs.readFileSync(ledger, "utf-8") : "";
@@ -292,11 +310,13 @@ function appendLedgerRow(root, row) {
292
310
  }
293
311
  }
294
312
  /**
295
- * Append the feature's roadmap row (built from `workflow` / `fid`, or `row` as
296
- * given) under `root`, then re-render the board. Fail-open: a failed append or
297
- * render is logged and reported, never thrown.
313
+ * Append the feature's roadmap row under `root`, then re-render the board stamped
314
+ * `now`. A row built from `workflow` / `fid`, or a `row` without `updates`, gets
315
+ * `firstTs` + `updates` carried forward from the FID's rows already in the ledger;
316
+ * a `row` that carries `updates` (one an earlier call printed) is appended byte
317
+ * for byte. Fail-open: a failed append or render is logged and reported, never thrown.
298
318
  */
299
- export function appendFeature(root, o, log) {
319
+ export function appendFeature(root, o, log, now = refreshStamp()) {
300
320
  let row;
301
321
  if (o.row !== undefined) {
302
322
  const parsed = parseJson(o.row);
@@ -318,13 +338,19 @@ export function appendFeature(root, o, log) {
318
338
  step: o.step ?? `${o.workflow}-close-workflow`,
319
339
  });
320
340
  }
341
+ const ledger = path.join(root, ".bkit", "issues.jsonl");
342
+ const prior = fs.existsSync(ledger) && fs.statSync(ledger).isFile()
343
+ ? parse(fs.readFileSync(ledger, "utf-8")).events
344
+ : [];
345
+ if (o.row === undefined || !("updates" in row))
346
+ row = withLineage(prior, row);
321
347
  const check = validate(row);
322
348
  if (!check.ok)
323
349
  throw new CommandError(EXIT.USAGE, `not a valid feature row: ${check.reason}`);
324
350
  const problem = appendLedgerRow(root, row);
325
351
  if (problem)
326
- log(`append failed: ${path.join(root, ".bkit", "issues.jsonl")} — ${problem}`);
327
- const board = foldRoadmap(root, log);
352
+ log(`append failed: ${ledger} — ${problem}`);
353
+ const board = foldRoadmap(root, log, now);
328
354
  return { row, appended: problem === undefined, written: board.written, path: board.path };
329
355
  }
330
356
  function feature(ctx) {
@@ -341,17 +367,21 @@ function feature(ctx) {
341
367
  const ROADMAP_FILES = [".bkit/issues.jsonl", "docs/roadmap.md"];
342
368
  /**
343
369
  * Build / debug close: append the feature row in the worktree, then land the
344
- * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). The
345
- * main checkout is never touched. Skipped when the run's own checkout is on dev
346
- * (the row rides that branch's commit). Fail-open throughout: the feat-side row
347
- * is already written and reaches dev with ship's merge.
370
+ * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). Both
371
+ * sides get the row's exact bytes and one shared refresh stamp, so the branch and
372
+ * dev make the same change to `.bkit/issues.jsonl` and `docs/roadmap.md` and the
373
+ * feature PR merges without a conflict on either. The main checkout is never
374
+ * touched. Skipped when the run's own checkout is on dev (the row rides that
375
+ * branch's commit). Fail-open throughout: the feat-side row is already written
376
+ * and reaches dev with ship's merge.
348
377
  */
349
378
  async function mirror(ctx) {
350
379
  const workflow = String(ctx.flags.workflow);
351
380
  const fid = String(ctx.flags.fid);
352
381
  const wt = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
353
382
  const root = repoRoot(ctx.cwd);
354
- const feat = appendFeature(wt, { workflow, fid }, ctx.log);
383
+ const now = refreshStamp();
384
+ const feat = appendFeature(wt, { workflow, fid }, ctx.log, now);
355
385
  const done = (mirrored, skipped) => {
356
386
  if (skipped)
357
387
  ctx.log(`skipping the dev-side roadmap mirror — ${skipped} (feat-side row already written)`);
@@ -368,7 +398,7 @@ async function mirror(ctx) {
368
398
  dir: landDir(root, fid),
369
399
  build: (dir) => {
370
400
  committed = "";
371
- if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log).appended) {
401
+ if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log, now).appended) {
372
402
  committed = "row not appended on dev";
373
403
  return;
374
404
  }
@@ -420,6 +450,7 @@ export const roadmapCommand = {
420
450
  verbs: {
421
451
  fold: {
422
452
  summary: "Rewrite the status tables; carry notes, analysis and the consumer's head through.",
453
+ use: "by-hand",
423
454
  flags: [
424
455
  {
425
456
  name: "root",
@@ -437,6 +468,7 @@ export const roadmapCommand = {
437
468
  },
438
469
  feature: {
439
470
  summary: "Append the feature's roadmap row to .bkit/issues.jsonl, then re-render the board (fail-open).",
471
+ use: "workflow",
440
472
  flags: [
441
473
  {
442
474
  name: "root",
@@ -476,6 +508,7 @@ export const roadmapCommand = {
476
508
  },
477
509
  mirror: {
478
510
  summary: "Build / debug close: append the feature row in the worktree, then land the same row on dev through a throwaway origin/dev checkout (fail-open).",
511
+ use: "workflow",
479
512
  flags: [
480
513
  { name: "workflow", type: "string", required: true, help: "build | debug" },
481
514
  { name: "fid", type: "string", required: true, help: "feature id (the row's key)" },