@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,191 +1,194 @@
1
- <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
2
-
3
1
  <!-- bkit:start -->
4
2
 
5
3
  {{BKIT_MANAGED_MARKER}}
6
4
 
5
+ <!-- Note: @bkit-audit-generate fills this template. The report lives at `docs/audits/{YYYYMM}/{slug}.md`, where `{YYYYMM}` is the UTC month of the run and `{slug}` is this file's name without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md`, where `{TIMESTAMP}` is the output of `date -u +%Y%m%dT%H%M%SZ`. NEVER overwrite an earlier report. The report is stamped with a `bkit:anchor` block that records the audited commit (`baseSha`) and branch (`baseRef`). NEVER write or edit that block by hand. -->
6
+
7
7
  # Documentation Audit
8
8
 
9
9
  > [!CAUTION]
10
- > **Purpose:** Docs still true — each claim matches code, each pointer lands, each agent-relevant fact written down.
10
+ > **Purpose:** Whether the docs are still true: each claim matches the code, each pointer lands, and each fact agents rely on is written down.
11
11
  >
12
12
  > **Rules:**
13
13
  >
14
- > - Read-only audit; never edit code, config, or data.
15
- > - `Universal Instructions` apply to all projects; `Project Instructions` apply only to this project.
16
- > - Local audit instructions / overrides → `Project Instructions` below the bkit-managed block; universal instructions stay in-block.
17
- > - Any tools mentioned in `Universal Instructions` are examples only; swap for actual tools in final output; drop inapplicable.
18
- > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
19
- > - Read `.agents/docs.md` → load docs for workflow / step / task; skip missing; cite docs inline where required.
20
- > - Every claim cites this run's evidence (`file:line`, or command / query and its output) and tool behind it; a previous report's figure, list, or status is a lead, not evidence.
21
- > - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
22
14
  > - NEVER paste a secret or credential value into the report.
23
- > - Historical records (`docs/plans/**`, `docs/archive/**`, `docs/completed.md`) and existing ledger rows are citers only; never edit them.
15
+ > - Treat historical records (`docs/plans/**`, `docs/archive/**`, `docs/completed.md`) and existing ledger rows as citers only, and never edit them.
24
16
 
25
17
  ## Universal Instructions
26
18
 
27
19
  ### Context & Goals
28
20
 
29
- Docs are the record agents work from: memory points at them, plans cite them, code comments cite them. Wrong doc > missing doc — agents follow it. Prose lint = style; formatter = shape; managed-block check = managed blocks only. None reads docs against code. Per-ship doc update sees only files that ship changed → drift across ships belongs to nobody.
21
+ Docs are the record agents work from: memory points at them, and plans and code comments cite them. A wrong doc is worse than a missing one, because agents follow it. Prose lint checks style, the formatter checks shape, and the managed-block check covers managed blocks only. None of them reads the docs against the code. The doc update on each ship sees only the files that ship changed, so drift across ships belongs to nobody.
30
22
 
31
- **Target failure:** **a claim the code has left behind** — default doc states but deployed env does not; script phase doc omits (look hardest for anything that deletes); pointer leads nowhere; fact running code relies on exists only in memory or was dropped from a ledger.
23
+ The failure this audit targets is a claim the code has left behind. Examples: a default the doc states that the deployed environment does not use; a script phase the doc leaves out (look hardest for anything that deletes); a pointer that leads nowhere; and a fact the running code relies on that exists only in memory, or was dropped from a ledger.
32
24
 
33
- **Applies when:** project has live docs (prose under `docs/` or `.agents/`, or root `README.md` agents treat as entry). None → one `N/A` row with evidence, never "clean".
25
+ **Applies when:** the project has live docs: prose under `docs/` or `.agents/`, or a root `README.md` that agents treat as the entry point. **If** it has none → write one `N/A` row with its evidence, and never report the surface as "clean".
34
26
 
35
- **Cadence:** monthly. Extra pass after ledger migration, `bkit upgrade`, or toolchain change (runtime, package manager, SDK, new required tool or hook).
27
+ **Cadence:** Run once a month. Run an extra pass after a ledger migration, a `bkit upgrade`, or a toolchain change (runtime, package manager, SDK, or a new required tool or hook).
36
28
 
37
- **Anchor Standards:** record version and date read. Newer version → `Standards` step reads what changed.
29
+ **Anchor Standards:**
38
30
 
39
31
  - Diátaxis (unversioned; record the date read).
40
- - Docs-as-code prose linter and link checker (e.g. Vale, lychee); record versions.
41
- - Architecture decision records (e.g. ADR form).
42
- - Runbook practice (e.g. Google SRE Workbook, "On-Call").
43
- - Source-host community health files (e.g. GitHub `README`, `CONTRIBUTING`, `SECURITY.md`).
44
- - API-doc validation for the language (e.g. TypeDoc validation, TSDoc); record version.
45
- - HTTP API specification when the project serves HTTP (e.g. OpenAPI); record version.
32
+ - Docs-as-code prose linter and link checker (e.g., Vale, lychee); record versions.
33
+ - Architecture decision records (e.g., ADR form).
34
+ - Runbook practice (e.g., Google SRE Workbook, "On-Call").
35
+ - Source-host community health files (e.g., GitHub `README`, `CONTRIBUTING`, `SECURITY.md`).
36
+ - API-doc validation for the language (e.g., TypeDoc validation, TSDoc); record version.
37
+ - HTTP API specification when the project serves HTTP (e.g., OpenAPI); record version.
46
38
 
