@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
@@ -25,7 +25,15 @@ import * as fs from "node:fs";
25
25
  import * as path from "node:path";
26
26
 
27
27
  import { statusTimestamp } from "../../ledgers/status.js";
28
- import { CommandError, EXIT, repoRoot, runTool, type CommandSpec, type FlagSpec } from "../lib.js";
28
+ import {
29
+ CommandError,
30
+ EXIT,
31
+ git,
32
+ repoRoot,
33
+ runTool,
34
+ type CommandSpec,
35
+ type FlagSpec,
36
+ } from "../lib.js";
29
37
  import {
30
38
  EXIT_NO_STATUS,
31
39
  FILE_FLAG,
@@ -116,6 +124,19 @@ const capable = (runtime: Runtime) =>
116
124
  /** No human can reply into the session: a GitHub Actions run. */
117
125
  const headless = (runtime: unknown) => runtime === "GITHUB_ACTION";
118
126
 
127
+ /**
128
+ * `classify` for a process working in `cwd`, which may be a build worktree: the Cursor
129
+ * marker sits in the main checkout (`repoRoot`), as `runtime detect` reads it. Outside a
130
+ * git repo the marker is looked for under `cwd`.
131
+ */
132
+ export function classifyAt(cwd: string): Runtime {
133
+ const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
134
+ return classify(process.env, common ? path.dirname(common) : cwd, () => undefined);
135
+ }
136
+
137
+ /** Whether a process working in `cwd` runs headless, classified like `runtime detect`. */
138
+ export const headlessRun = (cwd: string): boolean => headless(classifyAt(cwd));
139
+
119
140
  /** The full table: classification, default capabilities, and the one live gh probe. */
120
141
  export function detect(cwd: string, root: string, log: (m: string) => void): RuntimeTable {
121
142
  const runtime = classify(process.env, root, log);
@@ -196,6 +217,7 @@ export const runtimeCommand: CommandSpec = {
196
217
  verbs: {
197
218
  detect: {
198
219
  summary: "Classify the runtime, its default capabilities, gh auth, and the worktree path.",
220
+ use: "by-hand",
199
221
  flags: [FID_FLAG],
200
222
  output: {
201
223
  ...TABLE_OUTPUT,
@@ -213,6 +235,7 @@ export const runtimeCommand: CommandSpec = {
213
235
  },
214
236
  row: {
215
237
  summary: "Detect, then build the runtime-resolved row (and append it with --file).",
238
+ use: "workflow",
216
239
  flags: [
217
240
  WORKFLOW_FLAG,
218
241
  {
@@ -253,6 +276,7 @@ export const runtimeCommand: CommandSpec = {
253
276
  },
254
277
  assert: {
255
278
  summary: "Read back the latest runtime-resolved row and fail unless every field is resolved.",
279
+ use: "workflow",
256
280
  flags: [
257
281
  FILE_FLAG,
258
282
  { ...WORKFLOW_FLAG, required: false, help: "only rows written by this workflow" },
@@ -56,6 +56,7 @@ export const skillsCommand: CommandSpec = {
56
56
  verbs: {
57
57
  prune: {
58
58
  summary: "Uninstall every non-bkit skill .agents/skills.md does not list (ship Step 7).",
59
+ use: "workflow",
59
60
  flags: [],
60
61
  output: {
61
62
  removed: "skills uninstalled",
@@ -1,15 +1,23 @@
1
- // bkit status route|meta|path|row — read and annotate a workflow's `status.jsonl`.
1
+ // bkit status route|resume|meta|path|row — read and annotate a workflow's `status.jsonl`.
2
2
 
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
 
6
+ import { BKIT_DEBUG_GATES } from "../../install/manifest.js";
7
+ import { appendFrictionRow, journalEnabled, pauseFrictionRow } from "../../ledgers/journal.js";
8
+ import { resolveGitSha } from "../../ledgers/telemetry.js";
9
+ import { readBkitConfig } from "../../shared/settings.js";
6
10
  import {
7
11
  activeDoneSteps,
12
+ validateCiSelection,
13
+ ciSelectionIdentity,
14
+ allRunsDoneSteps,
8
15
  appendLine,
9
16
  fold,
10
17
  lastDoneStepAllRuns,
11
18
  lastRun,
12
19
  nextStrategy,
20
+ runNumber,
13
21
  runOrStepField,
14
22
  statusTimestamp,
15
23
  type StatusEvent,
@@ -21,12 +29,14 @@ import {
21
29
  EXIT,
22
30
  git,
23
31
  parseJson,
32
+ resolveActiveRun,
24
33
  statusLocation,
25
34
  type CommandSpec,
26
35
  type FlagSpec,
27
36
  type FlagValue,
28
37
  type RunContext,
29
38
  } from "../lib.js";
39
+ import { WORKFLOW_STEPS, isResumable, resumePoint } from "./step-table.js";
30
40
 
31
41
  // ---------------------------------------------------------------------------
32
42
  // Shared with counters / steps
@@ -50,14 +60,16 @@ export const STEP_FLAG: FlagSpec = {
50
60
  required: true,
51
61
  help: "step name",
52
62
  };
53
- export const SUB_PLAN_FLAG: FlagSpec = {
54
- name: "sub-plan",
63
+ export const GROUP_FLAG: FlagSpec = {
64
+ name: "group",
55
65
  type: "string",
56
- help: "only rows for this sub-plan (positive integer)",
66
+ help: "only rows for this task group (positive integer)",
57
67
  };
58
68
 
59
69
  /** Exit code: status.jsonl missing, unreadable, or not valid NDJSON. */
60
70
  export const EXIT_NO_STATUS = 3;
71
+ /** Exit code: the owner-pause friction row was not written; the status row is kept. */
72
+ export const EXIT_PAUSE_FRICTION = 4;
61
73
 
62
74
  /** Every row of status.jsonl, whatever its type; exit 3 when the file is missing or a line is not JSON. */
63
75
  export function readStatusRows(file: string): StatusRow[] {
@@ -85,6 +97,15 @@ export function readStatusRowsAt(file: string, ref: string): StatusRow[] {
85
97
  return parseStatusRows(text, spec);
86
98
  }
87
99
 
100
+ /**
101
+ * Step names a row may carry from before a rename, read as the current name so a run
102
+ * in flight across the rename folds, resumes and counts as one (`docs/migrations.md`).
103
+ * The row on disk is history and is not rewritten.
104
+ */
105
+ const RENAMED_STEPS: Readonly<Record<string, string>> = {
106
+ "build-plan-execute": "build-plan-tasks",
107
+ };
108
+
88
109
  /** Parse NDJSON status text; `label` names it in errors. Malformed is an error, never "no rows". */
89
110
  function parseStatusRows(text: string, label: string): StatusRow[] {
90
111
  return text
@@ -97,7 +118,9 @@ function parseStatusRows(text: string, label: string): StatusRow[] {
97
118
  if (typeof parsed.value !== "object" || parsed.value === null) {
98
119
  throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not a JSON object`);
99
120
  }
100
- return parsed.value as StatusRow;
121
+ const row = parsed.value as StatusRow;
122
+ const renamed = typeof row.step === "string" ? RENAMED_STEPS[row.step] : undefined;
123
+ return renamed === undefined ? row : { ...row, step: renamed };
101
124
  });
102
125
  }
103
126
 
@@ -160,13 +183,20 @@ const DEBUG_MODES = ["NORMAL", "SOAK"];
160
183
  const PUSH_MODES = ["PR", "LOCAL"];
161
184
  const STRATEGIES = ["STANDARD", "PIVOT", "FINAL"];
162
185
 
163
- const ROUTE_FIELDS = ["verdict", "failures", "strategy", "debugMode", "pushMode"] as const;
186
+ const ROUTE_FIELDS = [
187
+ "verdict",
188
+ "failures",
189
+ "strategy",
190
+ "debugMode",
191
+ "pushMode",
192
+ "publish",
193
+ ] as const;
164
194
  type RouteField = (typeof ROUTE_FIELDS)[number];
165
195
 
166
196
  /** Exit code: a `--require`d field is missing or holds a value outside its set. */
167
197
  export const EXIT_ROUTE_MISSING = 4;
168
198
 
169
- function route(runs: WorkflowRun[], workflow: string, step: string | undefined, subPlan?: number) {
199
+ function route(runs: WorkflowRun[], workflow: string, step: string | undefined, group?: number) {
170
200
  const out: Record<string, unknown> = {
171
201
  verdict: null,
172
202
  failures: null,
@@ -174,12 +204,16 @@ function route(runs: WorkflowRun[], workflow: string, step: string | undefined,
174
204
  nextStrategy: null,
175
205
  debugMode: null,
176
206
  pushMode: null,
207
+ publish: null,
208
+ publishSource: null,
177
209
  debugAttempt: 0,
210
+ parentSha: null,
178
211
  };
179
212
  const problems: Partial<Record<RouteField, string>> = {};
180
213
 
181
214
  if (step !== undefined) {
182
- const last = activeDoneSteps(runs, workflow, { step, subPlan }).at(-1);
215
+ const last = activeDoneSteps(runs, workflow, { step, group }).at(-1);
216
+ if (typeof last?.parentSha === "string") out.parentSha = last.parentSha;
183
217
  if (!last) {
184
218
  problems.verdict = `no DONE ${step} row in the active ${workflow} run`;
185
219
  problems.failures = problems.verdict;
@@ -188,13 +222,15 @@ function route(runs: WorkflowRun[], workflow: string, step: string | undefined,
188
222
  problems.failures = problems.verdict;
189
223
  } else {
190
224
  out.verdict = last.verdict;
191
- const failures = last.failures ?? 0;
192
- if (Number.isInteger(failures) && failures >= 0) out.failures = failures;
225
+ // An absent count on FAIL is unknown, never 0: a FAIL always has failures.
226
+ const failures = last.failures ?? (last.verdict === "FAIL" ? null : 0);
227
+ if (failures === null) out.failures = null;
228
+ else if (Number.isInteger(failures) && failures >= 0) out.failures = failures;
193
229
  else
194
230
  problems.failures = `${step} failures "${String(failures)}" is not a non-negative integer`;
195
231
  }
196
232
 
197
- const prior = lastDoneStepAllRuns(runs, workflow, { step, subPlan })?.strategy;
233
+ const prior = lastDoneStepAllRuns(runs, workflow, { step, group })?.strategy;
198
234
  if (prior === undefined || STRATEGIES.includes(prior)) {
199
235
  out.strategy = prior ?? null;
200
236
  out.nextStrategy = nextStrategy(prior);
@@ -214,11 +250,105 @@ function route(runs: WorkflowRun[], workflow: string, step: string | undefined,
214
250
  value === "" ? `${field} not recorded` : `${field} "${value}" is not ${allowed.join("|")}`;
215
251
  }
216
252
 
253
+ problems.publish = "publish not resolved: needs --workflow=build with --prompt-file";
254
+
217
255
  const attempt = Number(lastRun(runs, workflow)?.debugAttempt ?? 0);
218
256
  out.debugAttempt = Number.isFinite(attempt) ? attempt : 0;
219
257
  return { out, problems };
220
258
  }
221
259
 
260
+ /**
261
+ * The debug run's start decisions, from the session prompt and the feature's debug runs.
262
+ * `fixMax` is `bkit.workflows.debug.fix.maxAttempts`: once that many fix rounds ran across
263
+ * every debug run, the run starts in SOAK.
264
+ */
265
+ export function debugStart(runs: WorkflowRun[], promptText: string, fixMax: number) {
266
+ const attempt = runNumber(runs, "debug");
267
+ const latest = runs.at(-1);
268
+ // A resume: the newest run is debug's and still open. A finished run's modes never
269
+ // carry into the next run; its fix rounds count against `fixMax`.
270
+ const open = latest?.workflow === "debug" && latest.status === "IN_PROGRESS" ? latest : null;
271
+ const soaking =
272
+ open !== null &&
273
+ (runOrStepField([open], "debug", "debugMode") === "SOAK" ||
274
+ open.steps.some((s) => s.step === "debug-failure-soak" && s.status === "DONE"));
275
+ const fixes = allRunsDoneSteps(runs, "debug", { step: "debug-failure-remediate" }).length;
276
+ const debugMode = promptText.includes("[soak]") || soaking || fixes >= fixMax ? "SOAK" : "NORMAL";
277
+ const selection =
278
+ !promptText.includes("[local]") && validateCiSelection(open?.ciSelection)
279
+ ? open.ciSelection
280
+ : null;
281
+ const ci = selection?.mode === "ci" ? selection : null;
282
+ const ciGeneration = typeof open?.ciGeneration === "number" ? open.ciGeneration : 0;
283
+ const current =
284
+ open?.steps.filter((s) => s.status === "DONE" && s.ciGeneration === ciGeneration) ?? [];
285
+ const defaults = promptText.includes("[live=off]")
286
+ ? BKIT_DEBUG_GATES.filter((g) => !g.endsWith("-live"))
287
+ : [...BKIT_DEBUG_GATES];
288
+ const covering =
289
+ ci && ci.redTiers.length > 0
290
+ ? defaults
291
+ .filter((g) =>
292
+ ci.redTiers.every((tier) => g.slice("bkit:gate:".length).split("-").includes(tier)),
293
+ )
294
+ .reverse()
295
+ : [];
296
+ return {
297
+ debugAttempt: attempt,
298
+ debugMode,
299
+ repro: promptText.includes("[repro]"),
300
+ gates: [...new Set([...covering, ...defaults])],
301
+ ciRun: ci?.runId ?? null,
302
+ ciGeneration,
303
+ redTiers: ci?.redTiers ?? [],
304
+ ciFixDone:
305
+ ci !== null &&
306
+ current.some((s) => ["debug-failure-remediate", "debug-failure-soak"].includes(s.step)),
307
+ ciReproduced:
308
+ ci !== null &&
309
+ current.some((s) => s.step === "debug-failure-reproduce" && s.reproduced === "YES"),
310
+ };
311
+ }
312
+
313
+ const PUBLISH_TOKEN = /(?<![\w-])publish=(true|false)(?![\w-])/;
314
+
315
+ /**
316
+ * Build's ending, from the session prompt, `bkit.workflows.build.publish` and the runtime.
317
+ * A `publish=true|false` token wins; else LOCAL reads `publish.local` and any other runtime
318
+ * `publish.remote`. A non-LOCAL `false` resolves `true`. No `runtime-resolved` row throws.
319
+ */
320
+ export function publishRoute(
321
+ rows: StatusRow[],
322
+ promptText: string,
323
+ config: { remote: boolean; local: boolean },
324
+ ): { publish: boolean; publishSource: "token" | "local" | "remote" | "coerced" } {
325
+ const row = rows.filter((r) => r.type === "runtime-resolved" && r.workflow === "build").at(-1);
326
+ if (row === undefined)
327
+ throw new CommandError(
328
+ EXIT_ROUTE_MISSING,
329
+ "no runtime-resolved row for build: Step 2 never recorded the runtime",
330
+ );
331
+ const local = row.runtime === "LOCAL";
332
+ const token = PUBLISH_TOKEN.exec(promptText)?.[1];
333
+ const wanted = token !== undefined ? token === "true" : local ? config.local : config.remote;
334
+ if (!local && !wanted) return { publish: true, publishSource: "coerced" };
335
+ return {
336
+ publish: wanted,
337
+ publishSource: token !== undefined ? "token" : local ? "local" : "remote",
338
+ };
339
+ }
340
+
341
+ /** `--file`, else the debug status.jsonl `--fid` and `--month` name. */
342
+ function routeFile(ctx: RunContext): string {
343
+ if (ctx.flags.file !== undefined) return statusFile(ctx);
344
+ const fid = str(ctx.flags.fid);
345
+ const month = str(ctx.flags.month);
346
+ if (fid === undefined || month === undefined || ctx.flags.promptFile === undefined)
347
+ throw new CommandError(EXIT.USAGE, "give --file, or --prompt-file with --fid and --month");
348
+ if (!/^[0-9]{6}$/.test(month)) throw new CommandError(EXIT.USAGE, "--month must be YYYYMM");
349
+ return statusLocation({ cwd: ctx.cwd, workflow: "debug", fid, month }).path;
350
+ }
351
+
222
352
  // ---------------------------------------------------------------------------
223
353
  // meta
224
354
  // ---------------------------------------------------------------------------
@@ -227,7 +357,6 @@ const META_FIELDS: Record<string, { key: string; check: (v: string) => unknown }
227
357
  "debug-mode": { key: "debugMode", check: (v) => oneOf(v, DEBUG_MODES, "--debug-mode") },
228
358
  "push-mode": { key: "pushMode", check: (v) => oneOf(v, PUSH_MODES, "--push-mode") },
229
359
  "debug-attempt": { key: "debugAttempt", check: (v) => positiveInt(v, "debug-attempt") },
230
- "plan-source": { key: "planSource", check: (v) => oneOf(v, PLAN_SOURCES, "--plan-source") },
231
360
  };
232
361
 
233
362
  /** Row types the fold reads; each has its own verb (workflows start|fail|close, steps done, status meta). */
@@ -239,15 +368,11 @@ const FOLDED_TYPES = new Set([
239
368
  "workflow-failed",
240
369
  ]);
241
370
 
242
- /** Markers that record the row's own time or a fact, not a value. */
371
+ /** Markers that record a fact, not a value. */
243
372
  const META_MARKS: Record<string, (at: string) => Record<string, unknown>> = {
244
- "soak-entry": (at) => ({ soakEntryAt: at }),
245
373
  "opened-pr": () => ({ openedPr: true }),
246
374
  };
247
375
 
248
- /** `brief` = the run had no plan file and works from its input file. */
249
- const PLAN_SOURCES = ["brief", "plan"];
250
-
251
376
  const camelFlag = (kebab: string) => kebab.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
252
377
 
253
378
  function oneOf(v: string, allowed: string[], flag: string): string {
@@ -266,6 +391,7 @@ export const statusCommand: CommandSpec = {
266
391
  verbs: {
267
392
  path: {
268
393
  summary: "Where this workflow's status.jsonl lives.",
394
+ use: "by-hand",
269
395
  flags: [
270
396
  WORKFLOW_FLAG,
271
397
  { name: "fid", type: "string", required: true, help: "feature id" },
@@ -290,16 +416,18 @@ export const statusCommand: CommandSpec = {
290
416
  },
291
417
  },
292
418
  route: {
293
- summary: "Routing state: last verdict / failures / strategy of a step, debug and push mode.",
419
+ summary:
420
+ "Routing state: last verdict / failures / strategy of a step, debug and push mode; with --prompt-file, debug's start decisions.",
421
+ use: "workflow",
294
422
  flags: [
295
- FILE_FLAG,
423
+ { ...FILE_FLAG, required: false, help: `${FILE_FLAG.help}; or --fid and --month` },
296
424
  WORKFLOW_FLAG,
297
425
  {
298
426
  ...STEP_FLAG,
299
427
  required: false,
300
428
  help: "step whose last DONE row gives verdict, failures, strategy",
301
429
  },
302
- SUB_PLAN_FLAG,
430
+ GROUP_FLAG,
303
431
  {
304
432
  name: "require",
305
433
  type: "string",
@@ -312,15 +440,40 @@ export const statusCommand: CommandSpec = {
312
440
  repeatable: true,
313
441
  help: "field=value — fail (exit 4) unless the field holds this value, e.g. debugMode=NORMAL",
314
442
  },
443
+ {
444
+ name: "prompt-file",
445
+ type: "string",
446
+ help: "debug or build: the session prompt; debug: this run's attempt, mode, repro and gates (a missing status.jsonl is a fresh run); build: publish and publishSource",
447
+ },
448
+ { name: "fid", type: "string", help: "with --prompt-file, in place of --file: feature id" },
449
+ { name: "month", type: "string", help: "with --prompt-file, in place of --file: YYYYMM" },
315
450
  ],
316
451
  output: {
317
452
  verdict: "PASS|CONCERNS|FAIL of the step's last DONE row in the active run, or null",
318
- failures: "its failures (absent with a verdict = 0), or null",
453
+ ciRun: "active saved CI run ID with --prompt-file, or null; explicit [local] clears it",
454
+ ciGeneration: "active saved selection generation with --prompt-file, or 0",
455
+ redTiers:
456
+ "active selected failed tiers with --prompt-file; empty for local or unknown jobs",
457
+ ciFixDone: "whether the active generation has a DONE remediation or soak",
458
+ ciReproduced: "whether the active generation has DONE reproduction with YES",
459
+ failures:
460
+ "its failures (absent on PASS|CONCERNS = 0, absent on FAIL = null: count unknown), or null",
319
461
  strategy: "the step's last strategy across ALL runs, or null",
320
462
  nextStrategy: "next rung: STANDARD, PIVOT, FINAL (null without --step)",
321
- debugMode: "NORMAL|SOAK of the active run, or null",
463
+ debugMode:
464
+ "NORMAL|SOAK of the active run, or null; with --prompt-file, the mode this invocation runs in (SOAK on [soak] in the prompt, an open run already in SOAK, or bkit.workflows.debug.fix.maxAttempts fix rounds already run across every debug run; else NORMAL)",
322
465
  pushMode: "PR|LOCAL of the active run, or null",
323
- debugAttempt: "debugAttempt of the active run (0 when unset)",
466
+ debugAttempt:
467
+ "debugAttempt of the active run (0 when unset); with --prompt-file, this invocation's run number (a resume keeps its number)",
468
+ repro: "with --prompt-file: [repro] in the prompt",
469
+ gates:
470
+ "with --prompt-file: the gates to try, deepest first; [live=off] in the prompt drops the live gate",
471
+ publish:
472
+ "with --workflow=build and --prompt-file: whether the build publishes (a publish=true|false token, else publish.local on LOCAL or publish.remote elsewhere; a non-LOCAL false resolves true), else null",
473
+ publishSource:
474
+ "with publish: token | local | remote | coerced (a non-LOCAL false forced to true), else null",
475
+ parentSha:
476
+ "HEAD when the step's last DONE row in the active run was written — a build-group-start row's is the group's start commit, the base for `context diff` — or null",
324
477
  },
325
478
  exitCodes: {
326
479
  [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON",
@@ -355,13 +508,36 @@ export const statusCommand: CommandSpec = {
355
508
  throw new CommandError(EXIT.USAGE, `--require ${r} needs --step`);
356
509
  }
357
510
  }
358
- const runs = readRuns(statusFile(ctx));
511
+ const promptFile = str(ctx.flags.promptFile);
512
+ if (promptFile !== undefined && !["debug", "build"].includes(String(ctx.flags.workflow)))
513
+ throw new CommandError(EXIT.USAGE, "--prompt-file is for --workflow=debug or build");
514
+ const file = routeFile(ctx);
515
+ let promptText = "";
516
+ if (promptFile !== undefined) {
517
+ const abs = path.resolve(ctx.cwd, promptFile);
518
+ if (!fs.existsSync(abs))
519
+ throw new CommandError(EXIT.USAGE, `--prompt-file ${abs} does not exist`);
520
+ promptText = fs.readFileSync(abs, "utf-8");
521
+ }
522
+ const runs = promptFile !== undefined && !fs.existsSync(file) ? [] : readRuns(file);
359
523
  const { out, problems } = route(
360
524
  runs,
361
525
  String(ctx.flags.workflow),
362
526
  step,
363
- positiveInt(ctx.flags.subPlan, "sub-plan"),
527
+ positiveInt(ctx.flags.group, "group"),
364
528
  );
529
+ if (promptFile !== undefined) {
530
+ const root = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
531
+ const config = readBkitConfig(root);
532
+ if (ctx.flags.workflow === "debug") {
533
+ Object.assign(out, debugStart(runs, promptText, config.asks["debug.fix"].max));
534
+ delete problems.debugMode;
535
+ } else {
536
+ const rows = fs.existsSync(file) ? readStatusRows(file) : [];
537
+ Object.assign(out, publishRoute(rows, promptText, config.buildPublish));
538
+ delete problems.publish;
539
+ }
540
+ }
365
541
  ctx.emit(out);
366
542
  const failed = required.filter((r) => problems[r as RouteField] !== undefined);
367
543
  for (const r of failed) ctx.log(problems[r as RouteField]!);
@@ -375,21 +551,62 @@ export const statusCommand: CommandSpec = {
375
551
  return failed.length === 0 && differ.length === 0 ? EXIT.OK : EXIT_ROUTE_MISSING;
376
552
  },
377
553
  },
554
+ resume: {
555
+ summary:
556
+ "The step a stopped run continues at: after its last DONE step, setup steps and retired rows aside.",
557
+ use: "by-hand",
558
+ flags: [
559
+ { ...FILE_FLAG, help: "path to status.jsonl; a missing file is a run with no rows" },
560
+ { ...WORKFLOW_FLAG, help: `workflow name: ${Object.keys(WORKFLOW_STEPS).join(", ")}` },
561
+ ],
562
+ output: {
563
+ step: "the step's row name, or null for a step that writes no row",
564
+ number: "the step number to continue at (1 when no run is active)",
565
+ title: "the step heading's title",
566
+ after: "the DONE row that placed it, or null",
567
+ group: "that row's task group, or null",
568
+ active: "whether the latest run is this workflow, still IN_PROGRESS",
569
+ challengeRound:
570
+ "build: the round Step 11's challenge runs as (1 up to bkit.workflows.build.challenge.maxAttempts), from the build-challenge rows' round field; null for other workflows",
571
+ challengeDone:
572
+ "build: true once the last allowed challenge round has merged, so Step 11 goes on to Step 12; null for other workflows",
573
+ },
574
+ exitCodes: { [EXIT_NO_STATUS]: "status.jsonl unreadable or not valid NDJSON" },
575
+ run: (ctx) => {
576
+ const workflow = String(ctx.flags.workflow);
577
+ if (!isResumable(workflow))
578
+ throw new CommandError(
579
+ EXIT.USAGE,
580
+ `--workflow must be ${Object.keys(WORKFLOW_STEPS).join("|")}, got "${workflow}"`,
581
+ );
582
+ const file = statusFile(ctx);
583
+ const root = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
584
+ const challengeMax = readBkitConfig(root).asks["build.challenge"].max;
585
+ ctx.emit({
586
+ ...resumePoint(fs.existsSync(file) ? readRuns(file) : [], workflow, challengeMax),
587
+ });
588
+ return EXIT.OK;
589
+ },
590
+ },
378
591
  meta: {
379
592
  summary: "Append a workflow-meta row (run-level routing state).",
593
+ use: "workflow",
380
594
  flags: [
381
595
  FILE_FLAG,
382
596
  WORKFLOW_FLAG,
383
597
  { name: "debug-mode", type: "string", help: "NORMAL|SOAK" },
384
598
  { name: "push-mode", type: "string", help: "PR|LOCAL" },
385
- { name: "debug-attempt", type: "string", help: "positive integer" },
386
- { name: "plan-source", type: "string", help: "brief|plan" },
387
599
  {
388
- name: "soak-entry",
389
- type: "boolean",
390
- help: "record soakEntryAt (the soak budget counts from here)",
600
+ name: "debug-attempt",
601
+ type: "string",
602
+ help: "positive integer, or run (the active run's number)",
391
603
  },
392
604
  { name: "opened-pr", type: "boolean", help: "record openedPr: this run opened the PR" },
605
+ {
606
+ name: "ci-selection-file",
607
+ type: "string",
608
+ help: "validated atomic debug CI or local selection JSON",
609
+ },
393
610
  ],
394
611
  output: { row: "the appended workflow-meta row" },
395
612
  exitCodes: { [EXIT_NO_STATUS]: "status.jsonl does not exist (meta never starts a log)" },
@@ -397,9 +614,31 @@ export const statusCommand: CommandSpec = {
397
614
  const file = statusFile(ctx);
398
615
  const at = statusTimestamp();
399
616
  const fields: Record<string, unknown> = {};
617
+ if (ctx.flags.ciSelectionFile !== undefined) {
618
+ const parsed = parseJson(
619
+ fs.readFileSync(path.resolve(ctx.cwd, String(ctx.flags.ciSelectionFile)), "utf-8"),
620
+ );
621
+ const selection = parsed.ok ? parsed.value : null;
622
+ if (!validateCiSelection(selection))
623
+ throw new CommandError(EXIT.USAGE, "invalid CI selection");
624
+ const active = readRuns(file).at(-1);
625
+ if (
626
+ ctx.flags.workflow !== "debug" ||
627
+ active?.workflow !== "debug" ||
628
+ active.status !== "IN_PROGRESS"
629
+ )
630
+ throw new CommandError(EXIT.USAGE, "CI selection needs an active debug run");
631
+ const same =
632
+ validateCiSelection(active.ciSelection) &&
633
+ ciSelectionIdentity(active.ciSelection) === ciSelectionIdentity(selection);
634
+ fields.ciSelection =
635
+ selection.mode === "local" ? { mode: "local", reason: selection.reason } : selection;
636
+ fields.ciGeneration = (Number(active.ciGeneration) || 0) + (same ? 0 : 1);
637
+ }
400
638
  for (const { key, check } of Object.values(META_FIELDS)) {
401
639
  const v = str(ctx.flags[key]);
402
- if (v !== undefined) fields[key] = check(v);
640
+ // `--debug-attempt=run`: the active run's number, read once the log is known to exist.
641
+ if (v !== undefined) fields[key] = key === "debugAttempt" && v === "run" ? v : check(v);
403
642
  }
404
643
  for (const [flag, mark] of Object.entries(META_MARKS)) {
405
644
  if (ctx.flags[camelFlag(flag)] === true) Object.assign(fields, mark(at));
@@ -413,6 +652,9 @@ export const statusCommand: CommandSpec = {
413
652
  );
414
653
  }
415
654
  if (!fs.existsSync(file)) throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
655
+ if (fields.debugAttempt === "run") {
656
+ fields.debugAttempt = runNumber(readRuns(file), String(ctx.flags.workflow));
657
+ }
416
658
  const row = {
417
659
  type: "workflow-meta" as const,
418
660
  workflow: String(ctx.flags.workflow),
@@ -426,7 +668,8 @@ export const statusCommand: CommandSpec = {
426
668
  },
427
669
  row: {
428
670
  summary:
429
- "Append a typed audit row the fold does not model (ship's gate refusals, CI probes, merge CI).",
671
+ "Append a typed audit row the fold does not model (ship's gate refusals, CI probes, merge CI); an owner-pause row also logs a human-confirm friction row.",
672
+ use: "workflow",
430
673
  flags: [
431
674
  FILE_FLAG,
432
675
  WORKFLOW_FLAG,
@@ -444,7 +687,11 @@ export const statusCommand: CommandSpec = {
444
687
  },
445
688
  ],
446
689
  output: { row: "the appended row" },
447
- exitCodes: { [EXIT_NO_STATUS]: "status.jsonl does not exist (a row never starts a log)" },
690
+ exitCodes: {
691
+ [EXIT_NO_STATUS]: "status.jsonl does not exist (a row never starts a log)",
692
+ [EXIT_PAUSE_FRICTION]:
693
+ "an owner-pause row was appended but its human-confirm friction row was not written",
694
+ },
448
695
  run: (ctx) => {
449
696
  const type = String(ctx.flags.type);
450
697
  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(type))
@@ -468,10 +715,59 @@ export const statusCommand: CommandSpec = {
468
715
  at: statusTimestamp(),
469
716
  ...fields,
470
717
  };
718
+ const prior = type === "owner-pause" ? fs.readFileSync(file, "utf-8") : "";
471
719
  fs.appendFileSync(file, appendLine(row));
720
+ if (type === "owner-pause") recordPause(ctx.cwd, file, row, prior);
472
721
  ctx.emit({ row });
473
722
  return EXIT.OK;
474
723
  },
475
724
  },
476
725
  },
477
726
  };
727
+
728
+ const pauseReason = (row: Record<string, unknown>) =>
729
+ row["reason"] === undefined ? undefined : String(row["reason"]);
730
+
731
+ /**
732
+ * Log an owner pause as `human-confirm` friction in the active run's books. A
733
+ * follow-up wait writes nothing: `prior` (the status file before this row) holds an
734
+ * `owner-pause` row with the same workflow and reason and no `step-done` row after it.
735
+ * Nothing is written outside an active run or with `BKIT_ENGINE_JOURNAL=off`.
736
+ */
737
+ function recordPause(
738
+ cwd: string,
739
+ file: string,
740
+ row: StatusRow & { workflow: string },
741
+ prior: string,
742
+ ) {
743
+ if (!journalEnabled()) return;
744
+ const reason = pauseReason(row);
745
+ let waiting = false;
746
+ for (const line of prior.split("\n")) {
747
+ const parsed = parseJson(line);
748
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") continue;
749
+ const r = parsed.value as Record<string, unknown>;
750
+ if (r["type"] === "step-done") waiting = false;
751
+ else if (r["type"] === "owner-pause" && r["workflow"] === row.workflow) {
752
+ waiting ||= pauseReason(r) === reason;
753
+ }
754
+ }
755
+ if (waiting) return;
756
+ const run = resolveActiveRun({ cwd, file });
757
+ if (run === undefined) return;
758
+ const wrote = appendFrictionRow(
759
+ run.bookRoot,
760
+ pauseFrictionRow({
761
+ workflow: row.workflow,
762
+ reason,
763
+ bookRoot: run.bookRoot,
764
+ parentSha: resolveGitSha("HEAD", run.bookRoot),
765
+ }),
766
+ );
767
+ if (!wrote.ok) {
768
+ throw new CommandError(
769
+ EXIT_PAUSE_FRICTION,
770
+ `owner-pause row kept; its friction row was not written: ${wrote.error}`,
771
+ );
772
+ }
773
+ }