@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,171 +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
14
  > - NEVER paste a secret or credential value into the report.
15
- > - 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.
16
16
 
17
17
  ## Universal Instructions
18
18
 
19
19
  ### Context & Goals
20
20
 
21
- 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.
22
22
 
23
- **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.
24
24
 
25
- **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".
26
26
 
27
- **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).
28
28
 
29
29
  **Anchor Standards:**
30
30
 
31
31
  - Diátaxis (unversioned; record the date read).
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.
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.
38
38
 
39
39
  ### Scope
40
40
 
41
- - Every live doc, every run.
42
- - Catalogue: `.agents/docs.md` rows vs files on disk, and the root entry point.
43
- - Mechanical: prose, format, managed-block drift, backticked paths, links, and anchors, commands, diagrams.
44
- - Ledger citations resolve to one winning row; significant choices have a `docs/decisions.jsonl` row.
45
- - Claims in every live doc vs the code.
46
- - Setup doc enough to start. Runbooks exist and each is walked.
47
- - Generated reference for HTTP APIs, background events, and shared packages.
48
- - 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.
49
50
 
50
51
  ### Out of Scope
51
52
 
52
53
  <!-- prettier-ignore -->
53
54
  | Excluded item | Why | Where it belongs |
54
55
  | --- | --- | --- |
