@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,10 +1,10 @@
1
1
  // checks/status-holes.ts — Tier-3 advisory status-hole detector.
2
2
  //
3
- // A fail-open advisory that compares the set of ship steps RECORDED in a
4
- // status.jsonl against the set of steps the workflow PROSE says should be
5
- // there. It derives its expected set from .bkit/core/workflows/bkit-ship.md at
6
- // runtime (headings + step:"ship-*" literals) — NEVER a hand-maintained table
7
- // (decision 384-tier3-promotion).
3
+ // A fail-open advisory that compares the steps RECORDED in each run of a
4
+ // status.jsonl against the steps the workflow PROSE says should be there. It
5
+ // derives the expected set from .bkit/core/workflows/bkit-{workflow}.md at
6
+ // runtime (headings + --step= literals) — NEVER a hand-maintained table
7
+ // (decision 384-tier3-promotion). Each run's workflow is inferred from its rows.
8
8
  //
9
9
  // ADVISORY / FAIL-OPEN: the CLI exits 0 unconditionally — even when holes are
10
10
  // found (decision 384-tier3-promotion).
@@ -20,15 +20,20 @@
20
20
  // appear only in the merge-retry loop.
21
21
  //
22
22
  // Usage (advisory CI step or manual):
23
- // npx tsx .bkit/core/engine/checks/status-holes.ts <status.jsonl> [--ship-md <path>]
23
+ // npx tsx .bkit/core/engine/checks/status-holes.ts <status.jsonl>...
24
24
  // # exits 0 always; prints advisory report to stdout
25
25
 
26
+ import { createHash } from "node:crypto";
26
27
  import * as fs from "node:fs";
27
28
  import * as path from "node:path";
28
29
  import { fileURLToPath } from "node:url";
29
30
 
31
+ import { DECISION_ROUTES, WORKFLOW_STEPS } from "../commands/workflow/step-table.js";
32
+ import type { IssueTracker } from "../install/manifest.js";
33
+ import { substituteWorkflow } from "../render/trackers.js";
30
34
  import { parseJson } from "../shared/json.js";
31
35
  import { getWorkflowsRoot } from "../shared/package-roots.js";
36
+ import { ciRoundMatches } from "../ledgers/status.js";
32
37
 
33
38
  // ---------------------------------------------------------------------------
34
39
  // Canonical ship step order (mirrors audits/workflows/ship-invariants.test.ts
