@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,6 +1,7 @@
1
- // bkit ledgers commit|union|only-bookkeeping|append|check — stage and commit bookkeeping
2
- // by an allow-list, never `git add -A`; append validated rows with a minted `ts`;
3
- // check that the ledger rows a plan names are on disk.
1
+ // bkit ledgers commit|union|only-bookkeeping|append|check|triage|compact — stage and
2
+ // commit bookkeeping by an allow-list, never `git add -A`; append validated rows with
3
+ // a minted `ts`; check that the ledger rows a plan names are on disk; drop superseded
4
+ // rows from the keyed ledgers.
4
5
  //
5
6
  // The pathspec is built by `git ls-files` against quoted globs, so git does the
6
7
  // matching and an unmatched glob is empty output, never a shell abort. Staging
@@ -14,20 +15,25 @@ import * as os from "node:os";
14
15
  import * as path from "node:path";
15
16
 
16
17
  import { readBkitVersion } from "../../install/version-file.js";
18
+ import { readBkitConfig } from "../../shared/settings.js";
17
19
  import {
18
20
  APPEND_LEDGERS,
19
21
  SCHEMA,
22
+ UNJUSTIFIED_REASON,
20
23
  gitEnv,
21
24
  parse,
22
25
  mintTs,
23
26
  resolveRepoSlug,
24
27
  validate,
28
+ withLineage,
25
29
  writerProblem,
26
30
  type AppendLedger,
27
31
  } from "../../ledgers/telemetry.js";