55
- | Whether a doc is in the right place | Placement | `bkit-audit-repo` |
56
- | 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` |
57
- | Capability-register status (`one` / `bypassed` / `split` / `gap`) | Duplication sweep | `bkit-audit-duplication` |
58
- | Architecture graph diagram correctness | Architecture sweep | `bkit-audit-architecture` |
59
- | Turning a check into a CI gate | Gate design | `bkit-audit-gates` |
60
- | A stale fact inside a historical record | History, not a defect | Citers only; fix a dead pointer at the target |
61
- | Instruction files each agent host loads; agent permissions, hooks, tool servers | Agent config sweep | `bkit-audit-agents` |
62
- | 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 |
63
64
 
64
65
  ### Pre-Flight / Dependencies
65
66
 
66
67
  #### Core
67
68
 
68
- - [ ] **Permissions:** blocked calls recorded
69
- - [ ] **Repo Read:** Steps 2-13 — live docs, instruction files, manifests, CI workflow. Fallback: none; unreadable tree = finding.
70
- - [ ] **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.
71
72
 
72
73
  #### Conditional
73
74
 
74
- - [ ] **Prose and Format:** Step 4 — e.g. Vale, Prettier. Fallback: skip that check; name it in `Not Checked`.
75
- - [ ] **Managed-Block Check:** bkit project → Step 4 — e.g. `bkit check`. Fallback: read managed blocks; drift `Not Checked`.
76
- - [ ] **Link Checker:** Step 4 — offline fragments plus cached external URLs, e.g. lychee. Fallback: open relative links by hand; external URLs `Not Checked`.
77
- - [ ] **Diagram Renderer:** Fenced diagrams → Step 4 — e.g. mermaid-cli, headless browser. Fallback: skip render; `Not Checked`. A cloud session may lack the browser.
78
- - [ ] **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`.
79
- - [ ] **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`.
80
81
 
81
82
  ### 🔒 Gate 1: Prerequisites Check
82
83
 
83
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
84
- - [ ] **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.
85
86
 
86
87
  ### Probe Steps
87
88
 
88
- - [ ] **Step 1 — Previous Run:** **Done when:** closure rate in `Previous Run`, or run marked baseline.
89
- - [ ] **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`.
90
- - [ ] **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.
91
- - [ ] **Step 4 — Mechanical:** Run prose lint, format check, and managed-block check. Then:
92
- - 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`.
93
- - 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.
94
- - 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.
95
- - Diagrams still parse (e.g. Mermaid). Syntax break renders as raw text with no CI signal. Render each live doc that has one.
96
- - 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.
97
99
 
98
- 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.
99
101
 
100
- - [ ] **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:
101
- - Live doc or code comment → report names citation change to row's `key`. This run does not edit.
102
- - `docs/completed.md` or plan → do not edit. Report names new version of owning row to append, with old id in `references`.
103
- - 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.
104
106
 
105
- 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.
106
108
 
107
- - [ ] **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.
108
110
 
109
111
  <!-- prettier-ignore -->
110
112
  | Claim type | Check against |
111
113
  | --- | --- |
112
- | 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 |
113
115
  | What a script does | The script, end to end. Look hardest for anything that deletes |
114
116
  | Which parts exist, on which platform | The code, on every platform the doc claims |
115
117
  | `file:line` | Open the line. It must still say what the doc claims |
116
118
  | Section links (`§ Heading`) | The heading exists, word for word |
117
119
  | Counts and lists | Count them again |
118
120
 
119
- 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.
127
+
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.
129
+
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.
131
+
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.
120
133
 
121
- - [ ] **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.
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.
122
135
 
123
- 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).
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.
124
144
 
125
- 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.
145
+ **Done when:** `Memory` holds each hit, or the skip is recorded.
126
146
 
127
- - [ ] **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.
128
- - [ ] **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.
129
- - [ ] **Step 10 — Memory:** Local session → auto-memory must point at docs, never copy them. Cloud session → skip and say so.
130
- - Fact only in memory → doc or ledger row it should move to, and pointer to leave behind.
131
- - Memory copying doc → cut to pointer (path, section, one-line hook).
132
- - Pointer at section moved or gone → pointer fix, and whether `Mechanical` missed same move in docs.
133
- - Memory and doc disagree → code decides. Report says which next step should fix.
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.
134
157
 
135
- **Done when:** `Memory` holds each hit, or the skip recorded.
158
+ **Done when:** `Topics` holds the duplicates, the quadrant labels, and any compress candidate.
136
159
 
137
- - [ ] **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.
138
- - [ ] **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.
139
- - [ ] **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.
140
- - [ ] **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.
141
- - [ ] **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`.
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`.
142
163
 
143
164
  ### 🔒 Gate 2: Probes Check
144
165
 
145
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
146
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
147
- - [ ] **No secrets:** no secret or credential value anywhere in the report.
148
- - [ ] **Tree clean:** no doc, ledger, memory, or instruction file changed; scratch only under repo-root `tmp/`.
149
- - [ ] **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.
150
173
 
151
174
  ## Findings
152
175
 
153
176
  <!-- prettier-ignore -->
154
177
  | Severity | Use |
155
178
  | --- | --- |
156
- | `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 |
157
- | `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 |
158
- | `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 |
159
- | `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. |
160
183
 
161
- Within a severity: destructive steps and contradictions first.
184
+ Within a severity, list destructive steps and contradictions first.
162
185
 
163
186
  <!-- prettier-ignore -->
164
187
  | ID | Severity | Location | Evidence | Expected |
165
188
  | --- | --- | --- | --- | --- |
166
189
  | PENDING | PENDING | PENDING | PENDING | PENDING |
167
190
 
168
- Empty and clean → one row `None`.
191
+ **If** the run finds nothing → write one row: `None`.
169
192
 
170
193
  ## Report
171
194
 
@@ -254,13 +277,15 @@ PENDING
254
277
 
255
278
  ### 🔒 Gate 3: Report Check
256
279
 
257
- - [ ] **No placeholders:** no `PENDING` left
258
- - [ ] **Summary:** names count per severity.
259
- - [ ] **Series:** load size, and setup-walk times when the walk ran, beside previous report's numbers, or marked baseline.
260
- - [ ] **Writes:** only this report, template `Project Instructions`, and ledger rows changed; throwaway worktrees / remote targets removed.
261
- - [ ] **Process Improvements:** `Universal` and `Project` filled
262
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
263
- - [ ] **Gate 3 — Verified:** Every checkbox above independently verified and checked off.
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.
264
289
 
265
290
  <!-- bkit:end -->
266
291