@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -6,10 +6,11 @@
6
6
  // workflows already describe: "parse git remote"). The current branch, how far it
7
7
  // trails `origin/dev`, the main checkout, the bkit binary every later block calls,
8
8
  // and whether that bkit is behind the newest release ride along so Step 1 is one call.
9
+ import { randomBytes } from "node:crypto";
9
10
  import * as fs from "node:fs";
10
11
  import * as path from "node:path";
11
12
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
12
- import { DEV, EXIT, git, repoRoot, runGit, runTool } from "../lib.js";
13
+ import { DEV, EXIT, git, outboxRoot, repoRoot, runGit, runTool } from "../lib.js";
13
14
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
14
15
  import { readBkitConfig, trackerScope } from "../../shared/settings.js";
15
16
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
@@ -26,9 +27,14 @@ export function resolveOwnerRepo(cwd) {
26
27
  const gh = runTool("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], cwd);
27
28
  if (gh.status === 0 && splitSlug(gh.stdout))
28
29
  return { ownerRepo: gh.stdout.trim(), source: "gh" };
30
+ const slug = originOwnerRepo(cwd);
31
+ return slug === null ? null : { ownerRepo: slug, source: "remote" };
32
+ }
33
+ /** `owner/repo` from the `origin` remote URL alone (no network); null when origin names none. */
34
+ export function originOwnerRepo(cwd) {
29
35
  const url = git(cwd, ["remote", "get-url", "origin"]);
30
36
  const slug = url ? parseRemoteUrlToSlug(url) : "";
31
- return splitSlug(slug) ? { ownerRepo: slug, source: "remote" } : null;
37
+ return splitSlug(slug) ? slug : null;
32
38
  }
33
39
  /**
34
40
  * How far HEAD trails `origin/dev`, from whatever was last fetched. null when
@@ -80,12 +86,40 @@ export function actionsPermissionsReadable(cwd, ownerRepo) {
80
86
  .at(-1) ?? "";
81
87
  return { readable: res.found && res.status === 0, status: res.status, detail };
82
88
  }
89
+ /** Session folders older than this are pruned by `repo info`. */
90
+ export const SESSION_TTL_MS = 7 * 86_400_000;
91
+ const SESSION_NAME = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z-[0-9a-f]+$/;
92
+ /**
93
+ * Creates `<outboxRoot>/sessions/<utc-time>-<random>/` and prunes session folders
94
+ * whose name stamps them older than {@link SESSION_TTL_MS}. Folders named any
95
+ * other way are left alone.
96
+ */
97
+ export function newSessionDir(outboxRoot, now = new Date()) {
98
+ const sessions = path.join(outboxRoot, "sessions");
99
+ fs.mkdirSync(sessions, { recursive: true });
100
+ for (const name of fs.readdirSync(sessions)) {
101
+ const m = SESSION_NAME.exec(name);
102
+ if (!m)
103
+ continue;
104
+ const at = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]);
105
+ if (now.getTime() - at > SESSION_TTL_MS)
106
+ fs.rmSync(path.join(sessions, name), { recursive: true, force: true });
107
+ }
108
+ const stamp = now
109
+ .toISOString()
110
+ .replace(/[-:]/g, "")
111
+ .replace(/\.\d{3}/, "");
112
+ const dir = path.join(sessions, `${stamp}-${randomBytes(4).toString("hex")}`);
113
+ fs.mkdirSync(dir);
114
+ return dir;
115
+ }
83
116
  export const repoCommand = {
84
117
  noun: "repo",
85
118
  summary: "Repo facts for Step 1: owner/repo, current branch, and how far it trails dev.",
86
119
  verbs: {
87
120
  info: {
88
121
  summary: "owner/repo (gh, else the origin remote), the current branch, and commits behind origin/dev.",
122
+ use: "by-hand",
89
123
  flags: [
90
124
  {
91
125
  name: "fetch",
@@ -109,14 +143,20 @@ export const repoCommand = {
109
143
  repoRoot: "the main checkout (the same from any worktree)",
110
144
  bkit: "the bkit binary the workflow blocks call: <repoRoot>/node_modules/.bin/bkit, else `bkit` on PATH",
111
145
  outboxRoot: "<git common dir>/bkit-outbox: per-run scratch files, never committed",
146
+ sessionDir: "<outboxRoot>/sessions/<utc-time>-<random>/: a new, empty folder per call for this run's prompt.md and issue files; folders older than 7 days are pruned",
112
147
  bkitVersion: ".bkit/version pinnedVersion: the release this repo's bkit files came from (null when unpinned)",
113
148
  bkitLatest: "newest published @cbartens/bkit, asked at most once a day (null when offline, opted out via BKIT_NO_UPDATE_CHECK, or unpinned)",
114
149
  bkitOutdated: "true when bkitVersion is older than bkitLatest (null when either is unknown)",
115
150
  bkitAdvisory: "one line to show the user when bkitOutdated, else null",
116
- trackerTeam: "package.json bkit.linear.team under linear, else null",
117
- trackerProject: "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
118
- trackerSite: "package.json bkit.jira.site under jira (the MCP cloudId), else null",
119
- trackerBoard: "{ownerType, owner, number} read from package.json bkit.github.project under github, else null",
151
+ trackerTeam: "package.json bkit.tracker.linear.team under linear, else null",
152
+ trackerProject: "package.json bkit.tracker.linear.project under linear, bkit.tracker.jira.project under jira, else null",
153
+ trackerSite: "package.json bkit.tracker.jira.site under jira (the MCP cloudId), else null",
154
+ trackerBoard: "{ownerType, owner, number} read from package.json bkit.tracker.github.project under github, else null",
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",
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",
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",
120
160
  },
121
161
  exitCodes: {
122
162
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -149,6 +189,9 @@ export const repoCommand = {
149
189
  const latest = bkitVersionStatus(root, common);
150
190
  if (latest.advisory !== null)
151
191
  ctx.log(latest.advisory);
192
+ const outbox = outboxRoot(ctx.cwd) ?? path.join(root, ".git", "bkit-outbox");
193
+ const config = readBkitConfig(root);
194
+ const states = config.issueTracker === "none" ? null : config[config.issueTracker];
152
195
  ctx.emit({
153
196
  ...resolved,
154
197
  owner,
@@ -157,12 +200,18 @@ export const repoCommand = {
157
200
  ...behind,
158
201
  repoRoot: root,
159
202
  bkit: resolveBkitBinary(root),
160
- outboxRoot: path.join(common ?? path.join(root, ".git"), "bkit-outbox"),
203
+ outboxRoot: outbox,
204
+ sessionDir: newSessionDir(outbox),
161
205
  bkitVersion: latest.version,
162
206
  bkitLatest: latest.latest,
163
207
  bkitOutdated: latest.outdated,
164
208
  bkitAdvisory: latest.advisory,
165
- ...trackerScope(readBkitConfig(root)),
209
+ ...trackerScope(config),
210
+ trackerProgress: states?.progress ?? null,
211
+ trackerReview: states?.review ?? null,
212
+ tasks: config.tasks,
213
+ buildPublishRemote: config.buildPublish.remote,
214
+ buildPublishLocal: config.buildPublish.local,
166
215
  });
167
216
  if (branch === null && ctx.flags.allowDetached !== true) {
168
217
  ctx.log("HEAD is detached — no current branch");
@@ -173,6 +222,7 @@ export const repoCommand = {
173
222
  },
174
223
  preflight: {
175
224
  summary: "Advisory: whether gh can read the repo's Actions permissions (dispatch may 403 without them).",
225
+ use: "by-hand",
176
226
  flags: [
177
227
  {
178
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 { compareTs, 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,10 +39,24 @@ 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)_";
45
- const BANNER = "> Generated tables — do not hand-edit the `bkit` tables; append to `.bkit/issues.jsonl` instead (an `ABANDONED` row hides a FID from every section). `## Notes` blocks are yours and are never overwritten. Everything above the first marker is also yours. notes-post is last. Analysis list length: `package.json` key `bkit.roadmapNext` (positive integer; absent or invalid → 25).";
59
+ const BANNER = "> Generated tables — do not hand-edit the `bkit` tables; append to `.bkit/issues.jsonl` instead (an `ABANDONED` row hides a FID from every section). `## Notes` blocks are yours and are never overwritten. Everything above the first marker is also yours. notes-post is last. Analysis list length: `package.json` key `bkit.prompts.roadmapNext` (positive integer; absent or invalid → 25).";
46
60
  /** Fixed related-utilities line; `@bkit-audit-generate` ends every run with the same text. */
47
61
  export const RELATED_UTILITIES = "> Related utilities, run on demand: `@bkit-utility-update-roadmap` ranks the next best items in `docs/roadmap.md`; `@bkit-utility-update-tracker` brings tracker issues in line with the tracker rules; `@bkit-utility-update-deferrals` and `@bkit-utility-update-failures` close ledger rows the code already resolved; `@bkit-utility-update-decisions`, `@bkit-utility-update-knowledge` and `@bkit-utility-update-documentation` correct ledgers and docs the code has since contradicted.";
48
62
  /** Newest SHIPPED rows on the board; older ones stay in the ledger. */
@@ -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") : "";
@@ -264,13 +282,15 @@ function fold(ctx) {
264
282
  export function featureRow(root, o) {
265
283
  const phase = o.workflow.charAt(0).toUpperCase() + o.workflow.slice(1);
266
284
  return {
267
- ts: Date.now(),
285
+ schema: SCHEMA,
286
+ ts: mintTs(),
268
287
  kind: "feature",
269
- repo: resolveRepoSlug(root) || "unknown/repo",
270
- bkitVersion: readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown",
271
- workflow: o.workflow,
272
- step: o.step,
273
288
  key: o.fid,
289
+ repo: resolveRepoSlug(root) || "unknown/repo",
290
+ bkit: {
291
+ version: readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown",
292
+ },
293
+ by: { workflow: o.workflow, step: o.step },
274
294
  category: "agentic",
275
295
  description: `${phase} closed for ${o.fid}`,
276
296
  status: o.status,
@@ -290,11 +310,13 @@ function appendLedgerRow(root, row) {
290
310
  }
291
311
  }
292
312
  /**
293
- * Append the feature's roadmap row (built from `workflow` / `fid`, or `row` as
294
- * given) under `root`, then re-render the board. Fail-open: a failed append or
295
- * 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.
296
318
  */
297
- export function appendFeature(root, o, log) {
319
+ export function appendFeature(root, o, log, now = refreshStamp()) {
298
320
  let row;
299
321
  if (o.row !== undefined) {
300
322
  const parsed = parseJson(o.row);
@@ -316,13 +338,19 @@ export function appendFeature(root, o, log) {
316
338
  step: o.step ?? `${o.workflow}-close-workflow`,
317
339
  });
318
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);
319
347
  const check = validate(row);
320
348
  if (!check.ok)
321
349
  throw new CommandError(EXIT.USAGE, `not a valid feature row: ${check.reason}`);
322
350
  const problem = appendLedgerRow(root, row);
323
351
  if (problem)
324
- log(`append failed: ${path.join(root, ".bkit", "issues.jsonl")} — ${problem}`);
325
- const board = foldRoadmap(root, log);
352
+ log(`append failed: ${ledger} — ${problem}`);
353
+ const board = foldRoadmap(root, log, now);
326
354
  return { row, appended: problem === undefined, written: board.written, path: board.path };
327
355
  }
328
356
  function feature(ctx) {
@@ -339,17 +367,21 @@ function feature(ctx) {
339
367
  const ROADMAP_FILES = [".bkit/issues.jsonl", "docs/roadmap.md"];
340
368
  /**
341
369
  * Build / debug close: append the feature row in the worktree, then land the
342
- * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). The
343
- * main checkout is never touched. Skipped when the run's own checkout is on dev
344
- * (the row rides that branch's commit). Fail-open throughout: the feat-side row
345
- * 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.
346
377
  */
347
378
  async function mirror(ctx) {
348
379
  const workflow = String(ctx.flags.workflow);
349
380
  const fid = String(ctx.flags.fid);
350
381
  const wt = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
351
382
  const root = repoRoot(ctx.cwd);
352
- const feat = appendFeature(wt, { workflow, fid }, ctx.log);
383
+ const now = refreshStamp();
384
+ const feat = appendFeature(wt, { workflow, fid }, ctx.log, now);
353
385
  const done = (mirrored, skipped) => {
354
386
  if (skipped)
355
387
  ctx.log(`skipping the dev-side roadmap mirror — ${skipped} (feat-side row already written)`);
@@ -366,7 +398,7 @@ async function mirror(ctx) {
366
398
  dir: landDir(root, fid),
367
399
  build: (dir) => {
368
400
  committed = "";
369
- if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log).appended) {
401
+ if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log, now).appended) {
370
402
  committed = "row not appended on dev";
371
403
  return;
372
404
  }
@@ -418,6 +450,7 @@ export const roadmapCommand = {
418
450
  verbs: {
419
451
  fold: {
420
452
  summary: "Rewrite the status tables; carry notes, analysis and the consumer's head through.",
453
+ use: "by-hand",
421
454
  flags: [
422
455
  {
423
456
  name: "root",
@@ -435,6 +468,7 @@ export const roadmapCommand = {
435
468
  },
436
469
  feature: {
437
470
  summary: "Append the feature's roadmap row to .bkit/issues.jsonl, then re-render the board (fail-open).",
471
+ use: "workflow",
438
472
  flags: [
439
473
  {
440
474
  name: "root",
@@ -474,6 +508,7 @@ export const roadmapCommand = {
474
508
  },
475
509
  mirror: {
476
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",
477
512
  flags: [
478
513
  { name: "workflow", type: "string", required: true, help: "build | debug" },
479
514
  { name: "fid", type: "string", required: true, help: "feature id (the row's key)" },