@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
@@ -1,6 +1,7 @@
1
1
  // commands/lib.ts — what every `bkit <noun> <verb>` command shares.
2
2
  //
3
- // Flag parsing, one JSON object on stdout, `[bkit-<noun>]`-tagged logs on stderr,
3
+ // Flag parsing, one output object on stdout (text, or JSON with `--json`),
4
+ // `[bkit-<noun>]`-tagged logs on stderr,
4
5
  // the exit-code table, `--help` rendering, and the repo facts several workflow
5
6
  // steps each re-derived by hand: repo root, UTC month, where `status.jsonl` lives,
6
7
  // the skip-CI tokens, and which branches are shared. A command declares its flags,
@@ -12,7 +13,20 @@ import * as fs from "node:fs";
12
13
  import * as os from "node:os";
13
14
  import * as path from "node:path";
14
15
 
15
- import { gitEnv } from "../ledgers/telemetry.js";
16
+ import {
17
+ appendFrictionRow,
18
+ appendJournalRow,
19
+ engineCallRow,
20
+ frictionRow,
21
+ journalEnabled,
22
+ launchedByGit,
23
+ rebasePaused,
24
+ shouldRecordFriction,
25
+ } from "../ledgers/journal.js";
26
+ import { fold, type StatusEvent } from "../ledgers/status.js";
27
+ import { gitEnv, resolveGitSha } from "../ledgers/telemetry.js";
28
+ import { parseJson } from "../shared/json.js";
29
+ import { renderText } from "../shared/text.js";
16
30
 
17
31
  // ---------------------------------------------------------------------------
18
32
  // Exit codes