47
39
  ### Scope
48
40
 
49
- - Every live doc, every run.
50
- - Catalogue: `.agents/docs.md` rows vs files on disk, and the root entry point.
51
- - Mechanical: prose, format, managed-block drift, backticked paths, links, and anchors, commands, diagrams.
52
- - Ledger citations resolve to one winning row; significant choices have a `docs/decisions.jsonl` row.
53
- - Claims in every live doc vs the code.
54
- - Setup doc enough to start. Runbooks exist and each is walked.
55
- - Generated reference for HTTP APIs, background events, and shared packages.
56
- - Auto-memory vs docs. Instruction files vs each other. One topic, one doc. Diátaxis quadrant per live doc.
41
+ - Check every live doc on every run.
42
+ - Check the catalogue: `.agents/docs.md` rows against the files on disk, and the root entry point.
43
+ - Run the mechanical checks: prose, format, managed-block drift, backticked paths, links and anchors, commands, and diagrams.
44
+ - Check that each ledger citation resolves to one winning row, and that each significant choice has a `docs/decisions.jsonl` row.
45
+ - Check the claims in every live doc against the code.
46
+ - Check that the setup doc is enough to start, that the runbooks exist, and walk each one.
47
+ - Check the generated reference for HTTP APIs, background events and shared packages.
48
+ - Check auto-memory against the docs, and the instruction files against each other.
49
+ - Check that each topic has one doc, and label each live doc with its Diátaxis quadrant.
57
50
 
58
51
  ### Out of Scope
59
52
 
60
53
  <!-- prettier-ignore -->
61
54
  | Excluded item | Why | Where it belongs |
62
55
  | --- | --- | --- |
63
- | Whether a doc is in the right place | Placement | `bkit-audit-repo` |
64
- | Stale pointers found only from the code side (route or file moved, no doc cites the old path) | Code-side sweep | `bkit-audit-dead-code` |
65
- | Capability-register status (`one` / `bypassed` / `split` / `gap`) | Duplication sweep | `bkit-audit-duplication` |
66
- | Architecture graph diagram correctness | Architecture sweep | `bkit-audit-architecture` |
67
- | Turning a check into a CI gate | Gate design | `bkit-audit-gates` |
68
- | A stale fact inside a historical record | History, not a defect | Citers only; fix a dead pointer at the target |
69
- | Instruction files each agent host loads; agent permissions, hooks, tool servers | Agent config sweep | `bkit-audit-agents` |
70
- | Applying doc edits, appending ledger rows, editing memory | Audit reports only | Plan from this report |
56
+ | Whether a doc is in the right place | The repo sweep covers placement | `bkit-audit-repo` |
57
+ | Stale pointers found only from the code side (route or file moved, no doc cites the old path) | The code-side sweep covers it | `bkit-audit-dead-code` |
58
+ | Capability-register status (`one` / `bypassed` / `split` / `gap`) | The duplication sweep covers it | `bkit-audit-duplication` |
59
+ | Architecture graph diagram correctness | The architecture sweep covers it | `bkit-audit-architecture` |
60
+ | Turning a check into a CI gate | It is a gate design | `bkit-audit-gates` |
61
+ | A stale fact inside a historical record | It is history, not a defect | Citers only; fix a dead pointer at the target |
62
+ | Instruction files each agent host loads; agent permissions, hooks, tool servers | The agent config sweep covers it | `bkit-audit-agents` |
63
+ | Applying doc edits, appending ledger rows, editing memory | The audit only reports | A plan made from this report |
71
64
 
72
65
  ### Pre-Flight / Dependencies
73
66
 
74
- **Checkpoint:** Check off all core items. Check conditional items only when applicable. Each item: available → tool and version; missing → fallback, gap in `Not Checked`, fix in `Process Improvements`. Unnamed gap reads as passed. never abort for a missing capability.
75
-
76
- **Credentials:** probe direnv before marking a token / env var missing: `direnv exec . sh -c '[ -n "${VAR}" ] && echo set || echo unset'`; `unset` = missing. Run credentialed CLIs as `direnv exec . <cmd>`. No direnv (cloud session) → plain env check. Report names, never values.
77
-
78
67
  #### Core
79
68
 
80
- Always verify.
81
-
82
- - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
83
- - [ ] **Repo Read:** Steps 2–13 — live docs, instruction files, manifests, CI workflow. Fallback: none; unreadable tree = finding.
84
- - [ ] **Web:** Step 14 — fetch anchor standards. Fallback: versions recorded as unread.
69
+ - [ ] **Permissions:** every blocked call is recorded.
70
+ - [ ] **Repo Read:** Steps 2-13 — live docs, instruction files, manifests and the CI workflow. Fallback: none. An unreadable tree is a finding.
71
+ - [ ] **Web:** Step 14 — fetch the anchor standards. Fallback: record the versions as unread.
85
72
 
86
73
  #### Conditional
87
74
 