@@ -86,7 +91,8 @@ const MERGED_ON_ENTRY_SKIP = new Set<string>([
86
91
  // Types
87
92
  // ---------------------------------------------------------------------------
88
93
 
89
- export type RunPath = "PATH_A" | "PATH_B" | "MERGED_ON_ENTRY" | "ABORTED" | "IN_PROGRESS";
94
+ export type RunPath =
95
+ "PATH_A" | "PATH_B" | "MERGED_ON_ENTRY" | "COMPLETED" | "ABORTED" | "IN_PROGRESS";
90
96
 
91
97
  export interface StatusRow {
92
98
  type: string;
@@ -98,6 +104,8 @@ export interface StatusRow {
98
104
  }
99
105
 
100
106
  export interface HoleReport {
107
+ /** The workflow the run belongs to. */
108
+ workflow?: string;
101
109
  /** Steps the prose says should be present but were not recorded. */
102
110
  missing: string[];
103
111
  /** Steps recorded but NOT in the source-derived universe (invented names). */
@@ -115,88 +123,797 @@ export interface HoleReport {
115
123
  }
116
124
 
117
125
  // ---------------------------------------------------------------------------
118
- // Source derivation — parse bkit-ship.md to find the expected step universe.
126
+ // Contract derivation — parse the workflow markdown into steps + required calls.
119
127
  // ---------------------------------------------------------------------------
120
128
 
129
+ /** One `"{BKIT}" noun verb --flag` call the markdown names, reduced to words (flag values dropped). */
130
+ export interface RequiredCall extends WorkflowCall {
131
+ /** `post` when written below the section's last `steps finish` / `steps done --step=` line off every route arm. */
132
+ position: "pre" | "post";
133
+ /** R1: under a `- **If**` / `- **Else**` bullet or `N. **If**` sub-step, in a sub-step a route line names as its target, or in a `**Name:**` block an `**If**` line picks. */
134
+ branch: boolean;
135
+ }
136
+
137
+ export interface WorkflowCall {
138
+ noun: string;
139
+ verb: string;
140
+ flags: string[];
141
+ }
142
+
143
+ export interface ContractStep {
144
+ number: number;
145
+ title: string;
146
+ /** The `--step=` / `step:"` row keys the section writes. */
147
+ keys: string[];
148
+ /** The subset of `keys` the section writes: `steps finish|done --step=` and `step:"` literals. */
149
+ writes: string[];
150
+ /** Every `"{BKIT}"` call in the section, in order. */
151
+ calls: RequiredCall[];
152
+ /** True under a column-0 `**Run only if**` / `**Skip if**` line, or a `(Path X only)` heading. */
153
+ conditional: boolean;
154
+ }
155
+
156
+ export interface Contract {
157
+ workflow: string;
158
+ steps: ContractStep[];
159
+ /** Deduped row keys across the step sections, sorted. */
160
+ universe: string[];
161
+ /** Calls in sections no step owns (opening lines, Failure Path, Decision Pause ...). */
162
+ workflowCalls: WorkflowCall[];
163
+ /** `ANYWHERE_CALLS` the `**Contract:**` block names; matched like `workflowCalls`, never required. */
164
+ anywhereCalls: WorkflowCall[];
165
+ /** sha256 of the workflow markdown the contract was derived from. */
166
+ sourceSha: string;
167
+ /** Decision Pause row keys (`DECISION_ROUTES`) the markdown writes outside every numbered step. */
168
+ pauseRows: string[];
169
+ /** Row keys an engine verb a step calls writes on that step's behalf (`VERB_ROWS`). */
170
+ subRows: string[];
171
+ /** Row keys written outside every numbered step section, other than `pauseRows`. */
172
+ orphanSteps: string[];
173
+ /** Disagreements with the deduped `WORKFLOW_STEPS[workflow]` keys; reported, never fatal. */
174
+ drift: string[];
175
+ }
176
+
121
177
  /**
122
- * Derive the universe of ship step keys from the workflow markdown.
123
- *
124
- * Strategy:
125
- * 1. Extract every `step:"ship-..."` literal from fenced code blocks.
126
- * 2. Extract every `## … Step N — Name` heading and map the heading's section
127
- * to the step key(s) found within it.
128
- * 3. Return the union of all unique step keys.
129
- *
130
- * The two passes scan the SAME `step:"ship-*"` regex and the heading pass only
131
- * narrows the line range, so `headingSteps` is always a subset of `literalSteps`.
132
- * The detector reports `orphanSteps`: a status write that appears in the file but NOT
133
- * inside any `## … Step N` section.
178
+ * Step rows an engine verb writes itself, keyed by noun + verb: `tests red` writes the
179
+ * `RED_STEP` row of `commands/workflow/tests.ts` inside build Step 7.
134
180
  */
135
- export function deriveExpectedStepSetFromSource(shipMd: string): {
136
- steps: string[];
137
- headingSteps: string[];
138
- literalSteps: string[];
139
- orphanSteps: string[];
140
- } {
141
- const lines = shipMd.split("\n");
142
-
143
- // 1. Collect every `step:"ship-..."` / `--step=ship-...` literal (anywhere — fenced or prose).
144
- const literalSet = new Set<string>();
145
- const literalRe = /(?:step:"|--step=)(ship-[a-z-]+)/g;
146
- for (const line of lines) {
147
- let m: RegExpExecArray | null;
148
- while ((m = literalRe.exec(line)) !== null) {
149
- literalSet.add(m[1]);
181
+ const VERB_ROWS: Readonly<Record<string, readonly string[]>> = {
182
+ "tests red": ["build-tests-red"],
183
+ };
184
+ // A step that reads a verb row (`counters derive --step=build-tests-red`) does not own it.
185
+ const VERB_ROW_KEYS: ReadonlySet<string> = new Set(Object.values(VERB_ROWS).flat());
186
+
187
+ /**
188
+ * Calls the orchestrator may run at any point of a run, active when the workflow's
189
+ * `**Contract:**` block names them as `` `bkit {noun} {verb}` `` (the **Friction** bullet's
190
+ * `bkit ledgers append`). The Contract also names step-bound calls, so it is not read wholesale.
191
+ */
192
+ const ANYWHERE_CALLS: readonly string[] = ["ledgers append"];
193
+
194
+ // A key followed by `{` is a templated log label (`build-group-gate-{GROUP}`), not a row key.
195
+ const STEP_KEY_RE = /(?:step:"|--step=)([a-z][a-z0-9-]*)(\{)?/g;
196
+
197
+ /** The words of one `"{BKIT}" ...` call: shell-split, quotes kept, stopped at the first unquoted operator. */
198
+ export function callWords(rest: string): string[] {
199
+ const words: string[] = [];
200
+ let word = "";
201
+ let quote = "";
202
+ for (const ch of rest) {
203
+ if (quote) {
204
+ word += ch;
205
+ if (ch === quote) quote = "";
206
+ } else if (ch === '"' || ch === "'") {
207
+ word += ch;
208
+ quote = ch;
209
+ } else if ("|;&><)`".includes(ch)) break;
210
+ else if (/\s/.test(ch)) {
211
+ if (word) words.push(word);
212
+ word = "";
213
+ } else word += ch;
214
+ }
215
+ if (word) words.push(word);
216
+ return words;
217
+ }
218
+
219
+ /** Each `Step N — Title` heading, with the text up to the next step or section heading. */
220
+ export function stepSections(text: string): Array<{ number: number; title: string; body: string }> {
221
+ const lines = text.split("\n");
222
+ const heading = /^#{2,3} \S+ Step (\d+) — (.+)$/;
223
+ const out: Array<{ number: number; title: string; body: string }> = [];
224
+ lines.forEach((l, i) => {
225
+ const m = heading.exec(l);
226
+ if (!m) return;
227
+ const end = lines.findIndex((x, j) => j > i && /^#{2,3} /.test(x) && !x.startsWith("### 🔒"));
228
+ out.push({
229
+ number: Number(m[1]),
230
+ title: m[2]!,
231
+ body: lines.slice(i, end === -1 ? undefined : end).join("\n"),
232
+ });
233
+ });
234
+ return out;
235
+ }
236
+
237
+ /** Each `"{BKIT}"` call in `text` as noun / verb / flag names. */
238
+ function requiredCalls(text: string): WorkflowCall[] {
239
+ const joined = text.replace(/\\\n\s*/g, " ");
240
+ return joined
241
+ .split('"{BKIT}"')
242
+ .slice(1)
243
+ .map((call) => {
244
+ const [noun = "", verb = "", ...rest] = callWords(call.replace(/^ /, ""));
245
+ const flags = rest.flatMap((w) => {
246
+ const f = /^--([a-z][a-z0-9-]*)/.exec(w)?.[1];
247
+ return f ? [f] : [];
248
+ });
249
+ return { noun, verb: verb.startsWith("--") ? "" : verb, flags };
250
+ });
251
+ }
252
+
253
+ /** R1: per line of a step section, true when it sits on an `If` / `Else` arm. */
254
+ function branchLines(lines: string[]): boolean[] {
255
+ const branch = lines.map(() => false);
256
+ const targets = new Set<number>();
257
+ const blocks = new Set<string>();
258
+ let ifIndent: number | null = null;
259
+ lines.forEach((l, i) => {
260
+ if (l.trim() === "") {
261
+ branch[i] = ifIndent !== null;
262
+ return;
150
263
  }
151
- literalRe.lastIndex = 0; // reset per-line
264
+ const indent = l.length - l.trimStart().length;
265
+ if (ifIndent !== null && indent <= ifIndent) ifIndent = null;
266
+ if (/^\s*(?:- |\d+\. )\*\*(If|Else)\*\*/.test(l)) ifIndent = indent;
267
+ branch[i] = ifIndent !== null;
268
+ if (/\*\*(If|Else)\*\*/.test(l)) {
269
+ for (const m of l.matchAll(/sub-step (\d+)/g)) targets.add(Number(m[1]));
270
+ for (const m of l.matchAll(/→ \*\*([^*]+)\*\*/g)) blocks.add(m[1]!);
271
+ }
272
+ });
273
+ let sub: number | null = null;
274
+ let block = false;
275
+ lines.forEach((l, i) => {
276
+ const m = /^(\d+)\. /.exec(l);
277
+ if (m) sub = Number(m[1]);
278
+ else if (l.startsWith("#")) sub = null;
279
+ if (sub !== null && targets.has(sub)) branch[i] = true;
280
+ // A `**Name:**` block an `**If**` line routes to runs to the next such block or heading.
281
+ const label = /^\*\*([^*]+):\*\*/.exec(l)?.[1];
282
+ if (label !== undefined && blocks.has(label)) block = true;
283
+ else if (/^#{2,} /.test(l)) block = false;
284
+ if (block) branch[i] = true;
285
+ });
286
+ return branch;
287
+ }
288
+
289
+ /**
290
+ * Per `"{BKIT}"` call in `text`, true when it sits after an inline `**If** … →` / `**Else** →`
291
+ * in the same sentence (`→ add `Group gate`: `"{BKIT}" tests run …``). A call in the fence
292
+ * below such a line stays required: there the condition may only change the call.
293
+ */
294
+ function inlineArms(text: string): boolean[] {
295
+ const parts = text.split('"{BKIT}"');
296
+ return parts.slice(1).map((_, i) => {
297
+ const before = parts.slice(0, i + 1).join('"{BKIT}"');
298
+ const lead = [...before.matchAll(/\*\*(?:If|Else)\*\*/g)].at(-1);
299
+ if (lead?.index === undefined) return false;
300
+ const clause = before.slice(lead.index).replace(/`[^`]*`/g, "");
301
+ return clause.includes("→") && !/\.\s/.test(clause);
302
+ });
303
+ }
304
+
305
+ /** The `"{BKIT}"` calls of one step section, each tagged with its position (R3) and branch flag (R1). */
306
+ function sectionCalls(body: string): Array<RequiredCall & { line: number }> {
307
+ const lines = body.split("\n");
308
+ const branch = branchLines(lines);
309
+ const logical: Array<{ text: string; branch: boolean }> = [];
310
+ for (let i = 0; i < lines.length; i++) {
311
+ let text = lines[i]!;
312
+ const start = i;
313
+ while (text.endsWith("\\") && i + 1 < lines.length) {
314
+ i += 1;
315
+ text = `${text.slice(0, -1)} ${lines[i]!.trimStart()}`;
316
+ }
317
+ logical.push({ text, branch: branch[start]! });
152
318
  }
319
+ const perLine = logical.map((l) => requiredCalls(l.text));
320
+ const isFinish = (c: WorkflowCall) =>
321
+ c.noun === "steps" && (c.verb === "finish" || (c.verb === "done" && c.flags.includes("step")));
322
+ // An optional finish below the step's own (a route arm's row) does not move the line.
323
+ const finishes = perLine.flatMap((calls, i) => (calls.some(isFinish) ? [i] : []));
324
+ const plain = finishes.filter((i) => !logical[i]!.branch);
325
+ const lastFinish = (plain.length > 0 ? plain : finishes).at(-1) ?? -1;
326
+ return perLine.flatMap((calls, i) => {
327
+ const inline = inlineArms(logical[i]!.text);
328
+ return calls.map((c, j) => ({
329
+ ...c,
330
+ position: i > lastFinish && lastFinish !== -1 ? ("post" as const) : ("pre" as const),
331
+ branch: logical[i]!.branch || inline[j]!,
332
+ line: i,
333
+ }));
334
+ });
335
+ }
153
336
 
154
- // 2. Collect heading-derived steps. A `## … Step N` heading opens a section;
155
- // the step key(s) within that section's body (until the next `## ` heading)
156
- // belong to that step.
157
- const headingSet = new Set<string>();
158
- let inStep = false;
159
- for (const line of lines) {
160
- if (/^##\s+.*Step\s+\d+/i.test(line)) {
161
- inStep = true;
162
- continue;
337
+ /** Row keys a section writes (not merely names in a `steps gate --step=` read). */
338
+ function stepWrites(text: string): string[] {
339
+ const joined = text.replace(/\\\n\s*/g, " ");
340
+ const found = joined.split("\n").flatMap((line) => {
341
+ const viaCall = /"\{BKIT\}" steps (?:finish|done)\b/.test(line) ? stepKeys(line) : [];
342
+ return [...viaCall, ...[...line.matchAll(/step:"([a-z][a-z0-9-]*)"/g)].map((m) => m[1]!)];
343
+ });
344
+ return [...new Set(found)];
345
+ }
346
+
347
+ const stepKeys = (text: string): string[] => [
348
+ ...new Set([...text.matchAll(STEP_KEY_RE)].filter((m) => !m[2]).map((m) => m[1]!)),
349
+ ];
350
+
351
+ /** A step is conditional under a column-0 marker line anywhere in its section, or a `(Path X only)` heading. */
352
+ export function isConditionalSection(body: string): boolean {
353
+ const lines = body.split("\n");
354
+ return (
355
+ /\(Path [A-Z] only\)/.test(lines[0] ?? "") ||
356
+ lines.some((l) => /^\*\*(Run only if|Skip if)\*\*/.test(l))
357
+ );
358
+ }
359
+
360
+ /**
361
+ * Derive the contract of one workflow from its markdown: the step sections, the
362
+ * row keys and `"{BKIT}"` calls each holds, and the calls no step owns. The
363
+ * universe is cross-checked against the deduped `WORKFLOW_STEPS[workflow]`; a
364
+ * disagreement is reported as drift, never thrown. With a `tracker`, the markdown is
365
+ * first rendered for it, so a consumer is held to the calls its installed workflow names.
366
+ */
367
+ export function deriveContract(
368
+ sourceMd: string,
369
+ workflow: string,
370
+ tracker?: IssueTracker,
371
+ ): Contract {
372
+ const workflowMd =
373
+ tracker === undefined ? sourceMd : substituteWorkflow(sourceMd, tracker).output;
374
+ const sections = stepSections(workflowMd);
375
+ // The journal window runs from the first `workflows start` call to the `workflows close`
376
+ // call: a call written above or below it is matched when journaled, never required.
377
+ const lineOf = (offset: number) => workflowMd.slice(0, offset).split("\n").length - 1;
378
+ const absLine = (s: { body: string }, line: number) => lineOf(workflowMd.indexOf(s.body)) + line;
379
+ const marks = (noun: string, verb: string) =>
380
+ sections.flatMap((s) =>
381
+ sectionCalls(s.body)
382
+ .filter((c) => c.noun === noun && c.verb === verb)
383
+ .map((c) => absLine(s, c.line)),
384
+ );
385
+ const starts = marks("workflows", "start");
386
+ const closes = marks("workflows", "close");
387
+ const windowStart = starts.length > 0 ? Math.min(...starts) : -1;
388
+ const windowEnd = closes.length > 0 ? Math.max(...closes) : Number.POSITIVE_INFINITY;
389
+ const outsideWindow: WorkflowCall[] = [];
390
+ const steps: ContractStep[] = sections.map((s) => {
391
+ const inside: RequiredCall[] = [];
392
+ for (const { line, ...c } of sectionCalls(s.body)) {
393
+ const at = absLine(s, line);
394
+ // `workflows start` itself is outside: a fresh run has no active run to journal it under.
395
+ const isStart = c.noun === "workflows" && c.verb === "start";
396
+ if (isStart || at < windowStart || at > windowEnd) outsideWindow.push(c);
397
+ else inside.push(c);
163
398
  }
164
- if (/^##\s+/m.test(line) && !/Step\s+\d+/i.test(line)) {
165
- inStep = false;
166
- continue;
399
+ return {
400
+ number: s.number,
401
+ title: s.title,
402
+ keys: stepKeys(s.body).filter((k) => !VERB_ROW_KEYS.has(k)),
403
+ writes: stepWrites(s.body),
404
+ calls: inside,
405
+ conditional: isConditionalSection(s.body),
406
+ };
407
+ });
408
+ const universe = [...new Set(steps.flatMap((s) => s.keys))].sort();
409
+
410
+ // Text outside every step section: the md minus each section body.
411
+ let outside = workflowMd;
412
+ for (const s of sections) outside = outside.replace(s.body, "");
413
+ const table = (WORKFLOW_STEPS as Record<string, readonly { step?: string }[] | undefined>)[
414
+ workflow
415
+ ];
416
+ const tableKeys = new Set((table ?? []).flatMap((s) => (s.step ? [s.step] : [])));
417
+ const drift: string[] = [];
418
+ if (table) {
419
+ for (const k of tableKeys) if (!universe.includes(k)) drift.push(`table-but-not-source:${k}`);
420
+ for (const k of universe) if (!tableKeys.has(k)) drift.push(`source-but-not-table:${k}`);
421
+ }
422
+ const outsideKeys = stepKeys(outside).filter(
423
+ (k) => k.startsWith(`${workflow}-`) && !universe.includes(k),
424
+ );
425
+ const pause = (DECISION_ROUTES as Record<string, { step: string } | undefined>)[workflow]?.step;
426
+ const pauseRows = pause !== undefined && outsideKeys.includes(pause) ? [pause] : [];
427
+ const named = new Set(sections.flatMap((s) => sectionCalls(s.body)).map(callKey));
428
+ const contractBlock =
429
+ /^\*\*Contract:\*\*[\s\S]*?(?=^#{1,3} |(?![\s\S]))/m.exec(workflowMd)?.[0] ?? "";
430
+ const anywhereCalls = ANYWHERE_CALLS.filter((call) =>
431
+ contractBlock.includes(`\`bkit ${call}\``),
432
+ ).map((call) => {
433
+ const [noun = "", verb = ""] = call.split(" ");
434
+ return { noun, verb, flags: [] };
435
+ });
436
+ const subRows = Object.entries(VERB_ROWS)
437
+ .filter(([call]) => named.has(call))
438
+ .flatMap(([, keys]) => keys.filter((k) => k.startsWith(`${workflow}-`)));
439
+ return {
440
+ workflow,
441
+ steps,
442
+ universe,
443
+ workflowCalls: [...requiredCalls(outside), ...outsideWindow],
444
+ anywhereCalls,
445
+ sourceSha: createHash("sha256").update(workflowMd).digest("hex"),
446
+ pauseRows,
447
+ subRows,
448
+ orphanSteps: outsideKeys.filter((k) => !pauseRows.includes(k)).sort(),
449
+ drift,
450
+ };
451
+ }
452
+
453
+ // ---------------------------------------------------------------------------
454
+ // Completeness check — rows + contract → verdict
455
+ // ---------------------------------------------------------------------------
456
+
457
+ export interface CallRef {
458
+ noun: string;
459
+ verb: string;
460
+ }
461
+
462
+ export interface EvidenceHole {
463
+ step: string;
464
+ number: number;
465
+ /** 1-based occurrence among the run's rows for this step (group-loop and retry repeats). */
466
+ index: number;
467
+ group?: number;
468
+ missing: WorkflowCall[];
469
+ }
470
+
471
+ export interface CompletenessVerdict {
472
+ workflow: string;
473
+ verdict: "CLEAN" | "HOLEY";
474
+ /** True on an evidence hole or a step hole; unexercised arms never count. */
475
+ holey: boolean;
476
+ preJournal: boolean;
477
+ journalSuspect: boolean;
478
+ observed: { steps: number; calls: number };
479
+ evidenceHoles: EvidenceHole[];
480
+ stepHoles: string[];
481
+ unexercised: Array<{ step: string; call: CallRef }>;
482
+ unexpected: Array<CallRef | { step: string }>;
483
+ unattributable: CallRef[];
484
+ sourceSha: string;
485
+ workflowCalls: CallRef[];
486
+ }
487
+
488
+ export interface CheckOptions {
489
+ /** True when the closing engine itself journals (close path only). */
490
+ journalSuspect?: boolean;
491
+ }
492
+
493
+ /** The `completeness` verb journals itself; it is neither expected nor ever unexpected. */
494
+ const SELF_NOUN = "completeness";
495
+
496
+ const callKey = (c: CallRef): string => `${c.noun} ${c.verb}`;
497
+
498
+ /**
499
+ * One row-owning unit of a contract. A key belongs to the first section that writes it
500
+ * (else the last that names it); a later writer lists it as `shared`. A section owning
501
+ * no key folds its calls into the section owning its first key, so a step whose row
502
+ * another section writes is still checked as one unit (design Step 1 folds into Step 2).
503
+ */
504
+ export interface Unit {
505
+ number: number;
506
+ /** Row keys this unit owns, in section order. */
507
+ keys: string[];
508
+ /** Row keys this unit also writes that another unit owns (build Step 9 rewrites `build-plan-tests`). */
509
+ shared: string[];
510
+ calls: RequiredCall[];
511
+ conditional: boolean;
512
+ }
513
+
514
+ export function contractUnits(contract: Contract): Unit[] {
515
+ const owner = new Map<string, ContractStep>();
516
+ for (const k of contract.universe) {
517
+ const writers = contract.steps.filter((s) => s.writes.includes(k));
518
+ const namers = contract.steps.filter((s) => s.keys.includes(k));
519
+ const first = writers.length > 0 ? writers[0] : namers.at(-1);
520
+ if (first) owner.set(k, first);
521
+ }
522
+ const owners = contract.steps.filter((s) => [...owner.values()].includes(s));
523
+ return owners.map((s) => {
524
+ const keys = s.keys.filter((k) => owner.get(k) === s);
525
+ const folded = contract.steps.filter(
526
+ (f) => !owners.includes(f) && f.keys[0] !== undefined && owner.get(f.keys[0]) === s,
527
+ );
528
+ const calls = [
529
+ ...folded.filter((f) => f.number < s.number).flatMap((f) => f.calls),
530
+ ...s.calls,
531
+ ...folded
532
+ .filter((f) => f.number > s.number)
533
+ .flatMap((f) => f.calls.map((c) => ({ ...c, position: "post" as const }))),
534
+ ];
535
+ const shared = s.writes.filter((k) => owner.has(k) && owner.get(k) !== s);
536
+ return { number: s.number, keys, shared, calls, conditional: s.conditional };
537
+ });
538
+ }
539
+
540
+ interface Visit {
541
+ unit: Unit;
542
+ /** Item indices of this visit's rows. */
543
+ rows: number[];
544
+ }
545
+
546
+ type Item =
547
+ | { kind: "call"; call: CallRef }
548
+ | { kind: "step"; key: string; row: StatusRow; unit: Unit | undefined };
549
+
550
+ /**
551
+ * Classify one run's rows against its contract. Consecutive rows of one unit form a
552
+ * visit (a repeat of a key starts a new one, so each group-loop repeat owns its own
553
+ * gaps). A visit owns the calls before its first row and between its rows, and the
554
+ * calls after its last row that are one of its `post` calls (R3); the rest belong to
555
+ * the next visit. Matching is on noun + verb (R2). `holey` keys on `evidenceHoles` +
556
+ * `stepHoles` only. Never throws and never filters by age.
557
+ */
558
+ export function check(
559
+ rows: StatusRow[],
560
+ contract: Contract,
561
+ options: CheckOptions = {},
562
+ ): CompletenessVerdict {
563
+ const workflow = contract.workflow;
564
+ const own = rows.filter((r) => r.workflow === workflow);
565
+ const units = contractUnits(contract).map((u) => ({
566
+ ...u,
567
+ calls: u.calls.filter((c) => c.noun !== SELF_NOUN),
568
+ }));
569
+ const unitOf = new Map<string, Unit>();
570
+ for (const u of units) for (const k of u.keys) unitOf.set(k, u);
571
+ const writersOf = new Map<string, Unit[]>();
572
+ for (const u of units)
573
+ for (const k of [...u.keys, ...u.shared]) writersOf.set(k, [...(writersOf.get(k) ?? []), u]);
574
+ const workflowCalls = contract.workflowCalls.filter((c) => c.noun !== SELF_NOUN);
575
+ const workflowKeys = new Set([...workflowCalls, ...contract.anywhereCalls].map(callKey));
576
+ const subRows = new Set(contract.subRows);
577
+ const pauseRows = new Set(contract.pauseRows);
578
+
579
+ // A sub-row sits inside the visit of the step whose call wrote it, so it is no visit boundary.
580
+ // A pause row is a boundary owned by no step, like a row outside the contract.
581
+ const items: Item[] = own.flatMap((r): Item[] => {
582
+ if (r.type === "engine-call" && r["noun"] !== SELF_NOUN) {
583
+ return [{ kind: "call", call: { noun: String(r["noun"]), verb: String(r["verb"]) } }];
167
584
  }
168
- if (inStep) {
169
- let m: RegExpExecArray | null;
170
- const re = /(?:step:"|--step=)(ship-[a-z-]+)/g;
171
- while ((m = re.exec(line)) !== null) {
172
- headingSet.add(m[1]);
585
+ if (r.type === "step-done" && typeof r.step === "string" && !subRows.has(r.step)) {
586
+ return [{ kind: "step", key: r.step, row: r, unit: unitOf.get(r.step) }];
587
+ }
588
+ return [];
589
+ });
590
+ const stepRowCount = own.filter(
591
+ (r) => r.type === "step-done" && typeof r.step === "string",
592
+ ).length;
593
+ const callCount = items.filter((i) => i.kind === "call").length;
594
+ const preJournal = callCount === 0;
595
+ // A journal that starts mid-run (an engine upgrade, the kill switch lifted) leaves the
596
+ // visits that finished before its first `engine-call` row with no evidence to judge.
597
+ const firstCall = items.findIndex((i) => i.kind === "call");
598
+
599
+ // Visits over the step rows, in order; a row outside the contract closes the current visit.
600
+ const visits: Visit[] = [];
601
+ const visitOfRow = new Map<number, Visit>();
602
+ let current: Visit | undefined;
603
+ const keysInCurrent = new Set<string>();
604
+ // A row two units write joins the open visit of one of them, else the unit that also
605
+ // writes the next row, else its owner.
606
+ const unitOfRow = (key: string, owner: Unit, i: number): Unit => {
607
+ const writers = writersOf.get(key) ?? [owner];
608
+ if (writers.length === 1) return owner;
609
+ if (current && writers.includes(current.unit) && !keysInCurrent.has(key)) return current.unit;
610
+ const next = items.slice(i + 1).find((x) => x.kind === "step" && x.unit !== undefined);
611
+ const nextWriters = next?.kind === "step" ? (writersOf.get(next.key) ?? []) : [];
612
+ return writers.find((w) => nextWriters.includes(w)) ?? owner;
613
+ };
614
+ items.forEach((item, i) => {
615
+ if (item.kind !== "step") return;
616
+ if (!item.unit) {
617
+ current = undefined;
618
+ return;
619
+ }
620
+ const unit = unitOfRow(item.key, item.unit, i);
621
+ const sameUnit = current?.unit === unit && !keysInCurrent.has(item.key);
622
+ if (!sameUnit) {
623
+ current = { unit, rows: [] };
624
+ keysInCurrent.clear();
625
+ visits.push(current);
626
+ }
627
+ current!.rows.push(i);
628
+ keysInCurrent.add(item.key);
629
+ visitOfRow.set(i, current!);
630
+ });
631
+
632
+ interface Slots {
633
+ plain: Map<string, number>;
634
+ arm: Map<string, number>;
635
+ }
636
+ const postSlots = new Map<Visit, Slots>();
637
+ const freshSlots = (v: Visit): Slots => {
638
+ const slots: Slots = { plain: new Map(), arm: new Map() };
639
+ for (const c of v.unit.calls) {
640
+ if (c.position !== "post") continue;
641
+ const m = c.branch ? slots.arm : slots.plain;
642
+ m.set(callKey(c), (m.get(callKey(c)) ?? 0) + 1);
643
+ }
644
+ postSlots.set(v, slots);
645
+ return slots;
646
+ };
647
+ const take = (m: Map<string, number>, key: string): boolean => {
648
+ const n = m.get(key) ?? 0;
649
+ if (n > 0) m.set(key, n - 1);
650
+ return n > 0;
651
+ };
652
+ const stepIdx = items.flatMap((it, i) => (it.kind === "step" ? [i] : []));
653
+ const owned = new Map<Visit, Set<string>>();
654
+ const unexpectedCalls = new Map<string, CallRef>();
655
+ const unattributable = new Map<string, CallRef>();
656
+ items.forEach((item, i) => {
657
+ if (item.kind !== "call") return;
658
+ const key = callKey(item.call);
659
+ const prevIdx = stepIdx.filter((x) => x < i).at(-1) ?? -1;
660
+ const nextIdx = stepIdx.find((x) => x > i) ?? -1;
661
+ const prevVisit = visitOfRow.get(prevIdx);
662
+ const nextVisit = visitOfRow.get(nextIdx);
663
+ // Each post call of a visit absorbs one journaled call: a noun + verb written both
664
+ // below one step's finish line and above the next step's is charged once to each.
665
+ // A route-arm post call absorbs more only while the next visit names no such call.
666
+ const slots =
667
+ prevVisit === undefined ? undefined : (postSlots.get(prevVisit) ?? freshSlots(prevVisit));
668
+ const nextNames = (armsToo: boolean): boolean =>
669
+ nextVisit?.unit.calls.some((c) => callKey(c) === key && (armsToo || !c.branch)) === true;
670
+ const claimsPost =
671
+ prevVisit !== undefined &&
672
+ prevVisit.rows.at(-1) === prevIdx &&
673
+ slots !== undefined &&
674
+ (take(slots.plain, key) ||
675
+ (prevVisit.unit.calls.some(
676
+ (c) => c.position === "post" && c.branch && callKey(c) === key,
677
+ ) &&
678
+ !nextNames(false) &&
679
+ (take(slots.arm, key) || !nextNames(true))));
680
+ const insideVisit = prevVisit !== undefined && prevVisit === nextVisit ? prevVisit : undefined;
681
+ // A post call journaled between its visit's own rows (above an arm's row) uses its slot.
682
+ if (insideVisit !== undefined && slots !== undefined) {
683
+ if (!take(slots.plain, key)) take(slots.arm, key);
684
+ }
685
+ const owner = insideVisit ?? (claimsPost ? prevVisit : nextVisit);
686
+ const required = owner?.unit.calls.some((c) => callKey(c) === key) === true;
687
+ if (owner && required) {
688
+ owned.set(owner, (owned.get(owner) ?? new Set<string>()).add(key));
689
+ } else if (workflowKeys.has(key)) {
690
+ // R4: a workflow-level call is never charged to a step and never unexpected.
691
+ } else if (owner === undefined) {
692
+ unattributable.set(key, item.call);
693
+ } else {
694
+ unexpectedCalls.set(key, item.call);
695
+ }
696
+ });
697
+
698
+ const evidenceHoles: EvidenceHole[] = [];
699
+ if (workflow === "debug") {
700
+ rows.forEach((stepRow, position) => {
701
+ if (
702
+ stepRow.type === "step-done" &&
703
+ stepRow.workflow === "debug" &&
704
+ stepRow.step === "context-fetch"
705
+ ) {
706
+ const prior = rows.slice(0, position);
707
+ const previous =
708
+ prior
709
+ .map((r, i) => (r.type === "step-done" || r.type === "workflow-started" ? i : -1))
710
+ .filter((i) => i >= 0)
711
+ .at(-1) ?? -1;
712
+ const start =
713
+ prior
714
+ .map((r, i) => (r.type === "workflow-started" ? i : -1))
715
+ .filter((i) => i >= 0)
716
+ .at(-1) ?? -1;
717
+ const history = prior.slice(start + 1);
718
+ const meta = [...history]
719
+ .reverse()
720
+ .find(
721
+ (r) =>
722
+ r.type === "workflow-meta" && r.workflow === "debug" && r.ciSelection !== undefined,
723
+ );
724
+ const ci = history.some(
725
+ (r) =>
726
+ r.type === "test-run" &&
727
+ r.workflow === "debug" &&
728
+ ciRoundMatches(r, meta?.ciSelection, meta?.ciGeneration),
729
+ );
730
+ if (
731
+ ci &&
732
+ !prior
733
+ .slice(previous + 1)
734
+ .some((r) => r.type === "engine-call" && r.noun === "context" && r.verb === "fetch")
735
+ )
736
+ evidenceHoles.push({
737
+ step: "context-fetch",
738
+ number: unitOf.get("context-fetch")?.number ?? 2,
739
+ index: 1,
740
+ missing: [{ noun: "context", verb: "fetch", flags: ["context"] }],
741
+ });
742
+ }
743
+ if (
744
+ stepRow.type !== "step-done" ||
745
+ stepRow.workflow !== "debug" ||
746
+ stepRow.step !== "debug-run-tests" ||
747
+ stepRow.source !== "ci"
748
+ )
749
+ return;
750
+ const prior = rows.slice(0, position);
751
+ const start =
752
+ prior
753
+ .map((r, i) => (r.type === "workflow-started" ? i : -1))
754
+ .filter((i) => i >= 0)
755
+ .at(-1) ?? -1;
756
+ const history = prior.slice(start + 1).reverse();
757
+ const meta = history.find(
758
+ (r) => r.type === "workflow-meta" && r.workflow === "debug" && r.ciSelection !== undefined,
759
+ );
760
+ const round = history.find(
761
+ (r) =>
762
+ r.type === "test-run" &&
763
+ r.workflow === "debug" &&
764
+ r.step === "debug-run-tests" &&
765
+ r.attempt === stepRow.attempt,
766
+ );
767
+ if (
768
+ !round ||
769
+ !ciRoundMatches(round, meta?.ciSelection, meta?.ciGeneration) ||
770
+ stepRow.scope !== round.scope ||
771
+ stepRow.verdict !== "FAIL" ||
772
+ stepRow.ciGeneration !== meta?.ciGeneration ||
773
+ !Array.isArray(stepRow.artifacts) ||
774
+ !stepRow.artifacts.includes(round.artifact)
775
+ )
776
+ evidenceHoles.push({
777
+ step: "debug-run-tests",
778
+ number: unitOf.get("debug-run-tests")?.number ?? 1,
779
+ index: 1,
780
+ missing: [{ noun: "tests", verb: "run", flags: ["ci-run"] }],
781
+ });
782
+ });
783
+ }
784
+ const occurrence = new Map<Unit, number>();
785
+ const exercised = new Map<Unit, Set<string>>();
786
+ for (const v of visits) {
787
+ const index = (occurrence.get(v.unit) ?? 0) + 1;
788
+ occurrence.set(v.unit, index);
789
+ const beforeJournal = firstCall !== -1 && v.rows.every((r) => r < firstCall);
790
+ if (beforeJournal) continue;
791
+ const got = owned.get(v) ?? new Set<string>();
792
+ // A visit whose own row-writing call (`steps finish` / `steps done`) left no journaled
793
+ // call is judged on its step row alone: the journal did not see this visit's commands.
794
+ // A writer outside the journal window is never required, so there a visit with no
795
+ // journaled call at all is judged the same way.
796
+ const isWriter = (k: string): boolean => k === "steps finish" || k === "steps done";
797
+ const writerInWindow = v.unit.calls.some((c) => !c.branch && isWriter(callKey(c)));
798
+ if (writerInWindow ? ![...got].some(isWriter) : got.size === 0) continue;
799
+ const pool = exercised.get(v.unit) ?? new Set<string>();
800
+ for (const k of got) pool.add(k);
801
+ exercised.set(v.unit, pool);
802
+ const rowsOf = v.rows.map((i) => items[i]).flatMap((x) => (x?.kind === "step" ? [x.row] : []));
803
+ const done = rowsOf.some((r) => r.status === undefined || r.status === "DONE");
804
+ if (preJournal || !done) continue;
805
+ const missing = new Map<string, WorkflowCall>();
806
+ for (const c of v.unit.calls) {
807
+ if (!c.branch && !got.has(callKey(c)) && !missing.has(callKey(c))) {
808
+ missing.set(callKey(c), { noun: c.noun, verb: c.verb, flags: c.flags });
173
809
  }
174
- re.lastIndex = 0;
175
810
  }
811
+ if (missing.size === 0) continue;
812
+ const group = rowsOf.map((r) => r["group"]).find((g) => typeof g === "number");
813
+ evidenceHoles.push({
814
+ step: rowsOf[0]?.step ?? v.unit.keys[0] ?? "",
815
+ number: v.unit.number,
816
+ index,
817
+ ...(typeof group === "number" ? { group } : {}),
818
+ missing: [...missing.values()],
819
+ });
176
820
  }
177
821
 
178
- // 3. Union + the one asymmetry that carries signal (see the docstring).
179
- const all = new Set<string>([...literalSet, ...headingSet]);
180
- const orphanSteps = [...literalSet].filter((s) => !headingSet.has(s)).sort();
822
+ const unexercised: Array<{ step: string; call: CallRef }> = [];
823
+ if (!preJournal) {
824
+ for (const u of units) {
825
+ const pool = exercised.get(u);
826
+ if (pool === undefined) continue;
827
+ const required = new Set(u.calls.filter((c) => !c.branch).map(callKey));
828
+ const reported = new Set<string>();
829
+ for (const c of u.calls) {
830
+ const k = callKey(c);
831
+ if (c.branch && !required.has(k) && !pool.has(k) && !reported.has(k)) {
832
+ reported.add(k);
833
+ unexercised.push({ step: u.keys[0] ?? "", call: { noun: c.noun, verb: c.verb } });
834
+ }
835
+ }
836
+ }
837
+ }
838
+
839
+ const observed = new Set(items.flatMap((i) => (i.kind === "step" ? [i.key] : [])));
840
+ const closed = observed.has(`${workflow}-close-workflow`);
841
+ const failed = own.some((r) => r.type === "workflow-failed");
842
+ const lastNumber = Math.max(0, ...visits.map((v) => v.unit.number));
843
+ const stepHoles = units
844
+ .filter((u) => !u.conditional && !u.keys.some((k) => observed.has(k)))
845
+ .filter((u) => closed || (failed && u.number < lastNumber))
846
+ .map((u) => u.keys[0]!);
847
+
848
+ const unexpected: Array<CallRef | { step: string }> = [
849
+ ...[...observed]
850
+ .filter((k) => !unitOf.has(k) && !pauseRows.has(k))
851
+ .sort()
852
+ .map((step) => ({ step })),
853
+ ...(preJournal ? [] : unexpectedCalls.values()),
854
+ ];
855
+ const holey = evidenceHoles.length > 0 || stepHoles.length > 0;
181
856
  return {
182
- steps: [...all].sort(),
183
- headingSteps: [...headingSet].sort(),
184
- literalSteps: [...literalSet].sort(),
185
- orphanSteps,
857
+ workflow,
858
+ verdict: holey ? "HOLEY" : "CLEAN",
859
+ holey,
860
+ preJournal,
861
+ journalSuspect: preJournal && options.journalSuspect === true,
862
+ observed: { steps: stepRowCount, calls: callCount },
863
+ evidenceHoles,
864
+ stepHoles,
865
+ unexercised,
866
+ unexpected,
867
+ unattributable: [...unattributable.values()],
868
+ sourceSha: contract.sourceSha,
869
+ workflowCalls: workflowCalls.map((c) => ({ noun: c.noun, verb: c.verb })),
186
870
  };
187
871
  }
188
872
 
873
+ export interface StoredOrComputed {
874
+ verdict: CompletenessVerdict;
875
+ source: "stored" | "computed";
876
+ }
877
+
189
878
  /**
190
- * Cross-check the source-derived set against the frozen canonical set.
191
- * Returns the keys that disagree (present in one but not the other).
879
+ * The verdict of a run: its last stored `completeness` row, recomputed when a
880
+ * `step-done` or `engine-call` row follows it (the closing `workflow-done` row and
881
+ * the `completeness` verb's own journal row do not).
192
882
  */
193
- export function checkSourceCanonicalDrift(sourceSteps: string[]): string[] {
194
- const sourceSet = new Set(sourceSteps);
195
- const canonicalSet = new Set<string>(SHIP_STEP_ORDER);
196
- const drift: string[] = [];
197
- for (const k of canonicalSet) if (!sourceSet.has(k)) drift.push(`canonical-but-not-source:${k}`);
198
- for (const k of sourceSet) if (!canonicalSet.has(k)) drift.push(`source-but-not-canonical:${k}`);
199
- return drift;
883
+ export function readCompleteness(
884
+ rows: StatusRow[],
885
+ contract: Contract,
886
+ options: CheckOptions = {},
887
+ ): StoredOrComputed {
888
+ const own = rows.filter((r) => r.workflow === contract.workflow);
889
+ const at = own.map((r) => r.type).lastIndexOf("completeness");
890
+ const stored = at === -1 ? undefined : own[at];
891
+ const followed = own
892
+ .slice(at + 1)
893
+ .some((r) => r.type === "step-done" || (r.type === "engine-call" && r["noun"] !== SELF_NOUN));
894
+ if (!stored || followed) return { verdict: check(rows, contract, options), source: "computed" };
895
+ const list = (key: string): never[] =>
896
+ Array.isArray(stored[key]) ? (stored[key] as never[]) : [];
897
+ const holey = stored["verdict"] === "HOLEY";
898
+ const observed = stored["observed"] as CompletenessVerdict["observed"] | undefined;
899
+ return {
900
+ source: "stored",
901
+ verdict: {
902
+ workflow: contract.workflow,
903
+ verdict: holey ? "HOLEY" : "CLEAN",
904
+ holey,
905
+ preJournal: stored["preJournal"] === true,
906
+ journalSuspect: stored["journalSuspect"] === true,
907
+ observed: observed ?? { steps: 0, calls: 0 },
908
+ evidenceHoles: list("evidenceHoles"),
909
+ stepHoles: list("stepHoles"),
910
+ unexercised: list("unexercised"),
911
+ unexpected: list("unexpected"),
912
+ unattributable: list("unattributable"),
913
+ sourceSha: typeof stored["sourceSha"] === "string" ? stored["sourceSha"] : "",
914
+ workflowCalls: list("workflowCalls"),
915
+ },
916
+ };
200
917
  }
201
918
 
202
919
  // ---------------------------------------------------------------------------
@@ -265,6 +982,10 @@ export function computeMandatoryForPath(path: RunPath, sourceUniverse: string[])
265
982
  [...universe].filter((s) => !MERGED_ON_ENTRY_SKIP.has(s) && !RETRY_LOOP_STEPS.has(s)),
266
983
  );
267
984
 
985
+ case "COMPLETED":
986
+ // Non-ship runs derive their mandatory set from the contract (auditRun)
987
+ return new Set(universe);
988
+
268
989
  case "ABORTED":
269
990
  // No mandatory steps — the run terminated; post-abort absences are expected
270
991
  return new Set();
@@ -331,15 +1052,10 @@ export function detectHoles(
331
1052
  }
332
1053
 
333
1054
  // ---------------------------------------------------------------------------
334
- // Full audit — parse status.jsonl + ship md, classify, detect, report
1055
+ // Full audit — parse status.jsonl + workflow md, classify, detect, report
335
1056
  // ---------------------------------------------------------------------------
336
1057
 
337
- export function auditStatusJsonl(statusJsonl: string, shipMd: string): HoleReport {
338
- // Derive expected set from source
339
- const { steps: sourceUniverse, orphanSteps } = deriveExpectedStepSetFromSource(shipMd);
340
- const sourceCanonicalDrift = checkSourceCanonicalDrift(sourceUniverse);
341
-
342
- // Parse status rows
1058
+ export function parseRows(statusJsonl: string): StatusRow[] {
343
1059
  const rows: StatusRow[] = [];
344
1060
  for (const line of statusJsonl.split("\n")) {
345
1061
  const trimmed = line.trim();
@@ -348,37 +1064,97 @@ export function auditStatusJsonl(statusJsonl: string, shipMd: string): HoleRepor
348
1064
  const row = parseJson(trimmed);
349
1065
  if (row.ok) rows.push(row.value as StatusRow);
350
1066
  }
1067
+ return rows;
1068
+ }
351
1069
 
352
- // Filter to ship step-done rows + workflow-failed rows
353
- const shipStepRows = rows.filter(
354
- (r) => r.type === "step-done" && r.workflow === "ship" && typeof r.step === "string",
1070
+ /** Audit one run's rows against the contract derived from its workflow markdown. */
1071
+ export function auditRun(rows: StatusRow[], workflow: string, workflowMd: string): HoleReport {
1072
+ const contract = deriveContract(workflowMd, workflow);
1073
+ const stepRows = rows.filter(
1074
+ (r) => r.type === "step-done" && r.workflow === workflow && typeof r.step === "string",
355
1075
  );
356
- const hasWorkflowFailed = rows.some((r) => r.type === "workflow-failed" && r.workflow === "ship");
357
- const hasMergedOnEntryMarker = rows.some(
358
- (r) => r.type === "ship-merged-on-entry" && r.workflow === "ship",
1076
+ const hasWorkflowFailed = rows.some(
1077
+ (r) => r.type === "workflow-failed" && r.workflow === workflow,
359
1078
  );
360
-
361
- // Collect observed steps
362
1079
  const observed = new Set<string>();
363
- for (const r of shipStepRows) {
364
- if (r.step) observed.add(r.step);
365
- }
1080
+ for (const r of stepRows) if (r.step) observed.add(r.step);
1081
+ const sorted = [...observed].sort();
1082
+ const side = new Set([...contract.pauseRows, ...contract.subRows]);
366
1083
 
367
- // Classify + detect
368
- const runPath = classifyRun(observed, hasWorkflowFailed, hasMergedOnEntryMarker);
369
- const { missing, unexpected } = detectHoles(observed, sourceUniverse, runPath);
1084
+ if (workflow === "ship") {
1085
+ const hasMergedOnEntryMarker = rows.some(
1086
+ (r) => r.type === "ship-merged-on-entry" && r.workflow === "ship",
1087
+ );
1088
+ const runPath = classifyRun(observed, hasWorkflowFailed, hasMergedOnEntryMarker);
1089
+ const { missing, unexpected } = detectHoles(observed, contract.universe, runPath);
1090
+ return {
1091
+ workflow,
1092
+ missing,
1093
+ unexpected: unexpected.filter((k) => !side.has(k)),
1094
+ path: runPath,
1095
+ observed: sorted,
1096
+ sourceUniverse: contract.universe,
1097
+ sourceCanonicalDrift: contract.drift,
1098
+ orphanSteps: contract.orphanSteps,
1099
+ };
1100
+ }
370
1101
 
1102
+ const closeKey = `${workflow}-close-workflow`;
1103
+ const runPath: RunPath = observed.has(closeKey)
1104
+ ? "COMPLETED"
1105
+ : hasWorkflowFailed
1106
+ ? "ABORTED"
1107
+ : "IN_PROGRESS";
1108
+ const missing =
1109
+ runPath === "COMPLETED"
1110
+ ? contract.steps
1111
+ .filter(
1112
+ (s) => s.keys.length > 0 && !s.conditional && !s.keys.some((k) => observed.has(k)),
1113
+ )
1114
+ .map((s) => s.keys[0]!)
1115
+ .sort()
1116
+ : [];
371
1117
  return {
1118
+ workflow,
372
1119
  missing,
373
- unexpected,
1120
+ unexpected: sorted.filter((k) => !contract.universe.includes(k) && !side.has(k)),
374
1121
  path: runPath,
375
- observed: [...observed].sort(),
376
- sourceUniverse: [...sourceUniverse].sort(),
377
- sourceCanonicalDrift,
378
- orphanSteps,
1122
+ observed: sorted,
1123
+ sourceUniverse: contract.universe,
1124
+ sourceCanonicalDrift: contract.drift,
1125
+ orphanSteps: contract.orphanSteps,
379
1126
  };
380
1127
  }
381
1128
 
1129
+ /** `workflow`'s rows split into runs: each `workflow-started` opens a run that ends at the next one; rows before the first start form their own run. */
1130
+ export function runsOf(rows: StatusRow[], workflow: string): StatusRow[][] {
1131
+ const at = (r: StatusRow) => (typeof r["at"] === "string" ? r["at"] : "");
1132
+ const own = rows
1133
+ .filter((r) => r.workflow === workflow)
1134
+ .sort((a, b) => (at(a) < at(b) ? -1 : at(a) > at(b) ? 1 : 0));
1135
+ const runs: StatusRow[][] = [];
1136
+ for (const row of own) {
1137
+ const current = runs.at(-1);
1138
+ if (current === undefined || row.type === "workflow-started") runs.push([row]);
1139
+ else current.push(row);
1140
+ }
1141
+ return runs;
1142
+ }
1143
+
1144
+ /** Audit a status.jsonl as a ship run against `shipMd`. */
1145
+ export function auditStatusJsonl(statusJsonl: string, shipMd: string): HoleReport {
1146
+ return auditRun(parseRows(statusJsonl), "ship", shipMd);
1147
+ }
1148
+
1149
+ /** The workflows a status.jsonl holds runs of, inferred from its own rows. */
1150
+ export function inferWorkflows(rows: StatusRow[]): string[] {
1151
+ const known = new Set<string>(Object.keys(WORKFLOW_STEPS));
1152
+ const found = new Set<string>();
1153
+ for (const r of rows)
1154
+ if (typeof r.workflow === "string" && known.has(r.workflow)) found.add(r.workflow);
1155
+ return [...found].sort();
1156
+ }
1157
+
382
1158
  // ---------------------------------------------------------------------------
383
1159
  // Advisory report formatter
384
1160
  // ---------------------------------------------------------------------------
@@ -386,6 +1162,7 @@ export function auditStatusJsonl(statusJsonl: string, shipMd: string): HoleRepor
386
1162
  export function formatAdvisoryReport(report: HoleReport): string {
387
1163
  const lines: string[] = [];
388
1164
  lines.push("[bkit-status-holes] ADVISORY — fail-open (exit 0 regardless)");
1165
+ if (report.workflow) lines.push(` workflow: ${report.workflow}`);
389
1166
  lines.push(` path: ${report.path}`);
390
1167
  lines.push(` observed: ${report.observed.length} step(s)`);
391
1168
 
@@ -417,37 +1194,30 @@ export function formatAdvisoryReport(report: HoleReport): string {
417
1194
  // ---------------------------------------------------------------------------
418
1195
 
419
1196
  export function main(argv: string[]): void {
420
- const args = argv.slice(2);
421
-
422
- // Resolve the ship-md override FIRST so its VALUE is never mistaken for a
423
- // positional. `args.find(a => !a.startsWith("--"))` alone picks up the value
424
- // of `--ship-md` when the flag is passed before the status path.
425
- const mdFlagIdx = args.indexOf("--ship-md");
426
- const shipMdOverride = mdFlagIdx >= 0 ? args[mdFlagIdx + 1] : undefined;
427
- const consumed = new Set<number>();
428
- if (mdFlagIdx >= 0) {
429
- consumed.add(mdFlagIdx);
430
- if (shipMdOverride) consumed.add(mdFlagIdx + 1);
431
- }
432
-
433
- // Every remaining positional is a status.jsonl to audit — one report each, so
434
- // a whole corpus can be swept in one advisory CI step.
435
- const statusPaths = args.filter((a, i) => !consumed.has(i) && !a.startsWith("--"));
1197
+ // Every positional is a status.jsonl to audit — one report per run of each
1198
+ // workflow in each file, so a whole corpus can be swept in one advisory CI step.
1199
+ const statusPaths = argv.slice(2).filter((a) => !a.startsWith("--"));
436
1200
  if (statusPaths.length === 0) {
437
1201
  process.stdout.write("[bkit-status-holes] no status.jsonl path given — skipping (advisory)\n");
438
1202
  return; // exit 0
439
1203
  }
440
1204
 
441
- const shipMdPath = shipMdOverride || path.join(getWorkflowsRoot(), "bkit-ship.md");
442
-
443
- let shipMd = "";
444
- try {
445
- shipMd = fs.readFileSync(shipMdPath, "utf-8");
446
- } catch {
447
- process.stdout.write(`[bkit-status-holes] ${shipMdPath} not found — skipping (advisory)\n`);
448
- return; // exit 0
449
- }
1205
+ const mdCache = new Map<string, string | null>();
1206
+ const loadMd = (workflow: string): string | null => {
1207
+ if (!mdCache.has(workflow)) {
1208
+ try {
1209
+ mdCache.set(
1210
+ workflow,
1211
+ fs.readFileSync(path.join(getWorkflowsRoot(), `bkit-${workflow}.md`), "utf-8"),
1212
+ );
1213
+ } catch {
1214
+ mdCache.set(workflow, null);
1215
+ }
1216
+ }
1217
+ return mdCache.get(workflow) ?? null;
1218
+ };
450
1219
 
1220
+ let holeyRuns = 0;
451
1221
  for (const statusPath of statusPaths) {
452
1222
  // Read inputs (advisory — missing files = skip, never fail)
453
1223
  let statusJsonl = "";
@@ -458,10 +1228,33 @@ export function main(argv: string[]): void {
458
1228
  continue; // exit 0
459
1229
  }
460
1230
 
461
- const report = auditStatusJsonl(statusJsonl, shipMd);
1231
+ const rows = parseRows(statusJsonl);
1232
+ const workflows = inferWorkflows(rows);
462
1233
  process.stdout.write(`\n${statusPath}\n`);
463
- process.stdout.write(formatAdvisoryReport(report) + "\n");
1234
+ if (workflows.length === 0) {
1235
+ process.stdout.write(
1236
+ `[bkit-status-holes] ${statusPath}: no workflow rows — skipping (advisory)\n`,
1237
+ );
1238
+ continue;
1239
+ }
1240
+ for (const workflow of workflows) {
1241
+ const md = loadMd(workflow);
1242
+ if (md === null) {
1243
+ process.stdout.write(
1244
+ `[bkit-status-holes] bkit-${workflow}.md not found — skipping ${workflow} run (advisory)\n`,
1245
+ );
1246
+ continue;
1247
+ }
1248
+ for (const run of runsOf(rows, workflow)) {
1249
+ const report = auditRun(run, workflow, md);
1250
+ if (report.missing.length > 0) holeyRuns += 1;
1251
+ process.stdout.write(formatAdvisoryReport(report) + "\n");
1252
+ }
1253
+ }
464
1254
  }
1255
+ process.stdout.write(
1256
+ `[bkit-status-holes] sweep: ${statusPaths.length} file(s), ${holeyRuns} holey\n`,
1257
+ );
465
1258
  // ALWAYS exit 0 — this is advisory / fail-open
466
1259
  }
467
1260