32
+ import { COMPACT_LEDGERS, compactLedgers, type CompactLedger } from "../../ledgers/compact.js";
28
33
  import {
29
34
  CommandError,
30
35
  EXIT,
36
+ isIgnoredPath,
31
37
  isSharedBranch,
32
38
  parseJson,
33
39
  type CommandSpec,
@@ -35,6 +41,13 @@ import {
35
41
  type RunContext,
36
42
  } from "../lib.js";
37
43
  import { str } from "./status.js";
44
+ import {
45
+ NO_MARKERS_REASON,
46
+ outOfScope,
47
+ parsePlanBlocks,
48
+ reuseInventory,
49
+ type OutOfScopeRow,
50
+ } from "./plan-blocks.js";
38
51
 
39
52
  /** Root is not a directory or repo, git is too old, or a ref does not resolve. */
40
53
  export const EXIT_ROOT = 3;
@@ -53,11 +66,23 @@ const SCOPES = ["core", "full", "pr"] as const;
53
66
  export type Scope = (typeof SCOPES)[number];
54
67
  const MODES = ["stage", "commit", "commit-allow-empty"];
55
68
 
69
+ /** `package.json` globs as git pathspecs: `:(glob)` unless an entry carries its own magic. */
70
+ export const globPathspecs = (paths: readonly string[]): string[] =>
71
+ paths.map((p) => (p.startsWith(":") ? p : `:(glob)${p}`));
72
+
56
73
  /**
57
74
  * The bookkeeping allow-list. Plain git pathspec `*` crosses `/`, so the
58
- * top-level-only entry uses the `:(glob)` magic.
75
+ * top-level-only entries use the `:(glob)` magic. `extra` is
76
+ * `bkit.testing.ciSkipPaths` (`ciSkipPaths`), the project docs a repo
77
+ * keeps outside `docs/*.md` (bkit's own: `CHANGELOG.md`, `README.md`); it reaches
78
+ * the `pr` scope only.
59
79
  */
60
- export function bookPathspecs(month: string, fid: string, scope: Scope): string[] {
80
+ export function bookPathspecs(
81
+ month: string,
82
+ fid: string,
83
+ scope: Scope,
84
+ extra: readonly string[] = [],
85
+ ): string[] {
61
86
  const specs = [
62
87
  `docs/plans/${month}/logs/${fid}/*`,
63
88
  ".bkit/friction.jsonl",
@@ -81,10 +106,14 @@ export function bookPathspecs(month: string, fid: string, scope: Scope): string[
81
106
  ".opencode/skills/*",
82
107
  );
83
108
  }
84
- // `pr` adds the project docs ship's docs sync edits, for the commit that rides
85
- // the PR. Kept out of `full` so a close on a laptop's dev checkout never sweeps
86
- // unrelated dirty docs into its commit.
87
- if (scope === "pr") specs.push(":(glob)docs/*.md");
109
+ // `pr` adds the project docs ship's docs sync edits, for the commit that rides the
110
+ // PR: top-level `docs/*.md`, plus whatever the repo names in `ciSkipPaths` (the
111
+ // engine hardcodes no file name; a glob nothing matches selects nothing). Kept out
112
+ // of `full` so a close on a laptop's dev checkout never sweeps unrelated dirty docs
113
+ // into its commit.
114
+ if (scope === "pr") {
115
+ specs.push(":(glob)docs/*.md", ...globPathspecs(extra));
116
+ }
88
117
  return specs;
89
118
  }
90
119
 
@@ -536,6 +565,13 @@ export function commitOwnSet(
536
565
  try {
537
566
  const list = path.join(tmp, "list");
538
567
  const all = [...set.plain, ...set.ledgers.map((l) => l.path)];
568
+ // `dirtyPaths` drops ignored entries, so `all` never holds one today; name the
569
+ // failure if a future caller passes a gitignored path, rather than let git's
570
+ // ignored-paths guard surface as an opaque stage error.
571
+ const ignored = all.filter((p) => isIgnoredPath(top, p));
572
+ if (ignored.length > 0) {
573
+ return { ok: false, error: `refusing to stage gitignored path(s): ${ignored.join(", ")}` };
574
+ }
539
575
  fs.writeFileSync(list, all.map((p) => `${p}\0`).join(""));
540
576
  const stagedBefore = new Set(
541
577
  nulList(gitRaw(top, ["diff", "--cached", "--name-only", "-z"]).stdout),
@@ -653,10 +689,11 @@ export function retriggerCommit(
653
689
  export const ledgersCommand: CommandSpec = {
654
690
  noun: "ledgers",
655
691
  summary:
656
- "Stage and commit bookkeeping by allow-list; union ledgers; check a range is bookkeeping only.",
692
+ "Stage and commit bookkeeping by allow-list; union ledgers; check a range is bookkeeping only; compact keyed ledgers.",
657
693
  verbs: {
658
694
  commit: {
659
695
  summary: "Stage (and commit) the bookkeeping allow-list for one feature.",
696
+ use: "workflow",
660
697
  flags: [
661
698
  ROOT_FLAG,
662
699
  MONTH_FLAG,
@@ -719,6 +756,7 @@ export const ledgersCommand: CommandSpec = {
719
756
  union: {
720
757
  summary:
721
758
  "Append a worktree's new ledger rows into another checkout (never .bkit/issues.jsonl).",
759
+ use: "workflow",
722
760
  flags: [
723
761
  { name: "src", type: "string", required: true, help: "worktree to read ledgers from" },
724
762
  { name: "dst", type: "string", required: true, help: "checkout to append them to" },
@@ -732,6 +770,7 @@ export const ledgersCommand: CommandSpec = {
732
770
  },
733
771
  "only-bookkeeping": {
734
772
  summary: "Exit 0 when every path changed in from..to is on the --scope=pr allow-list.",
773
+ use: "by-hand",
735
774
  flags: [
736
775
  ROOT_FLAG,
737
776
  MONTH_FLAG,
@@ -752,6 +791,7 @@ export const ledgersCommand: CommandSpec = {
752
791
  },
753
792
  append: {
754
793
  summary: "Append validated rows to one ledger, minting each row's ts at append time.",
794
+ use: "by-hand",
755
795
  flags: [
756
796
  { name: "root", type: "string", help: "checkout whose ledger to append to (default: cwd)" },
757
797
  {
@@ -780,9 +820,37 @@ export const ledgersCommand: CommandSpec = {
780
820
  },
781
821
  run: (ctx) => append(ctx),
782
822
  },
823
+ triage: {
824
+ summary:
825
+ "Bucket each deferral row the FID declared by the four Deferral Reason tests, and write the unjustified ones.",
826
+ use: "workflow",
827
+ flags: [
828
+ { name: "root", type: "string", help: "checkout whose deferrals to read (default: cwd)" },
829
+ FID_FLAG,
830
+ {
831
+ name: "plan",
832
+ type: "string",
833
+ required: true,
834
+ help: "plan file whose task surfaces and Out of Scope rows the four tests read",
835
+ },
836
+ ],
837
+ output: {
838
+ fid: "the feature id triaged",
839
+ plan: "the plan the tests were read from",
840
+ rows: "each matched deferral's key, bucket (Exempt | Lazy), test results (none for a settled row: closed, LOW, or already adjudicated) and whether a row was written",
841
+ total: "deferral rows the FID matched",
842
+ written: "unjustified rows appended",
843
+ },
844
+ exitCodes: {
845
+ [EXIT_ROW_REFUSED]:
846
+ "a computed unjustified row fails validation or its writer check — nothing written",
847
+ },
848
+ run: (ctx) => triage(ctx),
849
+ },
783
850
  check: {
784
851
  summary:
785
852
  "Check that every decision / deferral key on a plan's `**Ledger rows:**` line is on disk.",
853
+ use: "by-hand",
786
854
  flags: [
787
855
  { name: "root", type: "string", help: "checkout whose ledgers to read (default: cwd)" },
788
856
  { name: "plan", type: "string", required: true, help: "plan file, relative to --root" },
@@ -798,6 +866,28 @@ export const ledgersCommand: CommandSpec = {
798
866
  },
799
867
  run: (ctx) => check(ctx),
800
868
  },
869
+ compact: {
870
+ summary:
871
+ "Rewrite keyed ledgers to their fold winners, stamping each winner's firstTs + updates.",
872
+ use: "by-hand",
873
+ flags: [
874
+ { name: "root", type: "string", help: "checkout whose ledgers to compact (default: cwd)" },
875
+ {
876
+ name: "ledger",
877
+ type: "string",
878
+ help: `${Object.keys(COMPACT_LEDGERS).join(" | ")} | all (default: all)`,
879
+ },
880
+ { name: "dry-run", type: "boolean", help: "count only; write nothing" },
881
+ ],
882
+ output: {
883
+ dryRun: "true when nothing was written by design",
884
+ ledgers:
885
+ "per ledger: ledger, file, rows (keyed rows folded), dropped (superseded rows removed), stamped (winners given firstTs / updates), written",
886
+ dropped: "superseded rows removed across all ledgers",
887
+ },
888
+ exitCodes: { [EXIT_STAGE]: "writing a compacted ledger failed" },
889
+ run: (ctx) => compact(ctx),
890
+ },
801
891
  },
802
892
  };
803
893
 
@@ -840,6 +930,9 @@ function commitOnePath(o: BookkeepingCommit, log: (m: string) => void): Bookkeep
840
930
  squashPaths: [],
841
931
  tracked: [],
842
932
  });
933
+ if (isIgnoredPath(root, inside)) {
934
+ throw new CommandError(EXIT_STAGE, `--path is gitignored, refusing to stage it: ${inside}`);
935
+ }
843
936
  const add = gitRaw(root, ["add", "--", inside]);
844
937
  if (add.status !== 0) throw new CommandError(EXIT_STAGE, `'git add' failed: ${add.stderr}`);
845
938
  if (
@@ -958,7 +1051,7 @@ export function commitBookkeeping(
958
1051
  }
959
1052
  }
960
1053
 
961
- const specs = bookPathspecs(month, fid, scope);
1054
+ const specs = bookPathspecs(month, fid, scope, readBkitConfig(root).ciSkipPaths);
962
1055
  const listed = gitRaw(root, [
963
1056
  "ls-files",
964
1057
  "-z",
@@ -1162,14 +1255,27 @@ export interface AppendResult {
1162
1255
  }
1163
1256
 
1164
1257
  /** The top section in its written order, then the row's own fields. */
1165
- const TOP_ORDER = ["schema", "ts", "kind", "key", "repo", "bkit", "by", "references"];
1258
+ const TOP_ORDER = [
1259
+ "schema",
1260
+ "ts",
1261
+ "firstTs",
1262
+ "updates",
1263
+ "kind",
1264
+ "key",
1265
+ "repo",
1266
+ "bkit",
1267
+ "by",
1268
+ "references",
1269
+ ];
1166
1270
 
1167
1271
  /**
1168
1272
  * Append `rows` to one ledger. Every row is checked before any is written, so a
1169
1273
  * refused row leaves the file byte-identical. Each row gets `schema` and a `ts`
1170
1274
  * minted now (never supplied), `repo` when it lacks one and `bkit.version` from
1171
- * `.bkit/version`. Never reads back or rewrites existing rows. Throws a
1172
- * CommandError (USAGE / EXIT_ROW_REFUSED / EXIT_STAGE).
1275
+ * `.bkit/version`; an `AGED_KINDS` row also gets `firstTs` + `updates` carried
1276
+ * forward from its entry's rows already in the ledger (supplied values replaced).
1277
+ * Never rewrites existing rows. Throws a CommandError (USAGE / EXIT_ROW_REFUSED /
1278
+ * EXIT_STAGE).
1173
1279
  */
1174
1280
  export function appendLedgerRows(root: string, ledger: string, rows: unknown): AppendResult {
1175
1281
  if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
@@ -1186,6 +1292,8 @@ export function appendLedgerRows(root: string, ledger: string, rows: unknown): A
1186
1292
  let repo: string | undefined;
1187
1293
  let version: string | undefined;
1188
1294
  let last: number | undefined;
1295
+ const abs = path.join(root, file);
1296
+ const prior: unknown[] = fs.existsSync(abs) ? parse(fs.readFileSync(abs, "utf-8")).events : [];
1189
1297
  const out: Array<Record<string, unknown>> = rows.map((raw, i) => {
1190
1298
  const refuse = (why: string) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
1191
1299
  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
@@ -1203,13 +1311,13 @@ export function appendLedgerRows(root: string, ledger: string, rows: unknown): A
1203
1311
  repo ??= resolveRepoSlug(root) || "unknown/repo";
1204
1312
  version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
1205
1313
  last = mintTs(last);
1206
- const filled: Record<string, unknown> = {
1314
+ const filled = withLineage(prior, {
1207
1315
  repo,
1208
1316
  ...r,
1209
1317
  schema: SCHEMA,
1210
1318
  ts: last,
1211
1319
  bkit: { version },
1212
- };
1320
+ });
1213
1321
  const row: Record<string, unknown> = {};
1214
1322
  for (const k of TOP_ORDER) if (filled[k] !== undefined) row[k] = filled[k];
1215
1323
  for (const [k, v] of Object.entries(filled)) if (!(k in row)) row[k] = v;
@@ -1217,10 +1325,10 @@ export function appendLedgerRows(root: string, ledger: string, rows: unknown): A
1217
1325
  if (!v.ok) throw refuse(v.reason ?? "invalid");
1218
1326
  const who = writerProblem(row);
1219
1327
  if (who !== undefined) throw refuse(who);
1328
+ prior.push(row);
1220
1329
  return row;
1221
1330
  });
1222
1331
 
1223
- const abs = path.join(root, file);
1224
1332
  const made = mkdirp(path.dirname(abs));
1225
1333
  if (made) throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(file)}: ${made}`);
1226
1334
  const block = out.map((r) => `${JSON.stringify(r)}\n`).join("");
@@ -1319,6 +1427,27 @@ function check(ctx: RunContext): number {
1319
1427
  return EXIT.OK;
1320
1428
  }
1321
1429
 
1430
+ function compact(ctx: RunContext): number {
1431
+ const root = rootOf(ctx);
1432
+ const named = str(ctx.flags.ledger) ?? "all";
1433
+ if (named !== "all" && !Object.hasOwn(COMPACT_LEDGERS, named)) {
1434
+ throw new CommandError(
1435
+ EXIT.USAGE,
1436
+ `--ledger must be one of ${Object.keys(COMPACT_LEDGERS).join(", ")}, all (got '${named}')`,
1437
+ );
1438
+ }
1439
+ const ledgers = (named === "all" ? Object.keys(COMPACT_LEDGERS) : [named]) as CompactLedger[];
1440
+ const dryRun = ctx.flags.dryRun === true;
1441
+ const results = compactOrError(root, ledgers, dryRun);
1442
+ if (typeof results === "string") throw new CommandError(EXIT_STAGE, `compact failed: ${results}`);
1443
+ const dropped = results.reduce((n, r) => n + r.dropped, 0);
1444
+ for (const r of results) {
1445
+ ctx.log(`${r.file}: ${r.dropped} superseded row(s) dropped, ${r.stamped} winner(s) stamped`);
1446
+ }
1447
+ ctx.emit({ dryRun, ledgers: results, dropped });
1448
+ return EXIT.OK;
1449
+ }
1450
+
1322
1451
  /** mkdir -p; the error text, or undefined on success. */
1323
1452
  function mkdirp(dir: string): string | undefined {
1324
1453
  try {
@@ -1330,6 +1459,20 @@ function mkdirp(dir: string): string | undefined {
1330
1459
  }
1331
1460
  }
1332
1461
 
1462
+ /** {@link compactLedgers}; its results, or the error text. A failed temp write or rename leaves the ledger untouched. */
1463
+ function compactOrError(
1464
+ root: string,
1465
+ ledgers: readonly CompactLedger[],
1466
+ dryRun: boolean,
1467
+ ): ReturnType<typeof compactLedgers> | string {
1468
+ try {
1469
+ return compactLedgers(root, ledgers, dryRun);
1470
+ } catch (err) {
1471
+ // Reported as the command's staging exit code, with the reason.
1472
+ return (err as Error).message;
1473
+ }
1474
+ }
1475
+
1333
1476
  /** Append `text` to `file`; the error text, or undefined on success. */
1334
1477
  function appendText(file: string, text: string): string | undefined {
1335
1478
  try {
@@ -1384,7 +1527,12 @@ export function checkOnlyBookkeeping(
1384
1527
  if (gitRaw(root, ["merge-base", "--is-ancestor", o.from, o.to]).status !== 0) {
1385
1528
  return { kind: "not-ancestor" };
1386
1529
  }
1387
- const diff = changedOutside(root, o.from, o.to, bookPathspecs(o.month, o.fid, "pr"));
1530
+ const diff = changedOutside(
1531
+ root,
1532
+ o.from,
1533
+ o.to,
1534
+ bookPathspecs(o.month, o.fid, "pr", readBkitConfig(root).ciSkipPaths),
1535
+ );
1388
1536
  if (!diff.ok) return { kind: "diff-failed", stderr: diff.stderr };
1389
1537
  return diff.outside.length ? { kind: "outside", outside: diff.outside } : { kind: "ok" };
1390
1538
  }
@@ -1449,3 +1597,295 @@ function onlyBookkeeping(ctx: RunContext): number {
1449
1597
  return EXIT.OK;
1450
1598
  }
1451
1599
  }
1600
+
1601
+ // ---------------------------------------------------------------------------
1602
+ // triage — the sweep's deferral tests, computed
1603
+ // ---------------------------------------------------------------------------
1604
+ //
1605
+ // `.bkit/jsonl.md` § Deferral Reason states the four tests: each names a way a
1606
+ // deferral reads as in-scope work that should have been finished, and all four
1607
+ // holding marks the row `unjustified`. The engine decides them from the row, its
1608
+ // own `references`, the plan's task surfaces, its Reuse Inventory and its
1609
+ // Out of Scope table. The sweep keeps the judgement the four cannot reach.
1610
+
1611
+ /** The four tests, in `.bkit/jsonl.md` order; each holds when the row reads as in-scope work. */
1612
+ export const DEFERRAL_TESTS = [
1613
+ "bounded-remediation",
1614
+ "in-scope-surface",
1615
+ "no-external-blocker",
1616
+ "own-declaration",
1617
+ ] as const;
1618
+ export type DeferralTest = (typeof DEFERRAL_TESTS)[number];
1619
+
1620
+ /** One test's verdict on a row. */
1621
+ export interface DeferralTestResult {
1622
+ test: DeferralTest;
1623
+ held: boolean;
1624
+ }
1625
+
1626
+ /** One matched deferral row's bucket and the tests behind it. */
1627
+ export interface TriageRow {
1628
+ key: string | null;
1629
+ /**
1630
+ * `Lazy` when every test holds, and for a row already adjudicated `unjustified`:
1631
+ * in-scope work that should have been finished.
1632
+ */
1633
+ bucket: "Exempt" | "Lazy";
1634
+ /** Empty when the row is settled before the tests are applied. */
1635
+ tests: DeferralTestResult[];
1636
+ /** A same-`key` `unjustified` / `TRIAGED` row was appended for it. */
1637
+ written: boolean;
1638
+ }
1639
+
1640
+ export interface TriageResult {
1641
+ fid: string;
1642
+ plan: string;
1643
+ rows: TriageRow[];
1644
+ total: number;
1645
+ written: number;
1646
+ }
1647
+
1648
+ /** The issue number a FID leads with (`701-engine-work` → `701`), else "". */
1649
+ const fidIssue = (fid: string) => /^(\d+)(?=$|[-_])/.exec(fid)?.[1] ?? "";
1650
+
1651
+ /** A row's `references` entries, as written. */
1652
+ const rowRefs = (row: Record<string, unknown>): string[] =>
1653
+ Array.isArray(row["references"])
1654
+ ? row["references"].filter((x): x is string => typeof x === "string")
1655
+ : [];
1656
+
1657
+ /** True when `ref` names the feature: the FID, or its leading issue number as `N` / `#N`. */
1658
+ const namesFeature = (ref: string, fid: string, issue: string): boolean =>
1659
+ ref.includes(fid) || (issue !== "" && new RegExp(`^#?${issue}(?![0-9])`).test(ref));
1660
+
1661
+ /** Every well-formed row of a JSONL ledger, as written. */
1662
+ function readLedgerRows(file: string): Array<Record<string, unknown>> {
1663
+ if (!fs.existsSync(file)) return [];
1664
+ return fs
1665
+ .readFileSync(file, "utf-8")
1666
+ .split("\n")
1667
+ .flatMap((line): Array<Record<string, unknown>> => {
1668
+ if (line.trim() === "") return [];
1669
+ const parsed = parseJson(line);
1670
+ const v = parsed.ok ? parsed.value : null;
1671
+ return typeof v === "object" && v !== null && !Array.isArray(v)
1672
+ ? [v as Record<string, unknown>]
1673
+ : [];
1674
+ });
1675
+ }
1676
+
1677
+ /** The deferral rows `fid` declared, same-`key` folded last-wins, in first-seen order. */
1678
+ export function featureDeferrals(
1679
+ rows: Array<Record<string, unknown>>,
1680
+ fid: string,
1681
+ ): Array<Record<string, unknown>> {
1682
+ const issue = fidIssue(fid);
1683
+ const kept: Array<Record<string, unknown>> = [];
1684
+ const at = new Map<string, number>();
1685
+ for (const row of rows) {
1686
+ if (row["kind"] !== "deferral") continue;
1687
+ const key = typeof row["key"] === "string" ? row["key"] : "";
1688
+ const named = key !== "" && namesFeature(key, fid, issue);
1689
+ if (!named && !rowRefs(row).some((r) => namesFeature(r, fid, issue))) continue;
1690
+ const seen = key === "" ? undefined : at.get(key);
1691
+ if (seen !== undefined) {
1692
+ kept[seen] = row;
1693
+ continue;
1694
+ }
1695
+ if (key !== "") at.set(key, kept.length);
1696
+ kept.push(row);
1697
+ }
1698
+ return kept;
1699
+ }
1700
+
1701
+ /** A repo path a token names, with any `:line` suffix cut; null when the token is no path. */
1702
+ function pathToken(token: string): string | null {
1703
+ const t = token
1704
+ .trim()
1705
+ .replace(/:\d+(?:-\d+)?$/, "")
1706
+ .replace(/[.,;:]+$/, "")
1707
+ .replace(/^\.\//, "");
1708
+ if (t === "" || /\s/.test(t) || t.startsWith("#") || /^[a-z][a-z0-9+.-]*:\/\//i.test(t))
1709
+ return null;
1710
+ if (!t.includes("/") && !/\.[A-Za-z][A-Za-z0-9]{0,5}$/.test(t)) return null;
1711
+ return path.posix.normalize(t);
1712
+ }
1713
+
1714
+ /** The repo paths a row names: backticked spans and bare words of its `remediation`, plus its `references`. */
1715
+ function namedPaths(row: Record<string, unknown>): string[] {
1716
+ const texts = [
1717
+ ...(typeof row["remediation"] === "string" ? [row["remediation"]] : []),
1718
+ ...rowRefs(row),
1719
+ ];
1720
+ const tokens = texts.flatMap((t) => [
1721
+ ...[...t.matchAll(/`([^`]+)`/g)].map((m) => m[1]!),
1722
+ ...t.replace(/`[^`]*`/g, " ").split(/[\s,()[\]]+/),
1723
+ ]);
1724
+ return [
1725
+ ...new Set(
1726
+ tokens.map(pathToken).filter((p): p is string => p !== null && p !== "." && p !== ".."),
1727
+ ),
1728
+ ];
1729
+ }
1730
+
1731
+ /** True when one of `paths` is a file in `root`. */
1732
+ function existsIn(root: string, paths: string[]): boolean {
1733
+ return paths.some((p) => {
1734
+ const abs = path.resolve(root, p);
1735
+ const rel = path.relative(root, abs);
1736
+ return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel) && fs.existsSync(abs);
1737
+ });
1738
+ }
1739
+
1740
+ /** True when `a` and `b` name the same path, or one sits inside the other. */
1741
+ const within = (a: string, b: string) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
1742
+
1743
+ const NORMAL = (s: string) => s.toLowerCase().replace(/\s+/g, " ").trim();
1744
+
1745
+ /** The items the plan's `Out of Scope` rows declare: their excluded item and every backticked token. */
1746
+ function declaredItems(rows: OutOfScopeRow[] | null): Set<string> {
1747
+ const out = new Set<string>();
1748
+ for (const row of rows ?? []) {
1749
+ const item = row.cells[0] ?? "";
1750
+ if (item !== "") out.add(NORMAL(item));
1751
+ for (const cell of row.cells)
1752
+ for (const m of cell.matchAll(/`([^`]+)`/g)) if (m[1]!.trim() !== "") out.add(NORMAL(m[1]!));
1753
+ }
1754
+ return out;
1755
+ }
1756
+
1757
+ /**
1758
+ * True when a reference other than the row's own key or the bare FID names a
1759
+ * pre-existing declaration: a plan `Out of Scope` item, or a doc section declared
1760
+ * out of scope. A row that is its own only declaration names none.
1761
+ */
1762
+ function declares(
1763
+ row: Record<string, unknown>,
1764
+ fid: string,
1765
+ issue: string,
1766
+ declared: Set<string>,
1767
+ ): boolean {
1768
+ const own = typeof row["key"] === "string" ? NORMAL(row["key"]) : "";
1769
+ const self = NORMAL(fid);
1770
+ for (const ref of rowRefs(row)) {
1771
+ const t = ref.trim();
1772
+ if (t === "" || NORMAL(t) === own || NORMAL(t) === self || t === `#${issue}`) continue;
1773
+ if (t.includes("§") && /out[- ]of[- ]scope|non-?goals?/i.test(t)) return true;
1774
+ const n = NORMAL(t);
1775
+ if (declared.has(n)) return true;
1776
+ for (const d of declared) if (d.length >= 8 && n.includes(d)) return true;
1777
+ }
1778
+ return false;
1779
+ }
1780
+
1781
+ /** The same-`key` row triage appends: every prior field verbatim, the verdict fields replaced. */
1782
+ export function unjustifiedRow(
1783
+ row: Record<string, unknown>,
1784
+ fid: string,
1785
+ held: DeferralTest[],
1786
+ ): Record<string, unknown> {
1787
+ const out: Record<string, unknown> = {};
1788
+ for (const [k, v] of Object.entries(row)) {
1789
+ if (k === "schema" || k === "ts" || k === "bkit" || k === "by" || k === "description") continue;
1790
+ out[k] = v;
1791
+ }
1792
+ out["kind"] = "deferral";
1793
+ out["reason"] = UNJUSTIFIED_REASON;
1794
+ out["status"] = "TRIAGED";
1795
+ out["description"] =
1796
+ `Adjudicated unjustified by bkit ledgers triage for ${fid}: every deferral test holds (${held.join(", ")}).`;
1797
+ // The ship orchestrator's sweep step is the writer, so the row clears the kind's writer check.
1798
+ out["by"] = { workflow: "ship", step: "ship-deferred-sweep" };
1799
+ return out;
1800
+ }
1801
+
1802
+ /**
1803
+ * Bucket the FID's deferral rows by the four tests and append a same-`key`
1804
+ * `unjustified` / `TRIAGED` row for each that holds all four. Throws
1805
+ * CommandError(USAGE) on a missing `--plan` or a plan whose task blocks do not
1806
+ * parse, CommandError(NO) on a plan with no task blocks — nothing written either
1807
+ * way — and EXIT_ROW_REFUSED when a computed row fails validation.
1808
+ */
1809
+ export function triageDeferrals(root: string, fid: string, planPath: string): TriageResult {
1810
+ const abs = path.resolve(root, planPath);
1811
+ if (!fs.existsSync(abs)) throw new CommandError(EXIT.USAGE, `--plan not found: ${planPath}`);
1812
+ const text = fs.readFileSync(abs, "utf-8");
1813
+ const blocks = parsePlanBlocks(text);
1814
+ const error = blocks.errors[0];
1815
+ if (error !== undefined)
1816
+ throw new CommandError(
1817
+ EXIT.USAGE,
1818
+ `${planPath}:${error.line}: ${error.message} — run \`bkit tests plan-check\``,
1819
+ );
1820
+ // No task block means no task surface: every row would bucket `Exempt` unread.
1821
+ if (blocks.tasks.length === 0)
1822
+ throw new CommandError(EXIT.NO, `${planPath}: ${NO_MARKERS_REASON}`);
1823
+ const surfaces = new Set<string>();
1824
+ for (const task of blocks.tasks)
1825
+ for (const ref of [...task.create, ...task.read, ...task.update, ...task.delete])
1826
+ surfaces.add(path.posix.normalize(ref.file));
1827
+ for (const row of reuseInventory(text)?.rows ?? []) for (const f of row.files) surfaces.add(f);
1828
+ const scope = [...surfaces];
1829
+ const declared = declaredItems(outOfScope(text));
1830
+ const issue = fidIssue(fid);
1831
+ const rows = featureDeferrals(
1832
+ readLedgerRows(path.join(root, APPEND_LEDGERS.deferrals.file)),
1833
+ fid,
1834
+ );
1835
+ const out: TriageRow[] = [];
1836
+ const write: Array<Record<string, unknown>> = [];
1837
+ for (const row of rows) {
1838
+ const key = typeof row["key"] === "string" ? row["key"] : null;
1839
+ // Closed work is done: nothing to test, nothing to write.
1840
+ if (row["status"] === "CLOSED") {
1841
+ out.push({ key, bucket: "Exempt", tests: [], written: false });
1842
+ continue;
1843
+ }
1844
+ // A LOW challenge finding holds without the tests, and an adjudicated row is never
1845
+ // re-adjudicated: it keeps the `Lazy` bucket its adjudication earned, so an
1846
+ // outstanding unjustified deferral never reads as `Exempt Deferrals`.
1847
+ if (row["reason"] === UNJUSTIFIED_REASON) {
1848
+ out.push({ key, bucket: "Lazy", tests: [], written: false });
1849
+ continue;
1850
+ }
1851
+ if (row["reason"] === "low-severity" && row["severity"] === "LOW") {
1852
+ out.push({ key, bucket: "Exempt", tests: [], written: false });
1853
+ continue;
1854
+ }
1855
+ const paths = namedPaths(row);
1856
+ const verdicts: Record<DeferralTest, boolean> = {
1857
+ // Test 1 reads "not a new architecture": an `own-cycle` row declares itself plan-sized.
1858
+ "bounded-remediation": row["reason"] !== "own-cycle" && existsIn(root, paths),
1859
+ "in-scope-surface": paths.some((p) => scope.some((s) => within(p, s))),
1860
+ "no-external-blocker": row["reason"] !== "hard-blocked" && row["reason"] !== "needs-decision",
1861
+ "own-declaration": !declares(row, fid, issue, declared),
1862
+ };
1863
+ const tests = DEFERRAL_TESTS.map((test) => ({ test, held: verdicts[test] }));
1864
+ const lazy = tests.every((t) => t.held);
1865
+ if (lazy)
1866
+ write.push(
1867
+ unjustifiedRow(
1868
+ row,
1869
+ fid,
1870
+ tests.map((t) => t.test),
1871
+ ),
1872
+ );
1873
+ out.push({ key, bucket: lazy ? "Lazy" : "Exempt", tests, written: lazy });
1874
+ }
1875
+ if (write.length > 0) appendLedgerRows(root, "deferrals", write);
1876
+ return { fid, plan: planPath, rows: out, total: out.length, written: write.length };
1877
+ }
1878
+
1879
+ function triage(ctx: RunContext): number {
1880
+ const r = triageDeferrals(rootOf(ctx), required(ctx, "fid"), required(ctx, "plan"));
1881
+ for (const row of r.rows) {
1882
+ const verdict =
1883
+ row.tests.length === 0
1884
+ ? "not tested"
1885
+ : row.tests.map((t) => `${t.test} ${t.held ? "holds" : "fails"}`).join(", ");
1886
+ ctx.log(`${row.key ?? "(no key)"} — ${row.bucket}: ${verdict}`);
1887
+ }
1888
+ ctx.log(`${r.total} deferral row(s) for ${r.fid}, ${r.written} written unjustified`);
1889
+ ctx.emit({ ...r });
1890
+ return EXIT.OK;
1891
+ }
@@ -306,6 +306,7 @@ export const locksCommand: CommandSpec = {
306
306
  verbs: {
307
307
  acquire: {
308
308
  summary: "Take the workflow lock, reclaiming a dead holder's.",
309
+ use: "workflow",
309
310
  flags: [KIND_FLAG, LOCK_WORKFLOW_FLAG, FID_FLAG, MONTH_FLAG],
310
311
  output: {
311
312
  kind: "workflow",
@@ -333,6 +334,7 @@ export const locksCommand: CommandSpec = {
333
334
  release: {
334
335
  summary:
335
336
  "Remove a lock this caller owns (and the feature's shared-checkout record); another owner's lock is left in place.",
337
+ use: "workflow",
336
338
  flags: [
337
339
  KIND_FLAG,
338
340
  LOCK_WORKFLOW_FLAG,