88
- Verify only when applicable.
89
-
90
- - [ ] **Prose and Format:** Step 4 — e.g. Vale, Prettier. Fallback: skip that check; name it in `Not Checked`.
91
- - [ ] **Managed-Block Check:** bkit project → Step 4 — e.g. `bkit check`. Fallback: read managed blocks; drift `Not Checked`.
92
- - [ ] **Link Checker:** Step 4 — offline fragments plus cached external URLs, e.g. lychee. Fallback: open relative links by hand; external URLs `Not Checked`.
93
- - [ ] **Diagram Renderer:** Fenced diagrams → Step 4 — e.g. mermaid-cli, headless browser. Fallback: skip render; `Not Checked`. A cloud session may lack the browser.
94
- - [ ] **API Doc Validator:** Shared packages or an HTTP API → Step 9 — e.g. TypeDoc `--validation`, `eslint-plugin-jsdoc`. Fallback: read exports; broken links `Not Checked`.
95
- - [ ] **Local Memory:** Maintainer machine → Step 10 — IDE auto-memory directory. Fallback: cloud session skips; record in `Not Checked`.
75
+ - [ ] **Prose and Format:** Step 4 — e.g., Vale, Prettier. Fallback: skip that check, and name it in `Not Checked`.
76
+ - [ ] **Managed-Block Check:** **If** this is a bkit project → Step 4 — e.g., `bkit check`. Fallback: read the managed blocks, and mark drift `Not Checked`.
77
+ - [ ] **Link Checker:** Step 4 — offline fragments plus cached external URLs (e.g., lychee). Fallback: open relative links by hand, and mark external URLs `Not Checked`.
78
+ - [ ] **Diagram Renderer:** **If** docs have fenced diagrams → Step 4 — e.g., mermaid-cli, a headless browser. A cloud session may lack the browser. Fallback: skip the render, and mark it `Not Checked`.
79
+ - [ ] **API Doc Validator:** **If** the project has shared packages **or** an HTTP API → Step 9 — e.g., TypeDoc `--validation`, `eslint-plugin-jsdoc`. Fallback: read the exports, and mark broken links `Not Checked`.
80
+ - [ ] **Local Memory:** **If** the run is on a maintainer machine → Step 10 — the IDE auto-memory directory. Fallback: a cloud session skips it and records that in `Not Checked`.
96
81
 
97
82
  ### 🔒 Gate 1: Prerequisites Check
98
83
 