@@ -78,21 +92,88 @@ export interface FlagSpec {
78
92
 
79
93
  export type FlagValue = string | boolean | string[] | undefined;
80
94
 
95
+ /** Parse a whole-number flag, using its fallback only when absent. */
96
+ export const wholeNumber = (v: FlagValue, flag: string, fallback: number, min = 0): number => {
97
+ if (v === undefined) return fallback;
98
+ const s = String(v);
99
+ if (!/^[0-9]+$/.test(s) || Number(s) < min) {
100
+ throw new CommandError(EXIT.USAGE, `--${flag} takes a whole number >= ${min} (got "${s}")`);
101
+ }
102
+ return Number(s);
103
+ };
104
+
105
+ /** The holder named by this run when its tests-lock wait gave up. */
106
+ export function testsLockHolder(log: string, who: string): string | null {
107
+ const prefix = `[machine-lock] ❌ ${who} gave up after `;
108
+ for (const line of log.split(/\r?\n/)) {
109
+ if (!line.startsWith(prefix)) continue;
110
+ const holder = /^\d+s waiting for tests, in use by (.+)$/.exec(line.slice(prefix.length));
111
+ if (holder) return holder[1]!;
112
+ }
113
+ return null;
114
+ }
115
+
116
+ /** Classify only a tests-lock outcome, leaving gate and nested-lock failures intact. */
117
+ export function classifyLockExit({
118
+ exitCode,
119
+ log,
120
+ who,
121
+ }: {
122
+ exitCode: number;
123
+ log: string;
124
+ who: string;
125
+ }): "gate" | "lock-wait" | "could-not-run" {
126
+ const lines = log.split(/\r?\n/);
127
+ if (exitCode === 75 && testsLockHolder(log, who) !== null) return "lock-wait";
128
+ if (
129
+ exitCode === 73 &&
130
+ lines.some((line) =>
131
+ /^\[machine-lock\] ❌ (?:could not take the lock for tests:|cannot take tests while holding )/.test(
132
+ line,
133
+ ),
134
+ )
135
+ )
136
+ return "could-not-run";
137
+ return "gate";
138
+ }
139
+
81
140
  export interface RunContext {
82
141
  /** Parsed flags, keyed by camelCase name. */
83
142
  flags: Record<string, FlagValue>;
84
143
  cwd: string;
144
+ /** The global `--json` flag was given. Taken by every verb, never declared in a verb's spec. */
145
+ json: boolean;
85
146
  /** Human-readable line on stderr, tagged `[bkit-<noun>]`. */
86
147
  log(message: string): void;
87
- /** The command's one JSON object on stdout. Call at most once. */
148
+ /**
149
+ * The command's one output object on stdout: text (`shared/text.ts` `renderText`,
150
+ * less the verb's `textOmit` keys), or one JSON object under `--json`. Call at most once.
151
+ */
88
152
  emit(output: Record<string, unknown>): void;
89
153
  }
90
154
 
155
+ /**
156
+ * An output key the text output leaves out: always, or only `when` its value holds.
157
+ * `audits/workflows/text-omit.test.ts` fails when a workflow or prompt reads one.
158
+ */
159
+ export type TextOmit =
160
+ string | { key: string; when: (value: unknown, output: Record<string, unknown>) => boolean };
161
+
162
+ /**
163
+ * Who runs a verb. `by-hand`: safe and useful outside a workflow run (reads, or a job of
164
+ * its own). `workflow`: a workflow step only (writes run state, takes locks, commits,
165
+ * pushes or posts). `.bkit/cli.md` shows it per verb.
166
+ */
167
+ export type VerbUse = "by-hand" | "workflow";
168
+
91
169
  export interface VerbSpec {
92
170
  summary: string;
171
+ use: VerbUse;
93
172
  flags: FlagSpec[];
94
173
  /** Output key -> meaning. Keys are camelCase, matching `status.jsonl`. */
95
174
  output: Record<string, string>;
175
+ /** Output keys no workflow or prompt reads: printed under `--json` only. */
176
+ textOmit?: readonly TextOmit[];
96
177
  /** This verb's own exit codes (3-79) -> meaning. */
97
178
  exitCodes?: Record<number, string>;
98
179
  run(ctx: RunContext): number | Promise<number>;
@@ -243,8 +324,8 @@ export function verbHelp(cmd: CommandSpec, verb: string): string {
243
324
  "Flags:",
244
325
  flags.length ? table(flags) : " none",
245
326
  "",
246
- "Output (one JSON object on stdout):",
247
- table(Object.entries(spec.output)),
327
+ "Output (one object on stdout: `key: value` text, JSON with --json):",
328
+ table(Object.entries(spec.output).map(([key, help]) => [key, help + omitNote(spec, key)])),
248
329
  "",
249
330
  "Exit codes:",
250
331
  table(exitCodeRows(spec.exitCodes)),
@@ -270,6 +351,207 @@ const processIo: Io = {
270
351
 
271
352
  const isHelp = (arg: string | undefined) => arg === "--help" || arg === "-h";
272
353
 
354
+ /** Global boolean flag every verb takes; it is removed before the verb's own flags parse. */
355
+ const JSON_FLAG = "--json";
356
+
357
+ /** `output` less the keys `spec.textOmit` leaves out of text. */
358
+ function textOutput(spec: VerbSpec, output: Record<string, unknown>): Record<string, unknown> {
359
+ const omit = new Set(
360
+ (spec.textOmit ?? []).flatMap((o) =>
361
+ typeof o === "string" ? [o] : o.when(output[o.key], output) ? [o.key] : [],
362
+ ),
363
+ );
364
+ return Object.fromEntries(Object.entries(output).filter(([k]) => !omit.has(k)));
365
+ }
366
+
367
+ /** `--help`'s note on an output key text leaves out: always, or only when it does not matter. */
368
+ function omitNote(spec: VerbSpec, key: string): string {
369
+ const o = (spec.textOmit ?? []).find((x) => (typeof x === "string" ? x : x.key) === key);
370
+ if (o === undefined) return "";
371
+ return typeof o === "string" ? " (--json only)" : " (text: only when it matters)";
372
+ }
373
+
374
+ // ---------------------------------------------------------------------------
375
+ // Journal seam — what `runCommand` records while a workflow run is active
376
+ // ---------------------------------------------------------------------------
377
+
378
+ export interface JournalInput {
379
+ noun: string;
380
+ verb: string;
381
+ /** The argv after the verb; the journal keeps flag names only. */
382
+ argv: string[];
383
+ flags: Record<string, FlagValue>;
384
+ cwd: string;
385
+ }
386
+
387
+ /** The two writes the seam makes; injectable so a test can make either throw. */
388
+ export interface Journal {
389
+ /** One `engine-call` row at dispatch entry. */
390
+ call(input: JournalInput): void;
391
+ /** One `tool-failure` friction row; `code` is null when the command threw. */
392
+ failure(input: JournalInput & { code: number | null }): void;
393
+ }
394
+
395
+ /** The active run a call is attributed to: its `status.jsonl` and the root its other books live under. */
396
+ export interface ActiveRun {
397
+ workflow: string;
398
+ file: string;
399
+ bookRoot: string;
400
+ }
401
+
402
+ /** Row types `fold` reads; the other rows a `status.jsonl` carries (engine-call, ...) stay out of it. */
403
+ const FOLD_TYPES = new Set([
404
+ "workflow-started",
405
+ "step-done",
406
+ "workflow-meta",
407
+ "workflow-done",
408
+ "workflow-failed",
409
+ ]);
410
+
411
+ /** Most `status.jsonl` files `resolveActiveRun` reads when it walks a checkout. */
412
+ const ACTIVE_RUN_SCAN_CAP = 500;
413
+
414
+ /** The workflow of the last run in `file` when that run is IN_PROGRESS, else undefined. */
415
+ function inProgressWorkflow(file: string): string | undefined {
416
+ if (!fs.existsSync(file)) return undefined;
417
+ const events: StatusEvent[] = [];
418
+ for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
419
+ if (line.trim() === "") continue;
420
+ const parsed = parseJson(line);
421
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") continue;
422
+ const type = (parsed.value as { type?: unknown }).type;
423
+ if (typeof type === "string" && FOLD_TYPES.has(type)) events.push(parsed.value as StatusEvent);
424
+ }
425
+ const last = fold(events).at(-1);
426
+ return last?.status === "IN_PROGRESS" ? last.workflow : undefined;
427
+ }
428
+
429
+ /** The directories under `dir`, by name; none when `dir` is missing. */
430
+ function subdirs(dir: string): string[] {
431
+ if (!fs.existsSync(dir)) return [];
432
+ return fs
433
+ .readdirSync(dir, { withFileTypes: true })
434
+ .filter((e) => e.isDirectory())
435
+ .map((e) => e.name);
436
+ }
437
+
438
+ /**
439
+ * The run a command call belongs to, or undefined. In order: the command's own
440
+ * `--file`; `--fid` (+ `--month`, default this UTC month) through `statusLocation`;
441
+ * the single IN_PROGRESS run among the `docs/plans/<month>/logs/<fid>/status.jsonl`
442
+ * files under the cwd's git toplevel (capped), only `--fid`'s own when it is set, so a
443
+ * run from an earlier month is found and another feature's run never is. From the main checkout a feature
444
+ * worktree's run is not found, so an out-of-worktree call is skipped, never
445
+ * attributed to another run. Reads with this module's own `node:fs` and `parseJson`
446
+ * and folds with `ledgers/status.ts`, so it never imports a `commands/**` module.
447
+ */
448
+ export function resolveActiveRun(opts: {
449
+ cwd: string;
450
+ file?: string;
451
+ fid?: string;
452
+ month?: string;
453
+ workflow?: string;
454
+ }): ActiveRun | undefined {
455
+ // A `--file` that is a run's `status.jsonl` names that run; any other file (a plan or
456
+ // design doc) says nothing about the run and falls through to `--fid` and the scan.
457
+ if (opts.file !== undefined && path.basename(opts.file) === "status.jsonl") {
458
+ const file = path.resolve(opts.cwd, opts.file);
459
+ const workflow = inProgressWorkflow(file);
460
+ const logs = path.dirname(path.dirname(file));
461
+ if (
462
+ workflow === undefined ||
463
+ path.basename(logs) !== "logs" ||
464
+ path.basename(path.dirname(path.dirname(logs))) !== "plans"
465
+ ) {
466
+ return undefined;
467
+ }
468
+ return {
469
+ workflow,
470
+ file,
471
+ bookRoot: path.dirname(path.dirname(path.dirname(path.dirname(logs)))),
472
+ };
473
+ }
474
+ if (opts.fid !== undefined) {
475
+ try {
476
+ const loc = statusLocation({
477
+ cwd: opts.cwd,
478
+ workflow: opts.workflow ?? "build",
479
+ fid: opts.fid,
480
+ month: opts.month ?? utcMonth(),
481
+ });
482
+ const workflow = inProgressWorkflow(loc.path);
483
+ if (workflow !== undefined) return { workflow, file: loc.path, bookRoot: loc.bookRoot };
484
+ } catch (err) {
485
+ if (!(err instanceof CommandError)) throw err;
486
+ }
487
+ }
488
+ const top = git(opts.cwd, ["rev-parse", "--show-toplevel"]);
489
+ if (top === null) return undefined;
490
+ const found: ActiveRun[] = [];
491
+ let read = 0;
492
+ for (const month of subdirs(path.join(top, "docs", "plans"))) {
493
+ for (const fid of subdirs(path.join(top, "docs", "plans", month, "logs"))) {
494
+ if (++read > ACTIVE_RUN_SCAN_CAP) return undefined;
495
+ if (opts.fid !== undefined && fid !== opts.fid) continue;
496
+ const file = path.join(top, statusRelPath(month, fid));
497
+ const workflow = inProgressWorkflow(file);
498
+ if (workflow !== undefined) found.push({ workflow, file, bookRoot: top });
499
+ }
500
+ }
501
+ return found.length === 1 ? found[0] : undefined;
502
+ }
503
+
504
+ /** The journal `runCommand` uses unless a caller injects one: writes into the active run's own books. */
505
+ function engineJournal(): Journal {
506
+ let resolved = false;
507
+ let run: ActiveRun | undefined;
508
+ const active = (i: JournalInput): ActiveRun | undefined => {
509
+ if (!resolved) {
510
+ resolved = true;
511
+ const text = (v: FlagValue) => (typeof v === "string" ? v : undefined);
512
+ run = resolveActiveRun({
513
+ cwd: i.cwd,
514
+ file: text(i.flags["file"]),
515
+ fid: text(i.flags["fid"]),
516
+ month: text(i.flags["month"]),
517
+ workflow: text(i.flags["workflow"]),
518
+ });
519
+ }
520
+ return run;
521
+ };
522
+ return {
523
+ call(i) {
524
+ // A call git launched (a hook's `bkit disk prune`) writes no row to the tracked status file.
525
+ if (!journalEnabled() || launchedByGit()) return;
526
+ const r = active(i);
527
+ // A paused rebase refuses `--continue` while the tracked status file has an unstaged row.
528
+ if (r === undefined || rebasePaused(path.dirname(r.file))) return;
529
+ const wrote = appendJournalRow(
530
+ r.file,
531
+ engineCallRow({ workflow: r.workflow, noun: i.noun, verb: i.verb, flags: i.argv }),
532
+ );
533
+ if (!wrote.ok) throw new Error(wrote.error);
534
+ },
535
+ failure(i) {
536
+ if (!journalEnabled()) return;
537
+ const r = active(i);
538
+ if (r === undefined) return;
539
+ const step = i.flags["step"];
540
+ const row = frictionRow({
541
+ workflow: r.workflow,
542
+ step: typeof step === "string" ? step : undefined,
543
+ noun: i.noun,
544
+ verb: i.verb,
545
+ code: i.code,
546
+ bookRoot: r.bookRoot,
547
+ parentSha: resolveGitSha("HEAD", r.bookRoot),
548
+ });
549
+ const wrote = appendFrictionRow(r.bookRoot, row);
550
+ if (!wrote.ok) throw new Error(wrote.error);
551
+ },
552
+ };
553
+ }
554
+
273
555
  /**
274
556
  * Run `argv` (without the leading `bkit`) if it names a registered command.
275
557
  * Returns the exit code, or null when `argv` is not a command, so the caller falls
@@ -281,7 +563,7 @@ const isHelp = (arg: string | undefined) => arg === "--help" || arg === "-h";
281
563
  export async function runCommand(
282
564
  argv: string[],
283
565
  commands: readonly CommandSpec[],
284
- options: { classicVerbs: ReadonlySet<string>; cwd?: string; io?: Io },
566
+ options: { classicVerbs: ReadonlySet<string>; cwd?: string; io?: Io; journal?: Journal },
285
567
  ): Promise<number | null> {
286
568
  const io = options.io ?? processIo;
287
569
  const cmd = commands.find((c) => c.noun === argv[0]);
@@ -310,20 +592,57 @@ export async function runCommand(
310
592
  const ctx: RunContext = {
311
593
  flags: {},
312
594
  cwd: options.cwd ?? process.cwd(),
595
+ json: false,
313
596
  log: (message) => io.stderr(`${tag} ${message}\n`),
314
597
  emit: (output) => {
315
- if (emitted) throw new Error(`${tag} ${verb} emitted twice — one JSON object per run`);
598
+ if (emitted) throw new Error(`${tag} ${verb} emitted twice — one output object per run`);
316
599
  emitted = true;
317
- io.stdout(`${JSON.stringify(output)}\n`);
600
+ io.stdout(ctx.json ? `${JSON.stringify(output)}\n` : renderText(textOutput(spec, output)));
318
601
  },
319
602
  };
603
+ // The journal never changes the verb's exit code, output or throw: each write is
604
+ // swallowed, and the first failure logs one line.
605
+ const journal = options.journal ?? engineJournal();
606
+ let journalWarned = false;
607
+ const guarded = (write: () => void) => {
608
+ try {
609
+ write();
610
+ } catch (err) {
611
+ if (journalWarned) return;
612
+ journalWarned = true;
613
+ io.stderr(`[bkit-telemetry] journal write failed: ${(err as Error).message}\n`);
614
+ }
615
+ };
616
+ const excluded = new Set(
617
+ [...Object.keys(SHARED_EXIT_CODES), ...Object.keys(spec.exitCodes ?? {})].map(Number),
618
+ );
619
+ let input: JournalInput | undefined;
620
+ /** undefined: not dispatched; null: the verb threw; a number: its exit code. */
621
+ let outcome: number | null | undefined;
320
622
  try {
321
- ctx.flags = parseFlags(rest, spec.flags);
322
- return await spec.run(ctx);
623
+ const own = rest.filter((arg) => arg !== JSON_FLAG);
624
+ if (own.some((arg) => arg.startsWith(`${JSON_FLAG}=`))) {
625
+ throw new CommandError(EXIT.USAGE, `${JSON_FLAG} takes no value`);
626
+ }
627
+ ctx.json = own.length !== rest.length;
628
+ ctx.flags = parseFlags(own, spec.flags);
629
+ input = { noun: cmd.noun, verb, argv: rest, flags: ctx.flags, cwd: ctx.cwd };
630
+ const entered = input;
631
+ guarded(() => journal.call(entered));
632
+ outcome = null;
633
+ const code = await spec.run(ctx);
634
+ outcome = code;
635
+ return code;
323
636
  } catch (err) {
324
637
  if (!(err instanceof CommandError)) throw err;
325
638
  io.stderr(`${tag} ${err.message}\n`);
639
+ outcome = err.code;
326
640
  return err.code;
641
+ } finally {
642
+ if (input !== undefined && outcome !== undefined && shouldRecordFriction(outcome, excluded)) {
643
+ const failed = { ...input, code: outcome };
644
+ guarded(() => journal.failure(failed));
645
+ }
327
646
  }
328
647
  }
329
648
 
@@ -331,8 +650,8 @@ export async function runCommand(
331
650
  // Repo facts
332
651
  // ---------------------------------------------------------------------------
333
652
 
334
- /** Captured stdout / stderr cap for `runGit` / `runTool`; hook output (pre-push) counts. */
335
- const OUTPUT_LIMIT = 1 << 26;
653
+ /** Captured stdout / stderr cap for every git / gh spawn; hook output (pre-push) counts. */
654
+ export const OUTPUT_LIMIT = 1 << 26;
336
655
 
337
656
  /** Spawn error as a stderr lead line: ENOBUFS names the limit, anything else Node's message. */
338
657
  function spawnErrorText(cmd: string, args: string[], err: NodeJS.ErrnoException): string {
@@ -341,15 +660,16 @@ function spawnErrorText(cmd: string, args: string[], err: NodeJS.ErrnoException)
341
660
  : err.message;
342
661
  }
343
662
 
344
- /** `git <args>` in `cwd`, never throwing: exit status plus trimmed stdout / stderr. */
663
+ /** `git <args>` in `cwd`, never throwing: exit status plus trimmed stdout / stderr; `env` adds vars. */
345
664
  export function runGit(
346
665
  cwd: string,
347
666
  args: string[],
667
+ env: Record<string, string> = {},
348
668
  ): { ok: boolean; stdout: string; stderr: string } {
349
669
  const res = spawnSync("git", args, {
350
670
  cwd,
351
671
  encoding: "utf-8",
352
- env: gitEnv(),
672
+ env: { ...gitEnv(), ...env },
353
673
  maxBuffer: OUTPUT_LIMIT,
354
674
  });
355
675
  const stderr = (res.stderr ?? "").trim();
@@ -368,13 +688,23 @@ export function git(cwd: string, args: string[]): string | null {
368
688
  return res.ok ? res.stdout : null;
369
689
  }
370
690
 
691
+ /**
692
+ * True when git's ignore rules match `rel` in `cwd`. A tracked file reads as not
693
+ * ignored, so an ignored `rel` is always an untracked file git would refuse to
694
+ * `add` when a pathspec names it (the guard `:(exclude)` and `--pathspec-from-file`
695
+ * trip). Check before naming a path in an add pathspec.
696
+ */
697
+ export function isIgnoredPath(cwd: string, rel: string): boolean {
698
+ return runGit(cwd, ["check-ignore", "-q", "--", rel]).ok;
699
+ }
700
+
371
701
  /** `JSON.parse` as a result instead of a throw; each caller says what bad input means for it. */
372
702
  // Shared with the files that are not commands (checks, install): re-exported here
373
703
  // for the command modules that already import it from this module.
374
704
  export { parseJson } from "../shared/json.js";
375
705
 
376
706
  // The shared-branch rule (`dev`, `main`) lives in shared/ so checks can read it too.
377
- export { DEV, isSharedBranch } from "../shared/branches.js";
707
+ export { DEV, MAIN, isSharedBranch } from "../shared/branches.js";
378
708
 
379
709
  export interface ToolResult {
380
710
  /** False when the binary is not on PATH (or could not be spawned). */
@@ -393,12 +723,12 @@ export function runTool(
393
723
  cmd: string,
394
724
  args: string[],
395
725
  cwd: string,
396
- opts: { input?: string } = {},
726
+ opts: { input?: string; env?: Record<string, string> } = {},
397
727
  ): ToolResult {
398
728
  const res = spawnSync(cmd, args, {
399
729
  cwd,
400
730
  encoding: "utf-8",
401
- env: gitEnv(),
731
+ env: { ...gitEnv(), ...opts.env },
402
732
  input: opts.input,
403
733
  maxBuffer: OUTPUT_LIMIT,
404
734
  });
@@ -430,9 +760,14 @@ export interface GhResult {
430
760
  status?: number;
431
761
  }
432
762
 
433
- /** `gh <args>` in `cwd`, never throwing; `input` goes to stdin. */
434
- export function runGh(cwd: string, args: string[], input?: string): GhResult {
435
- const res = runTool("gh", args, cwd, { input });
763
+ /** `gh <args>` in `cwd`, never throwing; `input` goes to stdin; `env` is added to the child's. */
764
+ export function runGh(
765
+ cwd: string,
766
+ args: string[],
767
+ input?: string,
768
+ env?: Record<string, string>,
769
+ ): GhResult {
770
+ const res = runTool("gh", args, cwd, { input, env });
436
771
  return {
437
772
  ok: res.found && res.status === 0,
438
773
  stdout: res.stdout.trim(),
@@ -450,14 +785,38 @@ export function runGh(cwd: string, args: string[], input?: string): GhResult {
450
785
  export const ghUnavailable = (res: GhResult): boolean =>
451
786
  res.missing || res.status === 4 || (!res.ok && /\bHTTP 403\b/.test(res.stderr));
452
787
 
788
+ /**
789
+ * The main checkout's root from any worktree, or `null` when not inside a git repo.
790
+ * `--git-common-dir` points at the shared `.git`, so a linked worktree resolves to the
791
+ * same root as the main one.
792
+ */
793
+ export function mainCheckoutRoot(cwd: string): string | null {
794
+ const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
795
+ return common ? path.dirname(common) : null;
796
+ }
797
+
453
798
  /**
454
799
  * The main checkout's root, from any worktree. `--git-common-dir` points at the
455
800
  * shared `.git`, so a linked worktree resolves to the same root as the main one.
456
801
  */
457
802
  export function repoRoot(cwd: string): string {
803
+ const root = mainCheckoutRoot(cwd);
804
+ if (!root) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
805
+ return root;
806
+ }
807
+
808
+ /** `<git common dir>/bkit-outbox`: per-run scratch files, never committed; null outside a git repo. */
809
+ export function outboxRoot(cwd: string): string | null {
458
810
  const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
459
- if (!common) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
460
- return path.dirname(common);
811
+ return common ? path.join(common, "bkit-outbox") : null;
812
+ }
813
+
814
+ /** An outbox path as a committed record names it: relative to the main checkout, never a home path. */
815
+ export function outboxRel(cwd: string, file: string): string {
816
+ const root = outboxRoot(cwd);
817
+ if (root === null) return file;
818
+ const rel = path.relative(path.dirname(path.dirname(root)), file);
819
+ return rel.startsWith("..") || path.isAbsolute(rel) ? file : rel.split(path.sep).join("/");
461
820
  }
462
821
 
463
822
  /** `YYYYMM` in UTC, so every workflow picks the same month bucket at a month boundary. */
@@ -9,13 +9,17 @@ import { ciCommand } from "./ci/ci.js";
9
9
  import type { CommandSpec } from "./lib.js";
10
10
  import { setupCommand } from "./setup/setup.js";
11
11
  import { branchesCommand } from "./workflow/branches.js";
12
+ import { challengeCommand } from "./workflow/challenge.js";
13
+ import { completenessCommand } from "./workflow/completeness.js";
12
14
  import { contextCommand } from "./workflow/context.js";
13
15
  import { countersCommand } from "./workflow/counters.js";
16
+ import { decisionsCommand } from "./workflow/decisions.js";
14
17
  import { diskCommand } from "./workflow/disk.js";
15
18
  import { fidsCommand } from "./workflow/fids.js";
16
19
  import { issuesCommand } from "./workflow/issues.js";
17
20
  import { ledgersCommand } from "./workflow/ledgers.js";
18
21
  import { locksCommand } from "./workflow/locks.js";
22
+ import { plansCommand } from "./workflow/plans.js";
19
23
  import { prsCommand } from "./workflow/prs.js";
20
24
  import { repoCommand } from "./workflow/repo.js";
21
25
  import { roadmapCommand } from "./workflow/roadmap.js";
@@ -24,19 +28,22 @@ import { runtimeCommand } from "./workflow/runtime.js";
24
28
  import { skillsCommand } from "./workflow/skills.js";
25
29
  import { statusCommand } from "./workflow/status.js";
26
30
  import { stepsCommand } from "./workflow/steps.js";
31
+ import { tasksCommand } from "./workflow/tasks.js";
27
32
  import { testsCommand } from "./workflow/tests.js";
28
33
  import { workflowsCommand } from "./workflow/workflows.js";
29
- import { workstreamsCommand } from "./workflow/workstreams.js";
30
34
  import { worktreesCommand } from "./workflow/worktrees.js";
31
35
 
32
36
  export const COMMANDS: readonly CommandSpec[] = [
33
37
  statusCommand,
34
38
  countersCommand,
35
39
  stepsCommand,
40
+ tasksCommand,
36
41
  runtimeCommand,
37
42
  repoCommand,
38
43
  fidsCommand,
39
44
  testsCommand,
45
+ challengeCommand,
46
+ decisionsCommand,
40
47
  locksCommand,
41
48
  workflowsCommand,
42
49
  worktreesCommand,
@@ -49,7 +56,8 @@ export const COMMANDS: readonly CommandSpec[] = [
49
56
  ledgersCommand,
50
57
  contextCommand,
51
58
  roadmapCommand,
52
- workstreamsCommand,
59
+ plansCommand,
60
+ completenessCommand,
53
61
  ciCommand,
54
62
  setupCommand,
55
63
  ];
@@ -5,7 +5,7 @@
5
5
  // The policy also binds admins. `dev` is left unprotected — operators choose
6
6
  // direct-push or feat/PR.
7
7
  //
8
- // The required check is `bkit.capstoneJob`, the always-on job that asserts every
8
+ // The required check is `bkit.testing.ciCapstone`, the always-on job that asserts every
9
9
  // expected tier ran and passed, so "required check green" means validated, not
10
10
  // merely "the tests job did not fail". Before requiring it the command checks a
11
11
  // job by that name exists in the CI workflow: a required check no job produces
@@ -27,9 +27,9 @@ import {
27
27
 
28
28
  /** Exit code: `gh repo view` did not name the repository. */
29
29
  export const EXIT_NO_REPO = 3;
30
- /** Exit code: the CI workflow file named by `bkit.ciWorkflow` does not exist. */
30
+ /** Exit code: the CI workflow file named by `bkit.testing.ciWorkflow` does not exist. */
31
31
  export const EXIT_NO_CI_WORKFLOW = 4;
32
- /** Exit code: the CI workflow has no job named `bkit.capstoneJob`. */
32
+ /** Exit code: the CI workflow has no job named `bkit.testing.ciCapstone`. */
33
33
  export const EXIT_NO_CAPSTONE_JOB = 5;
34
34
  /** Exit code: a `gh api` call failed. */
35
35
  export const EXIT_GH_API_FAILED = 6;
@@ -149,6 +149,7 @@ export const setupCommand: CommandSpec = {
149
149
  verbs: {
150
150
  "protect-main": {
151
151
  summary: "Apply bkit's branch protection to main, requiring the capstone check.",
152
+ use: "by-hand",
152
153
  flags: [
153
154
  {
154
155
  name: "dry-run",
@@ -164,8 +165,8 @@ export const setupCommand: CommandSpec = {
164
165
  output: {
165
166
  repo: "owner/name the policy targets",
166
167
  branch: "always main",
167
- requiredCheck: "the required status check (bkit.capstoneJob)",
168
- ciWorkflow: "the CI workflow checked for that job (bkit.ciWorkflow)",
168
+ requiredCheck: "the required status check (bkit.testing.ciCapstone)",
169
+ ciWorkflow: "the CI workflow checked for that job (bkit.testing.ciWorkflow)",
169
170
  dryRun: "true with --dry-run",
170
171
  applied: "true when the policy was written to GitHub",
171
172
  payload: "the protection body sent (or that would be sent)",
@@ -174,8 +175,8 @@ export const setupCommand: CommandSpec = {
174
175
  },
175
176
  exitCodes: {
176
177
  [EXIT_NO_REPO]: "gh repo view could not name the repository",
177
- [EXIT_NO_CI_WORKFLOW]: "the CI workflow file (bkit.ciWorkflow) does not exist",
178
- [EXIT_NO_CAPSTONE_JOB]: "the CI workflow has no job named bkit.capstoneJob",
178
+ [EXIT_NO_CI_WORKFLOW]: "the CI workflow file (bkit.testing.ciWorkflow) does not exist",
179
+ [EXIT_NO_CAPSTONE_JOB]: "the CI workflow has no job named bkit.testing.ciCapstone",
179
180
  [EXIT_GH_API_FAILED]: "a gh api call failed",
180
181
  },
181
182
  run: protectMain,