@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
@@ -21,23 +21,165 @@ import * as path from "node:path";
21
21
 
22
22
  import { parseJson } from "../shared/json.js";
23
23
 
24
+ export const CI_TIERS = ["static", "unit", "integration", "e2e", "live", "migration"] as const;
25
+ export type CiTier = (typeof CI_TIERS)[number];
26
+ export type CiSelection =
27
+ | { mode: "local"; reason: string }
28
+ | {
29
+ mode: "ci";
30
+ provider: "github";
31
+ repo: string;
32
+ runId: string;
33
+ runAttempt: number;
34
+ runUrl: string;
35
+ workflowId: string;
36
+ workflowPath: string;
37
+ headBranch: string;
38
+ headSha: string;
39
+ conclusion: "failure" | "timed_out" | "startup_failure";
40
+ redTiers: CiTier[];
41
+ via: string;
42
+ };
43
+
44
+ /** Validate the whole saved selection before any reader treats it as evidence. */
45
+ export function validateCiSelection(value: unknown): value is CiSelection {
46
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
47
+ const v = value as Record<string, unknown>;
48
+ if (v.mode === "local") return typeof v.reason === "string" && v.reason.trim().length > 0;
49
+ const stringField = (key: string) => (typeof v[key] === "string" ? v[key] : "");
50
+ const repo = stringField("repo");
51
+ const runId = stringField("runId");
52
+ const branch = stringField("headBranch");
53
+ return (
54
+ v.mode === "ci" &&
55
+ v.provider === "github" &&
56
+ /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(repo) &&
57
+ /^[1-9][0-9]*$/.test(runId) &&
58
+ Number.isSafeInteger(v.runAttempt) &&
59
+ Number(v.runAttempt) > 0 &&
60
+ stringField("runUrl") ===
61
+ `https://github.com/${repo}/actions/runs/${runId}/attempts/${v.runAttempt}` &&
62
+ /^[1-9][0-9]*$/.test(stringField("workflowId")) &&
63
+ /^\.github\/workflows\/[^/]+\.ya?ml$/.test(stringField("workflowPath")) &&
64
+ !stringField("workflowPath").includes("..") &&
65
+ branch.length > 0 &&
66
+ !branch.startsWith("-") &&
67
+ !branch.startsWith("/") &&
68
+ !branch.endsWith("/") &&
69
+ !/[\s~^:?*\[\\\u0000-\u001f\u007f]/.test(branch) &&
70
+ !branch.includes("..") &&
71
+ !branch.includes("//") &&
72
+ !branch.includes("@{") &&
73
+ !branch.endsWith(".") &&
74
+ branch.split("/").every((part) => !part.startsWith(".") && !part.endsWith(".lock")) &&
75
+ /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(stringField("headSha")) &&
76
+ ["failure", "timed_out", "startup_failure"].includes(stringField("conclusion")) &&
77
+ Array.isArray(v.redTiers) &&
78
+ v.redTiers.every((tier) => CI_TIERS.some((known) => known === tier)) &&
79
+ typeof v.via === "string" &&
80
+ v.via.trim().length > 0
81
+ );
82
+ }
83
+
84
+ /** Transport and wording changes preserve the identity of the evidence. */
85
+ export function ciSelectionIdentity(selection: CiSelection): string {
86
+ return JSON.stringify(
87
+ selection.mode === "local"
88
+ ? ["local"]
89
+ : [
90
+ selection.provider,
91
+ selection.repo.toLowerCase(),
92
+ selection.workflowId,
93
+ selection.workflowPath,
94
+ selection.runId,
95
+ selection.runAttempt,
96
+ selection.headSha,
97
+ ],
98
+ );
99
+ }
100
+
24
101
  export type Step = {
25
102
  step: string;
26
103
  status: "DONE" | "FAILED";
27
104
  at: string;
28
105
  parentSha: string;
29
106
  artifacts: string[];
30
- verdict?: "PASS" | "FAIL" | "CONCERNS" | "SINGLE" | "SPLIT";
107
+ verdict?: "PASS" | "FAIL" | "CONCERNS" | "HANDOVER" | "SINGLE" | "SPLIT";
31
108
  attempt?: number;
32
- /** The plan group the step ran for. */
109
+ /** The task group the step ran for. */
33
110
  group?: number;
34
111
  /** A row written before groups replaced sub-plans; read as its group. */
35
112
  subPlan?: number;
36
113
  failures?: number;
37
114
  strategy?: "STANDARD" | "PIVOT" | "FINAL";
38
115
  scope?: string;
116
+ ciGeneration?: number;
117
+ reproduced?: string;
39
118
  };
40
119
 
120
+ /** Validate the bounded CI evidence variant without relaxing local exit codes. */
121
+ export function testRunProblem(value: unknown): string | null {
122
+ if (!value || typeof value !== "object") return "test-run must be an object";
123
+ const r = value as Record<string, unknown>;
124
+ const positive = (v: unknown) => Number.isSafeInteger(v) && Number(v) > 0;
125
+ if (r.source === "ci") {
126
+ if (
127
+ r.workflow !== "debug" ||
128
+ r.step !== "debug-run-tests" ||
129
+ r.verdict !== "FAIL" ||
130
+ r.exitCode !== null ||
131
+ r.failures !== null ||
132
+ r.gate !== null ||
133
+ !positive(r.ciGeneration) ||
134
+ !positive(r.runAttempt) ||
135
+ typeof r.ciRun !== "string" ||
136
+ !/^[1-9][0-9]*$/.test(r.ciRun) ||
137
+ r.scope !== `ci:${r.ciRun}` ||
138
+ typeof r.artifact !== "string" ||
139
+ !r.artifact ||
140
+ typeof r.repo !== "string" ||
141
+ !/^[\w.-]+\/[\w.-]+$/.test(r.repo) ||
142
+ r.ciUrl !== `https://github.com/${r.repo}/actions/runs/${r.ciRun}/attempts/${r.runAttempt}` ||
143
+ typeof r.workflowId !== "string" ||
144
+ !/^[1-9][0-9]*$/.test(r.workflowId) ||
145
+ typeof r.workflowPath !== "string" ||
146
+ !/^\.github\/workflows\/[^/]+\.ya?ml$/.test(r.workflowPath) ||
147
+ typeof r.headSha !== "string" ||
148
+ !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(r.headSha)
149
+ )
150
+ return "invalid CI evidence round";
151
+ return null;
152
+ }
153
+ if (r.source !== undefined && r.source !== "local") return "invalid test source";
154
+ if (!Number.isSafeInteger(r.exitCode) || Number(r.exitCode) < 0)
155
+ return "local exitCode must be a non-negative integer";
156
+ if (r.failures !== null && (!Number.isSafeInteger(r.failures) || Number(r.failures) < 0))
157
+ return "invalid failure count";
158
+ return null;
159
+ }
160
+
161
+ /** A round belongs to exactly one saved evidence generation. */
162
+ export function ciRoundMatches(
163
+ row: Record<string, unknown>,
164
+ selection: unknown,
165
+ generation: unknown,
166
+ ): boolean {
167
+ return (
168
+ validateCiSelection(selection) &&
169
+ selection.mode === "ci" &&
170
+ testRunProblem(row) === null &&
171
+ row.source === "ci" &&
172
+ row.ciGeneration === generation &&
173
+ row.ciRun === selection.runId &&
174
+ row.runAttempt === selection.runAttempt &&
175
+ row.ciUrl === selection.runUrl &&
176
+ row.repo === selection.repo &&
177
+ row.workflowId === selection.workflowId &&
178
+ row.workflowPath === selection.workflowPath &&
179
+ row.headSha === selection.headSha
180
+ );
181
+ }
182
+
41
183
  export type WorkflowRun = {
42
184
  workflow: string;
43
185
  startedAt: string;
@@ -54,14 +196,24 @@ export type StatusEvent =
54
196
  | ({ type: "step-done"; workflow: string } & Step)
55
197
  | ({ type: "workflow-meta"; workflow: string; at: string } & Record<string, unknown>)
56
198
  // `parentSha`: HEAD at close, the run's join key (`run.parentSha` on its ledger rows).
57
- | { type: "workflow-done"; workflow: string; at: string; parentSha?: string }
199
+ // `ending` / `publish`: a build's close; `held` = a local build that published nothing.
200
+ | {
201
+ type: "workflow-done";
202
+ workflow: string;
203
+ at: string;
204
+ parentSha?: string;
205
+ ending?: "done" | "held";
206
+ publish?: boolean;
207
+ }
58
208
  | { type: "workflow-failed"; workflow: string; at: string };
59
209
 
60
210
  // Identity for de-dup under union merge. `step-done` is unique per
61
211
  // (workflow, step, parentSha, at); workflow-level events per (type, workflow, at).
62
212
  function identity(e: StatusEvent): string {
63
213
  if (e.type === "step-done")
64
- return `S\u0000${e.workflow}\u0000${e.step}\u0000${e.parentSha}\u0000${e.at}`;
214
+ return `S\u0000${e.workflow}\u0000${e.step}\u0000${e.parentSha}\u0000${e.at}${e.ciGeneration === undefined ? "" : `\u0000${e.status}\u0000${e.ciGeneration}`}`;
215
+ if (e.type === "workflow-meta" && e.ciSelection !== undefined)
216
+ return `M\u0000${e.workflow}\u0000${e.at}\u0000${e.ciGeneration}\u0000${JSON.stringify(e.ciSelection)}`;
65
217
  return `W\u0000${e.type}\u0000${e.workflow}\u0000${e.at}`;
66
218
  }
67
219
 
@@ -189,13 +341,12 @@ export function lastDoneStepAllRuns(
189
341
 
190
342
  /**
191
343
  * Which run of `workflow` this invocation is (1-based): the count of its runs,
192
- * plus one unless the latest run overall is one of them still IN_PROGRESS — a
193
- * resume. Same answer before and after the run's `workflow-started` row lands.
344
+ * plus one unless the latest of them is still IN_PROGRESS — a resume, even after
345
+ * another workflow's run. Same answer before and after the run's `workflow-started` row lands.
194
346
  */
195
347
  export function runNumber(runs: WorkflowRun[], workflow: string): number {
196
348
  const n = runs.filter((r) => r.workflow === workflow).length;
197
- const latest = runs.at(-1);
198
- return latest?.workflow === workflow && latest.status === "IN_PROGRESS" ? n : n + 1;
349
+ return lastRun(runs, workflow)?.status === "IN_PROGRESS" ? n : n + 1;
199
350
  }
200
351
 
201
352
  /**
@@ -228,7 +379,7 @@ export type EngineActionRow = {
228
379
  type: typeof ENGINE_ACTION;
229
380
  /** What was done: `comment`, `commit`, `dispatch`, `pr-open`, … */
230
381
  action: string;
231
- /** The moment: workflow, run, step, plan group, attempt and kind, joined by `/`. */
382
+ /** The moment: workflow, run, step, task group, attempt and kind, joined by `/`. */
232
383
  key: string;
233
384
  /** sha256 of the body or payload acted on. */
234
385
  hash: string;
@@ -122,7 +122,7 @@ const NORMALIZED_SCHEMA = 2;
122
122
 
123
123
  /** Who wrote a row: the workflow and step it was emitted at, and the subagent when one wrote it. */
124
124
  export interface RowBy {
125
- /** Emitting workflow: design | plan | build | debug | ship | audit; `chat-stats` on `chat` rows; the counted run's on `run` rows. */
125
+ /** Emitting workflow: design | plan | build | debug | ship | auto | audit; `utility` for a direct chat outside any workflow; `chat-stats` on `chat` rows; the counted run's on `run` rows. */
126
126
  workflow?: string;
127
127
  /**
128
128
  * The WORKFLOW STEP the row was emitted at, e.g. `build-close-workflow`,
@@ -155,6 +155,13 @@ export interface TelemetryEnvelope {
155
155
  schema: typeof SCHEMA | typeof NORMALIZED_SCHEMA;
156
156
  /** Primary id = unix milliseconds (portable: jq `now*1000|floor`). */
157
157
  ts: number;
158
+ /**
159
+ * {@link AGED_KINDS} only: `ts` of the entry's first row, so `ts - firstTs` is its age
160
+ * after compaction drops the rows before it. Set by the writer ({@link withLineage}), never authored.
161
+ */
162
+ firstTs?: number;
163
+ /** {@link AGED_KINDS} only: rows the entry has had, this one included — its recurrence count. Set like `firstTs`. */
164
+ updates?: number;
158
165
  /** Closed enum — validated on append; unknown kind rejected. */
159
166
  kind: TelemetryKind;
160
167
  /**
@@ -259,6 +266,18 @@ export const TRIAGE_STATUSES: Set<string> = new Set(["OPEN", "TRIAGED", "CLOSED"
259
266
  /** The `ACTIVE` / `SUPERSEDED` lifecycle shared by `decision` and `knowledge`. */
260
267
  export const DECISION_STATUSES: Set<string> = new Set(["ACTIVE", "SUPERSEDED"]);
261
268
 
269
+ /**
270
+ * The kinds whose rows carry `firstTs` + `updates` (`.bkit/jsonl.md` § Compaction):
271
+ * the keyed kinds of the ledgers `bkit ledgers compact` rewrites to their fold winners.
272
+ */
273
+ export const AGED_KINDS: Set<string> = new Set([
274
+ "deferral",
275
+ "failure",
276
+ "knowledge",
277
+ "decision",
278
+ "feature",
279
+ ]);
280
+
262
281
  /**
263
282
  * The `feature` kind's six-state phase ladder — the canonical status for
264
283
  * `.bkit/issues.jsonl`, appended once per phase close, same-`key`
@@ -335,7 +354,7 @@ export const UNJUSTIFIED_REASON = "unjustified";
335
354
  * § Ledgers & Writers). EXHAUSTIVE: a subagent absent from this set does not
336
355
  * write the kind at all.
337
356
  *
338
- * `@bkit-build-plan-execute` and `@bkit-build-plan-gaps-remediate` are not in it: a
357
+ * `@bkit-build-plan-tasks` and `@bkit-build-plan-gaps-remediate` are not in it: a
339
358
  * blocked plan task's record is its `BLOCKED` log line, which the next verify pass reads.
340
359
  *
341
360
  * Orchestrator-written rows carry no `subagent` and are outside this check.
@@ -379,6 +398,12 @@ export type AppendKind = (typeof APPEND_LEDGERS)[AppendLedger]["kinds"][number];
379
398
  /** The workflows whose close writes `.bkit/stats.jsonl` rows (`bkit workflows close`, `bkit comply`). */
380
399
  const CLOSING_WORKFLOWS = new Set(["design", "plan", "build", "debug", "ship"]);
381
400
 
401
+ /**
402
+ * The stats writers: the closing workflows, plus `utility`, a direct chat outside any
403
+ * workflow (`by.step` `manual`), the owner deciding in it.
404
+ */
405
+ const STATS_WRITERS = new Set([...CLOSING_WORKFLOWS, "utility"]);
406
+
382
407
  /**
383
408
  * `.bkit/jsonl.md` § Ledgers & Writers as code, for the kinds in
384
409
  * {@link APPEND_LEDGERS}. EXHAUSTIVE: a name absent from a set does not write the
@@ -392,31 +417,37 @@ export const KIND_WRITERS: Record<AppendKind, KindWriters> = {
392
417
  "bkit-plan-update",
393
418
  "bkit-utility-update-decisions",
394
419
  ]),
395
- // Build: Decision Pause accept; plan: an open question answered after close; ship: an
396
- // assumed accept the owner confirms (`bkit decisions apply --by=owner`). All ONLY after
397
- // explicit human approval.
398
- orchestrators: new Set(["build", "plan", "ship"]),
420
+ // Build: Decision Pause accept; plan: an open question answered after close; design: an
421
+ // open question answered by the owner at close (the human decides, the orchestrator
422
+ // records); ship: an assumed accept the owner confirms (`bkit decisions apply --by=owner`);
423
+ // utility: a direct chat outside any workflow (`by.step` `manual`), the owner deciding in it.
424
+ // All ONLY after explicit human approval.
425
+ orchestrators: new Set(["design", "build", "plan", "ship", "utility"]),
399
426
  },
400
427
  // Build: `bkit challenge merge` writes each LOW challenge finding (`low-severity`). Ship:
401
428
  // `bkit decisions pending --defer` writes each assumed accept nobody confirmed (`needs-decision`).
402
- deferral: { subagents: DEFERRAL_WRITERS, orchestrators: new Set(["build", "ship"]) },
429
+ // Utility: a direct chat outside any workflow (`by.step` `manual`), the owner deciding in it.
430
+ deferral: { subagents: DEFERRAL_WRITERS, orchestrators: new Set(["build", "ship", "utility"]) },
403
431
  failure: { subagents: ANY_WRITER, orchestrators: ANY_WRITER },
404
432
  knowledge: {
405
433
  subagents: new Set([
406
- "bkit-build-plan-execute",
434
+ "bkit-build-plan-tests",
435
+ "bkit-build-plan-tasks",
407
436
  "bkit-build-plan-gaps-remediate",
408
437
  "bkit-debug-failure-remediate",
409
438
  "bkit-utility-update-knowledge",
410
439
  ]),
411
- orchestrators: new Set(),
440
+ // Utility: a direct chat outside any workflow (`by.step` `manual`), the owner deciding in it.
441
+ orchestrators: new Set(["utility"]),
412
442
  },
413
443
  friction: {
414
444
  subagents: new Set(),
415
- orchestrators: new Set(["design", "plan", "build", "debug", "ship"]),
445
+ // Utility: a direct chat outside any workflow (`by.step` `manual`) that meets friction.
446
+ orchestrators: new Set(["design", "plan", "build", "debug", "ship", "auto", "utility"]),
416
447
  },
417
- compliance: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
418
- counter: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
419
- outcome: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
448
+ compliance: { subagents: new Set(), orchestrators: STATS_WRITERS },
449
+ counter: { subagents: new Set(), orchestrators: STATS_WRITERS },
450
+ outcome: { subagents: new Set(), orchestrators: STATS_WRITERS },
420
451
  };
421
452
 
422
453
  const writerList = (w: KindWriters["subagents"]): string =>
@@ -584,7 +615,7 @@ export interface ContextBlock {
584
615
  byAgent: Record<string, { peak: number; runs: number }>;
585
616
  }
586
617
 
587
- export const OUTCOME_ENDINGS: Set<string> = new Set(["done", "close-failed"]);
618
+ export const OUTCOME_ENDINGS: Set<string> = new Set(["done", "close-failed", "held"]);
588
619
 
589
620
  // outcome — one row per WORKFLOW RUN, keyed by (repo, by.workflow, run.parentSha), written
590
621
  // by `bkit workflows close`. Blocks that do not apply to the workflow are absent.
@@ -592,8 +623,13 @@ export interface OutcomePayload {
592
623
  run: RunRef;
593
624
  /** null when the run's start row is missing. */
594
625
  time: TimeBlock | null;
595
- /** `close-failed` = the work finished and the close after it did not (its CI never started). */
596
- ending: "done" | "close-failed";
626
+ /**
627
+ * `close-failed` = the work finished and the close after it did not (its CI never started);
628
+ * `held` = a local build that published nothing.
629
+ */
630
+ ending: "done" | "close-failed" | "held";
631
+ /** A build's resolved publish value; `false` with `held`. */
632
+ publish?: boolean;
597
633
  lines?: LinesBlock | null;
598
634
  steps?: StepsBlock;
599
635
  ci?: CiDispatch[];
@@ -683,7 +719,7 @@ export interface FailurePayload {
683
719
  /**
684
720
  * Free-form domain tag (mirrors DeferralPayload.category; see § Categories in
685
721
  * .bkit/jsonl.md). `"testing"` marks a flaky / intermittent test — recurrence
686
- * via same-`key` append is the flake signal; no extra fields. See § Categories.
722
+ * via same-`key` append is the flake signal, counted by `updates`. See § Categories.
687
723
  */
688
724
  category?: string;
689
725
  summary?: string;
@@ -774,7 +810,7 @@ export interface RunPayload {
774
810
  parentShas: string[];
775
811
  };
776
812
  time: TimeBlock;
777
- ending: "done" | "close-failed" | "failed" | "decision-pause" | "stopped";
813
+ ending: "done" | "close-failed" | "failed" | "decision-pause" | "stopped" | "held";
778
814
  scan: { rows: number; afterEnd: number; settled: boolean };
779
815
  [field: string]: unknown;
780
816
  }
@@ -785,6 +821,7 @@ export const RUN_ENDINGS: Set<string> = new Set([
785
821
  "failed",
786
822
  "decision-pause",
787
823
  "stopped",
824
+ "held",
788
825
  ]);
789
826
 
790
827
  // ---------------------------------------------------------------------------
@@ -1357,7 +1394,7 @@ export function totalsProblem(row: Obj): string | undefined {
1357
1394
  eq(
1358
1395
  "build.redTests",
1359
1396
  build["redTests"],
1360
- Number(field(steps, "byStep", "build-task-red", "n") ?? 0),
1397
+ Number(field(steps, "byStep", "build-tests-red", "n") ?? 0),
1361
1398
  ),
1362
1399
  );
1363
1400
  }
@@ -1613,6 +1650,22 @@ export function validate(event: unknown): ValidationResult {
1613
1650
  return { ok: false, reason: `${kind} rows do not carry reason` };
1614
1651
  }
1615
1652
 
1653
+ // firstTs / updates — the entry's age and row count, set by the writer (withLineage).
1654
+ if (AGED_KINDS.has(kind)) {
1655
+ const first = e["firstTs"];
1656
+ if (first !== undefined && (typeof first !== "number" || !(first <= (e["ts"] as number)))) {
1657
+ return { ok: false, reason: "firstTs must be a number no later than ts" };
1658
+ }
1659
+ const updates = e["updates"];
1660
+ if (updates !== undefined && (!Number.isInteger(updates) || (updates as number) < 1)) {
1661
+ return { ok: false, reason: "updates must be a positive integer" };
1662
+ }
1663
+ } else {
1664
+ for (const f of ["firstTs", "updates"]) {
1665
+ if (e[f] !== undefined) return { ok: false, reason: `${kind} rows do not carry ${f}` };
1666
+ }
1667
+ }
1668
+
1616
1669
  const run = isObj(e["run"]) ? e["run"] : undefined;
1617
1670
  if (kind === "compliance" || kind === "counter") {
1618
1671
  if (typeof run?.["parentSha"] !== "string" || run["parentSha"] === "") {
@@ -1667,7 +1720,13 @@ export function validate(event: unknown): ValidationResult {
1667
1720
  if (!OUTCOME_ENDINGS.has(e["ending"] as string)) {
1668
1721
  return {
1669
1722
  ok: false,
1670
- reason: `outcome ending must be done|close-failed (got: ${String(e["ending"])})`,
1723
+ reason: `outcome ending must be ${[...OUTCOME_ENDINGS].join("|")} (got: ${String(e["ending"])})`,
1724
+ };
1725
+ }
1726
+ if (e["publish"] !== undefined && typeof e["publish"] !== "boolean") {
1727
+ return {
1728
+ ok: false,
1729
+ reason: `outcome publish must be a boolean (got: ${String(e["publish"])})`,
1671
1730
  };
1672
1731
  }
1673
1732
  const ledgers = e["ledgers"];
@@ -1871,6 +1930,84 @@ export function fold(events: TelemetryEvent[]): FoldedState {
1871
1930
  return state;
1872
1931
  }
1873
1932
 
1933
+ // ---------------------------------------------------------------------------
1934
+ // Lineage — the entry age + row count a fold winner carries (AGED_KINDS)
1935
+ // ---------------------------------------------------------------------------
1936
+
1937
+ export interface Lineage {
1938
+ /** Earliest `ts` / `firstTs` among the entry's rows; absent when none is a number. */
1939
+ firstTs?: number;
1940
+ /** Rows the entry has had. */
1941
+ updates: number;
1942
+ }
1943
+
1944
+ const positiveInt = (v: unknown): number | undefined =>
1945
+ Number.isInteger(v) && (v as number) > 0 ? (v as number) : undefined;
1946
+
1947
+ /**
1948
+ * `firstTs` + `updates` of one entry from all of its rows, in any order. A row
1949
+ * carrying `updates` stands for that many rows, so the count survives compaction;
1950
+ * each later row adds one. Rows sharing a numeric `ts` are one write: a compacted
1951
+ * winner beside the pre-compaction copy a union merge brought back.
1952
+ */
1953
+ export function lineage(
1954
+ rows: ReadonlyArray<{ ts?: unknown; firstTs?: unknown; updates?: unknown }>,
1955
+ ): Lineage {
1956
+ let firstTs: number | undefined;
1957
+ let updates = 0;
1958
+ let prev: number | undefined;
1959
+ for (const r of [...rows].sort((a, b) => compareTs({ ts: a.ts }, { ts: b.ts }))) {
1960
+ for (const t of [r.firstTs, r.ts]) {
1961
+ if (typeof t === "number" && Number.isFinite(t) && (firstTs === undefined || t < firstTs)) {
1962
+ firstTs = t;
1963
+ }
1964
+ }
1965
+ const own = positiveInt(r.updates);
1966
+ const at = tsOrder(r.ts);
1967
+ updates =
1968
+ at === prev && Number.isFinite(at)
1969
+ ? Math.max(updates, own ?? updates)
1970
+ : Math.max(own ?? 0, updates + 1);
1971
+ prev = at;
1972
+ }
1973
+ return firstTs === undefined ? { updates } : { firstTs, updates };
1974
+ }
1975
+
1976
+ /** `row` with `firstTs` + `updates` set to `l`, placed right after `ts` (at the end when it has none). */
1977
+ export function placeLineage(row: Record<string, unknown>, l: Lineage): Record<string, unknown> {
1978
+ const fields: Record<string, unknown> = l.firstTs === undefined ? {} : { firstTs: l.firstTs };
1979
+ fields["updates"] = l.updates;
1980
+ const out: Record<string, unknown> = {};
1981
+ for (const [k, v] of Object.entries(row)) {
1982
+ if (k === "firstTs" || k === "updates") continue;
1983
+ out[k] = v;
1984
+ if (k === "ts") Object.assign(out, fields);
1985
+ }
1986
+ return "ts" in row ? out : { ...out, ...fields };
1987
+ }
1988
+
1989
+ /** True for a row `bkit ledgers compact` folds: an {@link AGED_KINDS} kind with a non-empty string `key`. */
1990
+ export const isAgedRow = (row: Record<string, unknown>): boolean =>
1991
+ AGED_KINDS.has(String(row["kind"])) && typeof row["key"] === "string" && row["key"] !== "";
1992
+
1993
+ /**
1994
+ * `row` about to be appended, with `firstTs` + `updates` carried forward from
1995
+ * `prior` (rows already in its ledger) and any supplied values replaced. A row
1996
+ * {@link isAgedRow} rejects is returned unchanged.
1997
+ */
1998
+ export function withLineage(
1999
+ prior: readonly unknown[],
2000
+ row: Record<string, unknown>,
2001
+ ): Record<string, unknown> {
2002
+ if (!isAgedRow(row)) return row;
2003
+ const id = identity(normalizeEvent(row));
2004
+ const same = prior
2005
+ .map(normalizeEvent)
2006
+ .filter((p) => isAgedRow(p as Record<string, unknown>) && identity(p) === id);
2007
+ const { firstTs: _first, updates: _updates, ...fresh } = row;
2008
+ return placeLineage(row, lineage([...same, fresh]));
2009
+ }
2010
+
1874
2011
  // ---------------------------------------------------------------------------
1875
2012
  // FoldFrom — reads ledger files, returns combined fold
1876
2013
  // ---------------------------------------------------------------------------
@@ -2093,7 +2230,7 @@ export function workflowTelemetry(result: FoldFromResult, workflow?: string): Te
2093
2230
  show("lines.total.files", (r) => r.lines?.total?.files);
2094
2231
  }
2095
2232
  show("plan.total.tasks", (r) => r.plan?.total?.tasks);
2096
- if (cur.ending === "close-failed") row("ending", "close-failed", "—");
2233
+ if (cur.ending === "close-failed" || cur.ending === "held") row("ending", cur.ending, "—");
2097
2234
  // Instinct-loop deltas — friction is the featured signal (shown even at 0).
2098
2235
  show("ledgers.friction.added", (r) => r.ledgers?.friction?.added);
2099
2236
  show("ledgers.deferrals.added", (r) => r.ledgers?.deferrals?.added);