99
- **Checkpoint.** Verify and check `[x]` all applicable boxes above, then continue to `Probe Steps` without asking.
100
-
101
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
102
- - [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
84
+ - [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
85
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
103
86
 
104
87
  ### Probe Steps
105
88
 
106
- - [ ] **Step 1 — Previous Run:** Audited commit = this report's `bkit:anchor` `baseSha`. Read newest prior report for this slug under `docs/audits/`; its commit = its `bkit:anchor` `baseSha`, else the HEAD its `Previous Run` recorded. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
107
- - [ ] **Step 2 — Scope:** No live docs → one `N/A` row with evidence and STOP. Else every live doc. Rank by drift: per live doc, commits since that doc last changed to repo paths it cites. Record ranking. Start from up-to-date default branch with clean `git status`. Historical records are citers: pointer leads nowhere = finding, fix at target. Stale fact inside them = history, not defect. **Done when:** every live doc and drift ranking in `Scope`.
108
- - [ ] **Step 3 — Catalogue:** `.agents/docs.md`: every file on disk under `docs/` outside `plans/`, `archive/`, and `audits/` has a row, and every row's file exists; no doc listed twice (two docs on one topic = bug, including one doc in both tables with different reading columns); each row's one-line scope still matches the doc. Root `README.md` = working entry point: what the project is, links setup doc, architecture doc, and `.agents/docs.md`, and how to report a security issue. Missing community-health file with no README substitute = finding. **Done when:** `Catalogue` names every mismatch, and every clean check.
109
- - [ ] **Step 4 — Mechanical:** Run prose lint, format check, and managed-block check. Then:
110
- - Every backticked repo path in a live doc exists. Output = candidates. Path named on purpose as removed = not finding. Path moved = finding. Section anchors and `file:line` wait for `Claims`.
111
- - Relative links and heading anchors offline across every doc, plans, and archive included (citers). Then external URLs in live docs, with cache. Anchor builder must match host (e.g. GitHub); open failed fragment before calling broken. Markdown link invisible to path check.
112
- - Every package-manager script a live doc names is defined by some manifest. Every script path a doc runs exists. Both lists = candidates: doc may name removed script on purpose.
113
- - Diagrams still parse (e.g. Mermaid). Syntax break renders as raw text with no CI signal. Render each live doc that has one.
114
- - Markdown tables in live docs: each carries `<!-- prettier-ignore -->` directly above its head, and each renders — no row with more cells than the separator (GFM drops the overflow), no header / separator count mismatch (GFM renders raw text). Run read-only, e.g. `node scripts/prettier/bkit-insert-ignore.mjs --check` (bkit package template `.bkit/templates/scripts/prettier/`; skips `docs/audits/`, `docs/plans/`). No such check → `Process Improvements` proposes the template.
89
+ - [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
90
+ - [ ] **Step 2 — Scope:** **If** there are no live docs → write one `N/A` row with evidence, then **STOP**. Otherwise take every live doc, and rank them by drift: for each live doc, count the commits to the repo paths it cites since the doc last changed, and add a column for the cited paths that no longer resolve. Record the ranking. Start from an up-to-date default branch with a clean `git status`. Historical records are citers. A pointer in one that leads nowhere is a finding, fixed at the target. A stale fact inside one is history, not a defect. **Done when:** `Scope` holds every live doc and the drift ranking.
91
+ - [ ] **Step 3 — Catalogue:** Check `.agents/docs.md`. Every file on disk under `docs/`, outside `plans/`, `archive/` and `audits/`, has a row, and every row's file exists. No doc is listed twice. Two docs on one topic is a bug, and that includes one doc in both tables with different reading columns. Each row's one-line scope still matches the doc. The root `README.md` works as the entry point: it says what the project is, links the setup doc, the architecture doc and `.agents/docs.md`, and says how to report a security issue. A missing community-health file with no README substitute is a finding. **Done when:** `Catalogue` names every mismatch, and every clean check.
92
+ - [ ] **Step 4 — Mechanical:** Run prose lint, the format check and the managed-block check. Then:
93
+ - Check that every backticked repo path in a live doc exists, and that every `*.md` name in a live doc resolves, backticked or not. The output is candidates. A path named on purpose as removed is not a finding. A path that moved is a finding. Section anchors and `file:line` wait for `Claims`.
94
+ - Check relative links and heading anchors offline across every doc, plans and archive included, because they are citers. Then check external URLs in live docs, with a cache. The anchor builder must match the host (e.g., GitHub). Open a failed fragment before calling it broken. The path check cannot see Markdown links.
95
+ - Check that every package-manager script a live doc names is defined by some manifest, and that every script path a doc runs exists. Both lists are candidates, because a doc may name a removed script on purpose.
96
+ - Confirm that the prose-lint and format globs cover every live doc. A live doc outside them is a finding, because neither check ever reads it.
97
+ - Check that diagrams still parse (e.g., Mermaid). A syntax break renders as raw text with no CI signal, so render each live doc that has one.
98
+ - Check Markdown tables in live docs. Each carries `<!-- prettier-ignore -->` directly above its head, and each renders. No row has more cells than the separator, because GFM drops the overflow. The header and separator counts match, because a mismatch renders as raw text. Run the check read-only (e.g., `node scripts/prettier/bkit-insert-ignore.mjs --check`; the bkit package template is in `.bkit/templates/scripts/prettier/`, and it skips `docs/audits/` and `docs/plans/`). **If** there is no such check → `Process Improvements` proposes the template.
115
99
 
116
- Path or link fix → doc edit for `@bkit-utility-update-documentation`, sync pass only (no reorganise, compress, or cross-reference), after intentional hits struck. Pointer broken because route or file moved → also `bkit-audit-dead-code`. Broken diagram that is architecture graph → also `bkit-audit-architecture`. Check that could be CI gate → `bkit-audit-gates`. **Done when:** `Mechanical` lists broken paths, links, scripts, diagrams, and tables, each dispositioned, including checks that came back clean.
100
+ A path or link fix is a doc edit for `@bkit-utility-update-documentation`, as a sync pass only (no reorganising, compressing or cross-referencing), after the intentional hits are struck. **If** a pointer broke because a route or file moved → also name `bkit-audit-dead-code`. **If** a broken diagram is the architecture graph → also name `bkit-audit-architecture`. A check that could be a CI gate goes to `bkit-audit-gates`. **Done when:** `Mechanical` lists the broken paths, links, scripts, diagrams and tables, each with its destination, including the checks that came back clean.
117
101
 
118
- - [ ] **Step 5 — Ledgers:** Rows cited by `key` (`.bkit/jsonl.md` § Key & References). Resolve winning row: fold by `key`, highest `ts` (§ Updating a Row). Legacy counter ids (e.g. `KN-<n>`, `DE-<n>`) = leftovers, not unique, survive in `references`; new citations keep appearing → runs every time. `references` may be string or list — accept both; reader assuming list silently skips string rows. Three candidate lists: cited legacy id resolves to nothing; cited legacy id resolves to >1 row; `key` cited next to ledger name no row has (also picks up job names — open each). Rows sharing `key` = updates, not duplicates. Only different keys claiming same legacy id = clash. For each real hit:
119
- - Live doc or code comment → report names citation change to row's `key`. This run does not edit.
120
- - `docs/completed.md` or plan → do not edit. Report names new version of owning row to append, with old id in `references`.
121
- - Fact in no row → `git log -S` the old id. Report quotes historical text to restore, or ask maintainer. never reconstruct rationale nobody wrote. Restoring = same-`key` append, next step. never edit a line in place.
102
+ - [ ] **Step 5 — Ledgers:** Rows are cited by `key` (`.bkit/jsonl.md` § Key & References). Resolve the winning row by folding on `key` and taking the highest `ts` (§ Updating a Row). Legacy counter ids (e.g., `KN-<n>`, `DE-<n>`) are leftovers. They are not unique, and they survive in `references`. New citations of them keep appearing, so this check runs every time. `references` may be a string or a list, so accept both; a reader that assumes a list silently skips string rows. Build three candidate lists: a cited legacy id that resolves to nothing; a cited legacy id that resolves to more than one row; and a `key` cited next to a ledger name that no row has. The third list also picks up job names, so open each one. Also flag rows whose `references` is null, because a citation to such a row cannot resolve. Rows that share a `key` are updates, not duplicates. A clash is only when different keys claim the same legacy id. For each real hit:
103
+ - **If** the hit is in a live doc or a code comment → the report names the citation change to the row's `key`. This run does not edit.
104
+ - **If** the hit is in `docs/completed.md` or a plan → do not edit. The report names the new version of the owning row to append, with the old id in `references`.
105
+ - **If** the fact is in no row → run `git log -S` on the old id. The report quotes the historical text to restore, or asks the maintainer. Never reconstruct rationale nobody wrote. Restoring is a same-`key` append in the next step. Never edit a line in place.
122
106
 
123
- Then choices recorded at all. List each external service, major library, and data-model choice visible in code; find its `docs/decisions.jsonl` row. No row = question for maintainer, not rationale to write. Choice code reversed needs newer row, same `key`; report names row to append. **Done when:** `Ledgers` lists every unresolved citation and every choice without a row.
107
+ Then check that choices are recorded at all. List each external service, major library and data-model choice visible in the code, and find its `docs/decisions.jsonl` row. A missing row is a question for the maintainer, not rationale to write. A choice the code reversed needs a newer row with the same `key`, and the report names the row to append. **Done when:** `Ledgers` lists every unresolved citation and every choice without a row.
124
108
 
125
- - [ ] **Step 6 — Claims:** For each live doc, list claims something depends on; check each against code. No tool does this.
109
+ - [ ] **Step 6 — Claims:** For each live doc, list the claims something depends on, and check each against the code. No tool does this.
126
110
 
127
111
  <!-- prettier-ignore -->
128
112
  | Claim type | Check against |
129
113
  | --- | --- |
130
- | Defaults and flags | Schema default and the env files that are actually deployed. A schema default (e.g. zod `.default()`) applies only when the variable is unset |
114
+ | Defaults and flags | Schema default and the env files that are actually deployed. A schema default (e.g., zod `.default()`) applies only when the variable is unset |
131
115
  | What a script does | The script, end to end. Look hardest for anything that deletes |
132
116
  | Which parts exist, on which platform | The code, on every platform the doc claims |
133
117
  | `file:line` | Open the line. It must still say what the doc claims |
134
118
  | Section links (`§ Heading`) | The heading exists, word for word |
135
119
  | Counts and lists | Count them again |
136
120
 
137
- Destinations: doc wrong, code right → doc edit; doc right, code wrong → `docs/failures.jsonl` row (`@bkit-utility-update-failures` applies it), do not "fix" doc to match bug; no recorded intent → question for maintainer; product-shape statement → proposed wording for owner before it lands; drift inside `bkit:start` / `bkit:end` → upstream bkit fix, do not edit there (`bkit install` overwrites it). Handoff for `@bkit-utility-update-documentation` (this run does not invoke): findings from this report only; known drift first (`file:line` and code that disproves it); no managed-block interiors; no historical records or `*.jsonl`. Unscoped, it walks every indexed doc in several passes and stops partway. It cannot run commands → script behaviour and deployed values from this list. Compress pass can delete a warning — next reader checks every removed "never", "always", or trap. Docs other code reads: hand-fix, then tests `Handoff` finds. Do not trust "synced"; re-grep every changed claim. **Done when:** `Claims` row per hit: `file:line` · what the doc said · what the code does · severity · destination.
121
+ Destinations:
122
+ - **If** the doc is wrong **and** the code is right → a doc edit.
123
+ - **If** the doc is right **and** the code is wrong → a `docs/failures.jsonl` row, which `@bkit-utility-update-failures` applies. Do not "fix" the doc to match the bug.
124
+ - **If** there is no recorded intent → a question for the maintainer.
125
+ - **If** it is a statement about the product's shape → proposed wording for the owner before it lands.
126
+ - **If** the drift is inside `bkit:start` / `bkit:end` → an upstream bkit fix. Do not edit there, because `bkit install` overwrites it.
138
127
 
139
- - [ ] **Step 7 — Setup:** Setup doc enough: new developer or agent in fresh session/worktree gets clean clone → running app and passing local suite using only that doc. Cheap checks every run. Full walk every run.
128
+ Write the handoff for `@bkit-utility-update-documentation`; this run does not invoke it. Give it findings from this report only, known drift first (the `file:line` and the code that disproves it), no managed-block interiors, and no historical records or `*.jsonl`. Unscoped, it walks every indexed doc in several passes and stops partway. It cannot run commands, so give it script behaviour and deployed values from this list. A compress pass can delete a warning, so the next reader checks every removed "never", "always" or trap. For docs that other code reads, fix by hand, then run the tests that `Handoff` finds. Do not trust "synced"; re-grep every changed claim. **Done when:** `Claims` has a row per hit: `file:line` · what the doc said · what the code does · severity · destination.
140
129
 
141
- Cheap checks: tool versions in doc vs manifest and version files (e.g. `engines`, `packageManager`, `.nvmrc`, `.python-version`, `rust-toolchain.toml`); every binary a package script, git hook, or local CI runner calls is listed (hook dying on missing binary = usual first-day stop); required vs optional still right (nothing calls it, or platform retired → not required); every command and path in doc exists; every variable code reads is in example env or doc says where to get it, every example variable still read, doc names right example file and how loaded; doc says what agent needs that person already has (env trust in new worktree, language-server provisioning, which steps cloud session cannot run).
130
+ - [ ] **Step 7 — Setup:** The setup doc is enough when a new developer, or an agent in a fresh session or worktree, gets from a clean clone to a running app and a passing local suite using only that doc. Run the cheap checks and the full walk on every run.
142
131
 
143
- Full walk → fresh clone into temp directory, not worktree of this checkout (hides missing steps). Follow doc literally, in order. Every time you need something the doc did not say = finding. Goal states, in order, with time each takes: install succeeds; local app serves on doc's port and sign-in works; local static, unit, and integration gate passes; local end-to-end passes; mobile section, when doc has one, through simulator and emulator. Then new worktree of existing checkout through first test passing (agent path). Then which goal states cloud session can reach, and whether doc says which it cannot. Secrets: doc says where each comes from, and whether that works without asking a person. never paste a value. **Done when:** `Setup` row per cheap check; when walk ran, time per goal state and every point doc was not enough.
132
+ Cheap checks: the tool versions in the doc match the manifest and version files (e.g., `engines`, `packageManager`, `.nvmrc`, `.python-version`, `rust-toolchain.toml`). Every binary that a package script, git hook or local CI runner calls is listed; a hook dying on a missing binary is the usual first-day stop. Required and optional are still right: **if** nothing calls a tool, **or** its platform is retired → it is not required. Every command and path in the doc exists. Every variable the code reads is in the example env, or the doc says where to get it. Every example variable is still read, and the doc names the right example file and how it is loaded. The doc says what an agent needs that a person already has: env trust in a new worktree, language-server provisioning, and which steps a cloud session cannot run.
144
133
 
145
- - [ ] **Step 8 — Runbooks:** Procedure exists for each, named by doc and section: production rollback, per host (web deploy, native update plus store build when those exist); database restore and point-in-time recovery; migration fails partway through push; secret rotation, per provider; failing or poisoned background-job queue; outage at primary dependency; user data export and deletion request. Walk every procedure with `Claims` checks: every command exists, every path real, every dashboard step still matches. Missing procedure = finding. Says who to tell but not what to run = finding. Destination: doc and section to add, also `bkit-audit-reliability`. **Done when:** `Runbooks` lists each procedure and its walk.
146
- - [ ] **Step 9 — Reference:** HTTP routes external or native client calls → generated, current reference (e.g. OpenAPI), not prose. Each background-event name and payload schema → generated or code-adjacent reference matching what is sent. Shared packages → API-doc validation over each entry point (e.g. TSDoc: broken `{@link}` references, exported symbols with no docs). Gap = finding; fix = generated reference, next step. **Done when:** `Reference` row per surface: present or gap.
147
- - [ ] **Step 10 — Memory:** Local session → auto-memory must point at docs, never copy them. Cloud session → skip and say so.
148
- - Fact only in memory → doc or ledger row it should move to, and pointer to leave behind.
149
- - Memory copying doc → cut to pointer (path, section, one-line hook).
150
- - Pointer at section moved or gone → pointer fix, and whether `Mechanical` missed same move in docs.
151
- - Memory and doc disagree → code decides. Report says which next step should fix.
134
+ Full walk: make a fresh clone into a temp directory, not a worktree of this checkout, because a worktree hides missing steps. Follow the doc literally, in order. Every time you need something the doc did not say is a finding. Reach these goal states in order, recording the time each takes: the install succeeds; the local app serves on the doc's port and sign-in works; the local static, unit and integration gate passes; local end-to-end passes; and, when the doc has a mobile section, the simulator and emulator run. Then take a new worktree of the existing checkout through to the first passing test, which is the agent path. Then record which goal states a cloud session can reach, and whether the doc says which it cannot. Secrets: the doc says where each one comes from, and whether that works without asking a person. Never paste a value. **Done when:** `Setup` has a row per cheap check, and, when the walk ran, the time per goal state and every point where the doc was not enough.
152
135
 
153
- **Done when:** `Memory` holds each hit, or the skip recorded.
136
+ - [ ] **Step 8 — Runbooks:** Check that a procedure exists for each case below, named by doc and section: production rollback, per host (web deploy, plus native update and store build when those exist); database restore and point-in-time recovery; a migration that fails partway through a push; secret rotation, per provider; a failing or poisoned background-job queue; an outage at the primary dependency; and a user data export and a user data deletion request. Walk every procedure with the `Claims` checks: every command exists, every path is real, and every dashboard step still matches. A missing procedure is a finding. A procedure that says who to tell but not what to run is a finding. The destination is the doc and section to add, and also `bkit-audit-reliability`. **Done when:** `Runbooks` lists each procedure and its walk.
137
+ - [ ] **Step 9 — Reference:** **If** an external or native client calls HTTP routes → they need a generated, current reference (e.g., OpenAPI), not prose. Each background-event name and payload schema needs a generated or code-adjacent reference that matches what is sent. **If** the project has shared packages → run API-doc validation over each entry point (e.g., TSDoc: broken `{@link}` references, exported symbols with no docs). A gap is a finding, and the fix is a generated reference in the next step. **Done when:** `Reference` has a row per surface: present or gap.
138
+ - [ ] **Step 10 — Memory:** **If** the session is local → auto-memory must point at docs, never copy them. **If** the session is in the cloud → skip this step and say so.
139
+ - **If** a fact is only in memory → name the doc or ledger row it should move to, and the pointer to leave behind.
140
+ - **If** memory copies a doc → cut it to a pointer (path, section, one-line hook).
141
+ - Run the Step 4 path resolver over the memory files.
142
+ - **If** a pointer aims at a section that moved or is gone → name the pointer fix, and whether `Mechanical` missed the same move in the docs.
143
+ - **If** memory and a doc disagree → the code decides. The report says which next step should fix it.
154
144
 
155
- - [ ] **Step 11 — Rules:** Read instruction files IDE loads side by side (`AGENTS.md`, `CLAUDE.md`, IDE rule files, `.agents/rules.md`, any other). Directive one forbids, or two commands for same task = finding. Inside `bkit:start` / `bkit:end` → upstream bkit fix. Destination: proposed wording, for owner to pick rule that stands. Load size: byte size of always-applied files, and about a quarter of that in tokens, as a series. Growth with no new rule = copying. **Done when:** `Rules` lists contradictions and load size.
156
- - [ ] **Step 12 — Topics:** Two docs on one topic = bug (`.agents/docs.md`): pick home, delete copy, link to home. Look in order: same table or list in two docs; section in domain doc repeating ledger row; audit report still giving advice doc replaced. Label each live doc by Diátaxis quadrant (tutorial, how-to, reference, explanation). Doc mixing quadrants = finding for split. Topic agents need with no doc in right quadrant = finding for new one. Record labels so next run diffs them. `@bkit-utility-compress-markdown` overwrites one file per call; this run does not invoke it. Long prose doc may be named as candidate. Never a doc tests parse, never a ledger. **Done when:** `Topics` holds duplicates, quadrant labels, and any compress candidate.
157
- - [ ] **Step 13 — Handoff:** This run does not edit docs. Read CI workflow for what docs-only push actually runs. Record recheck next step owes after edits this report names: prose lint, format check, managed-block check, `Mechanical` and `Ledgers` again (both should list nothing new), and every test that reads a doc the report says to touch. Find those tests (`git grep -l`), do not list from memory. Change to code comment, script, or migration = code change → normal lanes. **Done when:** `Handoff` names recheck commands and tests.
158
- - [ ] **Step 14 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per Diátaxis quadrant, link, and anchor checking, decision records, runbooks, each community health file, and API or package reference → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
159
- - [ ] **Step 15 — Anything Else:** (a) Everything changed since previous report's commit touching docs (new or renamed docs, `.agents/*.md` and other rule files, package scripts, env vars, routes, background events, new ledger rows, new external services) → one-line verdict each. (b) Bounded ~30 min pass: what senior technical writer flags that no step asks; read what happened since previous run (incidents, `bkit-audit-logs` reports, new `docs/failures.jsonl` rows, vendor status incidents) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
145
+ **Done when:** `Memory` holds each hit, or the skip is recorded.
160
146
 
161
- ### 🔒 Gate 2: Probes Check
147
+ - [ ] **Step 11 — Rules:** Read the instruction files the IDE loads side by side (`AGENTS.md`, `CLAUDE.md`, IDE rule files, `.agents/rules.md`, and any other). A directive that one file forbids, or two commands for the same task, is a finding. **If** it is inside `bkit:start` / `bkit:end` → it is an upstream bkit fix. The destination is proposed wording, so the owner can pick the rule that stands. Record the load size as a series: the byte size of the always-applied files, and about a quarter of that in tokens. Growth with no new rule means copying. **Done when:** `Rules` lists the contradictions and the load size.
148
+ - [ ] **Step 12 — Topics:** Two docs on one topic is a bug (`.agents/docs.md`).
149
+ - Look for duplicates in this order: the same table or list in two docs; a section in a domain doc that repeats a ledger row; and an audit report still giving advice that a doc replaced.
150
+ - For each duplicate, name the home, the copy to delete and the link to add, for the next step to apply.
151
+ - Label each live doc with its Diátaxis quadrant (tutorial, how-to, reference, explanation).
152
+ - Record the labels, so the next run can diff them.
153
+ - A doc that mixes quadrants is a finding for a split.
154
+ - A topic agents need with no doc in the right quadrant is a finding for a new one.
155
+ - A long prose doc may be named as a candidate for `@bkit-utility-compress-markdown`, which overwrites one file per call. This run does not invoke it.
156
+ - Never name a doc that tests parse, or a ledger, as a compress candidate.
157
+
158
+ **Done when:** `Topics` holds the duplicates, the quadrant labels, and any compress candidate.
159
+
160
+ - [ ] **Step 13 — Handoff:** This run does not edit docs. Read the CI workflow for what a docs-only push actually runs. Record the recheck the next step owes after the edits this report names: prose lint, the format check, the managed-block check, `Mechanical` and `Ledgers` again (both should list nothing new), and every test that reads a doc the report says to touch. Find those tests with `git grep -l`; do not list them from memory. A change to a code comment, a script or a migration is a code change, and takes the normal lanes. **Done when:** `Handoff` names the recheck commands and tests.
161
+ - [ ] **Step 14 — Standards:** Confirm the current version of each anchor standard, and read what changed since the previous report's version. In `Standards Coverage`, give one row per Diátaxis quadrant, plus one row each for link checking, anchor checking, decision records, runbooks, each community health file, and the API or package reference, marked checked (with the step), not applicable (saying why) or finding. Mark each recommended practice the project does not apply as adopt (with a proposed step), reject (saying why) or not applicable. **Done when:** no row is empty.
162
+ - [ ] **Step 15 — Anything Else:** (a) List everything changed since the previous report's commit that touches docs (new or renamed docs, `.agents/*.md` and other rule files, package scripts, env vars, routes, background events, new ledger rows and new external services), with a one-line verdict each. (b) In a bounded pass of about 30 minutes, note what a senior technical writer would flag that no step asks about. Read what happened since the previous run (incidents, `bkit-audit-logs` reports, new `docs/failures.jsonl` rows and vendor status incidents), and note what no step would catch. **Done when:** `Beyond the Steps` holds both passes, or says `none`. **If** one class of issue is seen on 2 runs → propose a step for it in `Process Improvements`.
162
163
 
163
- **Checkpoint.** Verify and check `[x]` all boxes below, then continue to `Findings` without asking.
164
+ ### 🔒 Gate 2: Probes Check
164
165
 
165
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
166
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
167
- - [ ] **No secrets:** no secret or credential value anywhere in the report.
168
- - [ ] **Tree clean:** no doc, ledger, memory, or instruction file changed; scratch only under repo-root `tmp/`.
169
- - [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off.
166
+ - [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
167
+ - [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
168
+ - [ ] **No secrets:** no secret or credential value appears anywhere in the report.
169
+ - [ ] **Docs untouched:** no live doc, memory file or instruction file changed, other than the template's `Project Instructions`.
170
+ - [ ] **Ledger rows untouched:** no existing ledger row changed.
171
+ - [ ] **Scratch in tmp:** scratch files are only under the repo-root `tmp/`.
172
+ - [ ] **Gate 2 — Verified:** every item above holds.
170
173
 
171
174
  ## Findings
172
175
 
173
176
  <!-- prettier-ignore -->
174
177
  | Severity | Use |
175
178
  | --- | --- |
176
- | `CRITICAL` | Following the doc destroys data, skips a safety check, or blocks a fresh start with no workaround written; instruction files contradict on a safety rule |
177
- | `HIGH` | Doc states the opposite of the code on a flag, default, or platform shape; pointer an agent follows that leads nowhere; fact running code depends on, and no ledger row holds it; setup gap with a known workaround |
178
- | `MEDIUM` | Drifted `file:line`, count, or list; table that renders as raw text or drops cells; setup command wrong but recoverable; missing runbook; missing generated reference; same topic in two docs; mixed Diátaxis quadrant; choice with no decision row |
179
- | `LOW` | Catalogue one-line scope slightly off; wording drift that changes no instruction; quadrant label with no split needed |
179
+ | `CRITICAL` | Following the doc destroys data, skips a safety check, or blocks a fresh start with no workaround written. Instruction files contradict each other on a safety rule. |
180
+ | `HIGH` | The doc states the opposite of the code on a flag, a default or a platform shape. A pointer an agent follows leads nowhere. Running code depends on a fact that no ledger row holds. The setup doc has a gap with a known workaround. |
181
+ | `MEDIUM` | A `file:line`, count or list has drifted. A table renders as raw text or drops cells. A setup command is wrong but recoverable. A runbook is missing. A generated reference is missing. The same topic is in two docs. A doc mixes Diátaxis quadrants. A choice has no decision row. |
182
+ | `LOW` | A catalogue one-line scope is slightly off. Wording drift changes no instruction. A quadrant label needs no split. |
180
183
 
181
- Scale per `.bkit/jsonl.md` § Severity. Within a severity: destructive steps and contradictions first.
184
+ Within a severity, list destructive steps and contradictions first.
182
185
 
183
186
  <!-- prettier-ignore -->
184
187
  | ID | Severity | Location | Evidence | Expected |
185
188
  | --- | --- | --- | --- | --- |
186
189
  | PENDING | PENDING | PENDING | PENDING | PENDING |
187
190
 
188
- Empty and clean → one row `None`.
191
+ **If** the run finds nothing → write one row: `None`.
189
192
 
190
193
  ## Report
191
194
 
@@ -274,17 +277,15 @@ PENDING
274
277
 
275
278
  ### 🔒 Gate 3: Report Check
276
279
 
277
- **Checkpoint.** Verify and check `[x]` all boxes below, then stop.
278
-
279
- - [ ] **No placeholders:** Findings table and every `Report` section have no `PENDING`.
280
- - [ ] **Summary:** names count per severity.
281
- - [ ] **Series:** load size, and setup-walk times when the walk ran, beside previous report's numbers, or marked baseline.
282
- - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
283
- - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
284
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
285
- - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
286
-
287
- > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
280
+ - [ ] **No placeholders:** no `PENDING` is left.
281
+ - [ ] **Summary:** `Summary` gives the count per severity.
282
+ - [ ] **Series:** the report shows load size, and setup-walk times when the walk ran, beside the previous report's numbers, or marks the run as baseline.
283
+ - [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
284
+ - [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
285
+ - [ ] **Process Improvements:** `Universal` and `Project` are both filled.
286
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
287
+ - [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
288
+ - [ ] **Gate 3 — Verified:** every item above holds.
288
289
 
289
290
  <!-- bkit:end -->
290
291