@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,9 +1,9 @@
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
  # Usability Review
8
8
 
9
9
  > [!CAUTION]
@@ -11,142 +11,160 @@
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
- > - NEVER commit, push, or start a metered native build to produce shots. Use an artifact that already exists.
23
- > - Seeded-defect copies stay in scratch. never write them into the app, the manifest under test, or this report as product shots.
24
- > - Session notes name the segment, not the person. never copy a personal-data value from a screen into the report.
14
+ > - NEVER commit, push or start a metered native build to produce shots. Use an artifact that already exists.
15
+ > - Keep seeded-defect copies in scratch. Never write them into the app, the manifest under test, or this report as product shots.
16
+ > - Name the segment in session notes, not the person.
17
+ > - NEVER copy a personal-data value into the report.
25
18
 
26
19
  ## Universal Instructions
27
20
 
28
21
  ### Context & Goals
29
22
 
30
- Automated checks never look at a screen. They pass when a title is centred on one platform and left-aligned on another, when an empty state was never drawn, or when a label overflows. Drawings are the reference for how a screen should look, so drift from the drawing is a defect with every test green. Target failure: a screen that does not match its drawing, its twin on another platform, or a path a new user can finish.
23
+ Automated checks never look at a screen. They pass when a title is centred on one platform and left-aligned on another, when an empty state was never drawn, or when a label overflows. Drawings are the reference for how a screen should look, so drift from the drawing is a defect even with every test green. The failure this audit targets is a screen that does not match its drawing or its twin on another platform, or a path a new user cannot finish.
31
24
 
32
- **Applies when:** user-facing screens. None → one `N/A` row with evidence, never "clean".
25
+ **Applies when:** the product has user-facing screens. **If** it has none → write one `N/A` row with its evidence, and never report the surface as "clean".
33
26
 
34
- **Cadence:** monthly. Extra pass when a shared component, the palette, or a route's layout changes. Every second run includes the sessions in `Sessions`.
27
+ **Cadence:** Run once a month. Run an extra pass when a shared component, the palette or a route's layout changes. Every second run includes the sessions in `Sessions`.
35
28
 
36
- **Anchor Standards:** record version and date read. Newer version → `Standards` step reads what changed.
29
+ **Anchor Standards:**
37
30
 
38
31
  - Nielsen's 10 usability heuristics (NN/g, the 1994 set).
39
32
  - NN/g severity ratings: frequency, impact, and persistence.
40
33
  - ISO 9241-11:2018 (effectiveness, efficiency, and satisfaction).
41
34
  - ISO 9241-110:2020 (interaction principles).
42
- - Platform interface guidelines (e.g. Apple Human Interface Guidelines, Material Design 3). Living documents; record the date read.
43
- - Human-AI interaction guidelines (e.g. Microsoft HAX, 18 guidelines; Google PAIR Guidebook).
44
- - Task metrics (e.g. task success, time on task, Single Ease Question, SUS, UMUX-Lite) and the five-participant round.
35
+ - Platform interface guidelines (e.g., Apple Human Interface Guidelines, Material Design 3). Living documents; record the date read.
36
+ - Human-AI interaction guidelines (e.g., Microsoft HAX, 18 guidelines; Google PAIR Guidebook).
37
+ - Task metrics (e.g., task success, time on task, Single Ease Question, SUS, UMUX-Lite) and the five-participant round.
45
38
 
46
39
  ### Scope
47
40
 
48
- - Rendered screens beside their drawings and beside the same screen on other platforms.
49
- - Routes and states the capture did not reach.
50
- - A new user's first journey, per platform.
51
- - Heuristics on the primary flows, including when the drawing itself is the defect.
52
- - Copy, locale format, findability, platform conventions, notifications, poor network, and device switching.
53
- - Errors, forms, and destructive actions.
54
- - AI features the user must see, correct, and undo.
55
- - Scripted sessions with real people, every second run.
41
+ - Compare rendered screens with their drawings, and with the same screen on other platforms.
42
+ - List the routes and states the capture did not reach.
43
+ - Walk a new user's first journey on each platform.
44
+ - Check the primary flows against the heuristics, including when the drawing itself is the defect.
45
+ - Check copy, locale format, findability, platform conventions, notifications, poor network and device switching.
46
+ - Check errors, forms and destructive actions.
47
+ - Check that the user can see, correct and undo what AI features do.
48
+ - Run scripted sessions with real people every second run.
56
49
 
57
50
  ### Out of Scope
58
51
 
59
52
  <!-- prettier-ignore -->
60
53
  | Excluded item | Why | Where it belongs |
61
54
  | --- | --- | --- |
62
- | Contrast, target size, focus, labels | Same screens, different sweep | `bkit-audit-accessibility` |
63
- | A value or control implemented twice | Duplication sweep | `bkit-audit-duplication` |
64
- | Funnel or feedback instrumentation | Analytics sweep | `bkit-audit-analytics` |
65
- | Store listing declarations | Store sweep | `bkit-audit-app-store` |
66
- | Model output, when the screen already shows, corrects, and undoes it | Model sweep | `bkit-audit-llm` |
67
- | Price, renewal, or cancel wording vs consumer law | Privacy sweep | `bkit-audit-privacy` |
68
- | Capture pipeline (bad crop, unpaired row, missing cell, canary miss) | Pipeline, not the screen | Plan from this report |
69
- | Changing screens or drawings | Audit reports only | Plan from this report |
55
+ | Contrast, target size, focus, labels | The same screens, in a different sweep | `bkit-audit-accessibility` |
56
+ | A value or control implemented twice | The duplication sweep owns it | `bkit-audit-duplication` |
57
+ | Funnel or feedback instrumentation | The analytics sweep owns it | `bkit-audit-analytics` |
58
+ | Store listing declarations | The store sweep owns them | `bkit-audit-app-store` |
59
+ | Model output, when the screen already shows, corrects, and undoes it | The model sweep owns it | `bkit-audit-llm` |
60
+ | Price, renewal, or cancel wording vs consumer law | The privacy sweep owns it | `bkit-audit-privacy` |
61
+ | Capture pipeline (bad crop, unpaired row, missing cell, canary miss) | It is the pipeline, not the screen | A plan made from this report |
62
+ | Changing screens or drawings | The audit only reports | A plan made from this report |
70
63
 
71
64
  ### Pre-Flight / Dependencies
72
65
 
73
- **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.
74
-
75
- **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.
76
-
77
66
  #### Core
78
67
 
79
- Always verify.
80
-
81
- - [ ] **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.
82
- - [ ] **Screens:** Steps 2, 7–14 — open product (local or existing preview). Fallback: drawings and source only; live claims = hypotheses.
83
- - [ ] **Drawings:** Steps 5, 7, 9 — reference drawings readable. Fallback: live vs live only; drawing comparison `Not Checked`.
84
- - [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
68
+ - [ ] **Permissions:** every blocked call is recorded.
69
+ - [ ] **Screens:** Steps 2, 7-14 — open the product, locally or on an existing preview. Fallback: read the drawings and source only, and treat live claims as hypotheses.
70
+ - [ ] **Drawings:** Steps 5, 7, 9 — readable reference drawings. Fallback: compare live with live only, and mark the drawing comparison `Not Checked`.
71
+ - [ ] **Web:** Step 15 — fetch the anchor standards. Fallback: record the versions as unread.
85
72
 
86
73
  #### Conditional
87
74
 
88
- Verify only when applicable.
89
-
90
- - [ ] **Capture Artifact:** Screenshot-capture pipeline exists, finished run's artifact inside retention window → Steps 3–6. Fallback: hand walk; capture `Not Checked`. NEVER push or start a run.
91
- - [ ] **Vision:** Image review → Steps 5–6 — agent opens every PNG. Fallback: hand comparison; record images not opened.
92
- - [ ] **Phone Runtimes:** Phone apps ship → Step 8 — simulator, emulator, or device. Fallback: web only; phone `Not Checked`.
93
- - [ ] **Locale Catalogue:** More than one locale, or a pseudo-locale → Step 8. Fallback: source-language copy only.
94
- - [ ] **Participants:** Session run → Step 11. Fallback: last round's date and next due date; figures `Not Checked`.
75
+ - [ ] **Capture Artifact:** **If** a screenshot-capture pipeline exists, **and** a finished run's artifact is inside the retention window → Steps 3-6 — the capture artifact. Fallback: walk by hand, and mark the capture `Not Checked`. NEVER push or start a run.
76
+ - [ ] **Vision:** **If** the agent can review images → Steps 5-6 — the agent opens every PNG. Fallback: compare by hand, and record the images not opened.
77
+ - [ ] **Phone Runtimes:** **If** phone apps ship → Step 8 — a simulator, emulator or device. Fallback: cover web only, and mark phone `Not Checked`.
78
+ - [ ] **Locale Catalogue:** **If** there is more than one locale, **or** a pseudo-locale → Step 8 — the locale catalogue. Fallback: check the source-language copy only.
79
+ - [ ] **Participants:** **If** a session is run → Step 11 — the participants. Fallback: record the last round's date and the next due date, and mark the figures `Not Checked`.
95
80
 
96
81
  ### 🔒 Gate 1: Prerequisites Check
97
82
 
98
- **Checkpoint.** Verify and check `[x]` all applicable boxes above, then continue to `Probe Steps` without asking.
99
-
100
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
101
- - [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
83
+ - [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
84
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
102
85
 
103
86
  ### Probe Steps
104
87
 
105
- - [ ] **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.
106
- - [ ] **Step 2 — Signals:** Since previous report: funnel drop-off on core flows, support tickets, store-review themes, in-app feedback. Top 5 complaints → each a finding or explained by run end. No users yet → `no users yet`. Missing or untrustworthy funnel data stays listed; fix → `bkit-audit-analytics`. **Done when:** `Signals` holds the five, or `no users yet`.
107
- - [ ] **Step 3 — Capture:** Project has a screenshot-capture pipeline (`Project Instructions` names it, incl. how a run opts in, e.g. commit-message marker) → use finished run with artifact still inside retention window. No pipeline or no such run → hand walk; capture `Not Checked`. Record run id, event type, opt-in markers. Fetch and review before artifact expires. **Done when:** run id in `Capture`, or absence recorded.
108
- - [ ] **Step 4 — Manifest:** Download that run's report artifact. Read manifest and gap step in same job's log, where the pipeline emits them: every route and test id the run did not reach → this run's blind spot. **Done when:** manifest path in `Capture` and gap list in `Gaps`, or skip recorded.
109
- - [ ] **Step 5 — Review:** Side-by-side image per row. Reviewer opens every image; reads each row (drawing, viewport, full page, each platform with a cell). Rules: rows, not pairs (one row per screen × state × size × theme the pipeline captures); status bar, home indicator, and keyboard are never findings; blocked or missing native cell = pipeline or surface with no phone screen, never app defect; cut drawing stops at control its state is about — region below cut not missing; viewport↔viewport, full page↔full page (heights differ by construction); same scale → metrics may compare, different scale → layout and presence only. Inventory on full-page pair only: items in drawing missing from app, items in app missing from drawing — names, not counts; do not fold inventory into parity severity. Verdicts not deterministic → Step 7. **Done when:** every row has verdict or explicit skip; `Inventory` names both directions or `none`.
110
- - [ ] **Step 6 — Canary:** Run that finds nothing reads like blind reviewer. Copy few rows' shots to scratch; seed known defects (title off centre, truncated button label, blank drawn empty state). Point manifest copy at them; review those rows only. Record hit rate. Missed seed = pipeline finding, not app defect. **Done when:** hit rate in `Canary`.
111
- - [ ] **Step 7 — Verify:** No finding counts until PNG and live screen at same width and theme opened; drawing compared and wins on arrangement when they disagree; pipeline ruled out; value or control checked for second implementation (platform file split, both consumers). Second copy still recorded here → belongs to `bkit-audit-duplication`. Each finding cites PNG, live screen, drawing, or source line. **Done when:** every finding has that evidence.
112
- - [ ] **Step 8 — Hand Checks:** What shots do not cover. While phone cells blocked → walk primary flows on each phone platform, light and dark, against same drawings. States seed does not produce (empty, loading, failed request): each not seen = unchecked, not clean. Longer text in pseudo-locale; source detail → `bkit-audit-accessibility`. Translations: every key in every locale, no source-language on translated screen, no sentence from joined strings; then read every locale for meaning. Dates, numbers, currency use locale format. Plurals: counts reaching every category locale has (0, 1, 2, 5, 21 cover most) — right branch, not raw pattern or source-language form. Right-to-left target locale → walk primary flow once. Plain language: UI copy and email ~grade 8; one word per concept everywhere; no internal jargon. Findability: five lookups `Project Instructions` name; flag path over 3 taps or clicks. Phone conventions: back gesture and system back, native date/time pickers, share sheet, haptics, safe areas, pull-to-refresh, tab bar. Web: links open in place, browser back works, every screen has URL that opens directly. Notifications and email: worth sending, open right screen; frequency and quiet-hours settings; permission in context when first needed, not at first launch. Poor network on phone: slow/flaky, offline, backgrounding mid-flow, low-end device — record what user sees, whether action queues or fails loudly, whether every skeleton and spinner resolves. Switching devices: start task on phone, finish on web; state, drafts, notifications agree. Plans: comparison understandable, prices show tax and currency, downgrade, and cancel take no more steps than upgrade, no confirm-shaming, and no hidden cancel path. Consumer-law wording → `bkit-audit-privacy`. Everything in `Gaps`. **Done when:** `Hand Checks` lists each item checked, unchecked, or not applicable.
113
- - [ ] **Step 9 — First Run:** Capture account already full. Walk new-user path by hand, as journey, each platform, fresh synthetic account teardown can reap. One row per point: screens and taps, dead ends, words that assume knowledge, verdict per platform. (1) Sign up on web, including confirmation message and link, through first landing — check message, not only screens. (2) Install on phone first — create account? If not, screen says where to go? (3) Multi-tenant → tenant created for them: understand it exists, see and change name, find address or id given. (4) Empty primary screens — each says what to do next or is blank; no drawing of empty state → finding for drawing first: decide, draw, then build. (5) First record by hand from empty screen — appears where expected, empty-state message goes away. (6) Product ingests items from outside app (e.g. forwarded email, upload) → first item: what they see while processing, reply text, when nothing extractable. (7) Invitations exist → join by invitation — different first run, arrive in full tenant. (8) Come back: sign out, sign in, recovery path once; note drawings promise what app lacks. (9) First plan gate or paywall in first session — what it says, whether next step clear. **Done when:** `First Run` has one row per point; condition unmet → `N/A` row with evidence.
114
- - [ ] **Step 10 — Heuristics:** Drawing says how screen should look; nothing above asks whether drawn design is usable — screen matching bad drawing passes. Walk each primary flow; check every screen against Nielsen's 10 heuristics. Each violation = finding with heuristic (`H1` visibility of system status through `H10` help and documentation). Same problem in drawing → finding for drawing first. **Done when:** each primary flow has line in `Checked`; violations are findings.
115
- - [ ] **Step 11 — Sessions:** Screenshot review ≠ user evidence. Every second run: same scripted tasks with real people — five participants from segments `Project Instructions` name; think-aloud; one script in `Sessions` for next round. Per task: success (unaided, with help, failed), time on task, Single Ease Question. Per session: SUS or UMUX-Lite — pick one, keep it. Each figure beside previous session. No participants → last round's date and next due; do not invent figures. **Done when:** `Sessions` holds figures beside previous session, or next due date.
116
- - [ ] **Step 12 — AI Features:** Each user-visible result feature vs human-AI guidelines — user sees what it did and why; each extracted field correctable, each created item undoable; low-confidence flagged, not silently saved; failure says what happened and next step (Step 9 point 6 covers first). Screen already does this, fault is model output → `bkit-audit-llm`. **Done when:** `AI Features` row per feature: guideline · what the user sees · verdict.
117
- - [ ] **Step 13 — Errors:** Trigger every validation and server error on primary forms — each says what happened and how to fix, plain language, next to field. Input survives failed submit, offline mid-form, session expiry. Every destructive action: undo or confirmation, same on every platform, not most prominent when drawing shows otherwise. **Done when:** `Errors` row per form and per destructive action.
118
- - [ ] **Step 14 — Dates:** Product with dates, times, or recurrence → accounts in different locales and timezones. Date format, first day of week, and 12- or 24-hour time follow the locale. Members in different timezones: which timezone each sees, whether app says so when they differ. Event crossing daylight-saving change keeps wall-clock time. Editing recurring event: choice (this event, this and following, all events) clear, each does what it says. No dates → skip with evidence. **Done when:** `Dates` holds answers, or skip recorded.
119
- - [ ] **Step 15 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per Nielsen heuristic, ISO 9241-110 interaction principle, HAX guideline → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
120
- - [ ] **Step 16 — Anything Else:** (a) Everything changed since previous report's commit touching usability (screens and routes, shared components, drawings, copy, emails, notifications, plan gates, AI-produced results) → one-line verdict each. (b) Bounded ~30 min pass: what senior UX researcher flags that no step asks; read since previous run (incidents, new `docs/failures.jsonl` rows) — 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`.
88
+ - [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
89
+ - [ ] **Step 2 — Signals:** Collect, since the previous report, funnel drop-off on core flows, support tickets, store-review themes and in-app feedback. Each of the top 5 complaints becomes a finding, or is explained, by the end of the run. **If** there are no users yet → write `no users yet`. Missing or untrustworthy funnel data stays listed, and its fix goes to `bkit-audit-analytics`. **Done when:** `Signals` holds the five, or `no users yet`.
90
+ - [ ] **Step 3 — Capture:** **If** the project has a screenshot-capture pipeline (`Project Instructions` names it, including how a run opts in, e.g., a commit-message marker) → use a finished run whose artifact is still inside the retention window. **If** there is no pipeline, **or** no such run → walk by hand, and mark the capture `Not Checked`. Record the run id, event type and opt-in markers. Fetch and review the artifact before it expires. **Done when:** `Capture` holds the run id, or the absence is recorded.
91
+ - [ ] **Step 4 — Manifest:** Download that run's report artifact. Read the manifest, and the gap step in the same job's log, where the pipeline emits them. Every route and test id the run did not reach is this run's blind spot. **Done when:** `Capture` holds the manifest path and `Gaps` holds the gap list, or the skip is recorded.
92
+ - [ ] **Step 5 — Review:** Build a side-by-side image per row. The reviewer opens every image, and reads each row: the drawing, viewport, full page, and each platform that has a cell. Review rows, not pairs (one row per screen x state x size x theme the pipeline captures). The status bar, home indicator and keyboard are never findings. A blocked or missing native cell is the pipeline, or a surface with no phone screen, never an app defect. A cut drawing stops at the control its state is about, so the region below the cut is not missing. Compare viewport with viewport, and full page with full page, because their heights differ by construction. At the same scale, metrics may be compared. At a different scale, compare layout and presence only. Take the inventory on the full-page pair only: items in the drawing missing from the app, and items in the app missing from the drawing, by name, not by count. Do not fold the inventory into parity severity. Verdicts are not deterministic, so they go through Step 7. **Done when:** every row has a verdict or an explicit skip, and `Inventory` names both directions or says `none`.
93
+ - [ ] **Step 6 — Canary:** A run that finds nothing looks the same as a reviewer who cannot see. Copy a few rows' screenshots to scratch, and seed known defects in them: a title off centre, a truncated button label, a blank screen where the drawing shows an empty state. Point a copy of the manifest at them, and review those rows only. Record the hit rate. A missed seed is a pipeline finding, not an app defect. **Done when:** the hit rate is in `Canary`.
94
+ - [ ] **Step 7 — Verify:** No finding counts until the PNG and the live screen have been opened at the same width and theme; the drawing has been compared, and wins on arrangement when they disagree; the pipeline has been ruled out; and the value or control has been checked for a second implementation (a platform file split, both consumers). A second copy is still recorded here, and it belongs to `bkit-audit-duplication`. Each finding cites a PNG, live screen, drawing or source line. **Done when:** every finding has that evidence.
95
+ - [ ] **Step 8 — Hand Checks:** Check what the shots do not cover.
96
+ - **If** phone cells are blocked → walk the primary flows on each phone platform, in light and dark, against the same drawings.
97
+ - For states the seed does not produce (empty, loading, failed request), each state not seen is unchecked, not clean.
98
+ - Check longer text in a pseudo-locale, and send the source detail to `bkit-audit-accessibility`.
99
+ - Translations:
100
+ - Check every key in every locale, no source-language text on a translated screen, and no sentence built from joined strings.
101
+ - Read every locale for meaning.
102
+ - Check that dates, numbers and currency use the locale format.
103
+ - Plurals: use counts that reach every category the locale has (0, 1, 2, 5 and 21 cover most), and check that the right branch shows, not the raw pattern or the source-language form.
104
+ - **If** there is a right-to-left target locale → walk the primary flow once in it.
105
+ - Plain language: UI copy and email are at about grade 8, use one word per concept everywhere, and contain no internal jargon.
106
+ - Findability: try the five lookups `Project Instructions` names, and flag any path over 3 taps or clicks.
107
+ - Phone conventions: back gesture and system back, native date and time pickers, share sheet, haptics, safe areas, pull-to-refresh and tab bar.
108
+ - Web: links open in place, browser back works, and every screen has a URL that opens it directly.
109
+ - Notifications and email: each one is worth sending and opens the right screen, there are frequency and quiet-hours settings, and permission is asked in context when first needed, not at first launch.
110
+ - Poor network on a phone (slow or flaky, offline, backgrounding mid-flow, a low-end device): record what the user sees, whether the action queues or fails loudly, and whether every skeleton and spinner resolves.
111
+ - Switching devices: start a task on a phone and finish it on web, and check that state, drafts and notifications agree.
112
+ - Plans: the comparison is understandable, prices show tax and currency, downgrade and cancel take no more steps than upgrade, there is no confirm-shaming, and there is no hidden cancel path. Consumer-law wording goes to `bkit-audit-privacy`.
113
+ - Record every gap in `Gaps`.
114
+
115
+ **Done when:** `Hand Checks` lists each item checked, unchecked, or not applicable.
116
+
117
+ - [ ] **Step 9 — First Run:** The capture account is already full, so walk the new-user path by hand, as a journey, on each platform, with a fresh synthetic account that teardown can reap.
118
+ - Give one row per point: the screens and taps, dead ends, words that assume knowledge, and a verdict per platform.
119
+ - (1) Sign up on web, including the confirmation message and link, through to the first landing. Check the message, not only the screens.
120
+ - (2) Install on a phone first, and check whether the user can create an account there.
121
+ - **If** not → check whether the screen says where to go.
122
+ - (3) **If** the product is multi-tenant **and** a tenant is created for the user → check that they understand it exists, can see and change its name, and can find the address or id they were given.
123
+ - (4) Check that each empty primary screen says what to do next, or record that it is blank.
124
+ - **If** there is no drawing of the empty state → it is a finding for the drawing first: decide, draw, then build.
125
+ - (5) Create the first record by hand from an empty screen, and check that it appears where expected and the empty-state message goes away.
126
+ - (6) **If** the product ingests items from outside the app (e.g., a forwarded email, an upload) → for the first item, record what the user sees while it processes, the reply text, and what happens when nothing can be extracted.
127
+ - (7) **If** invitations exist → join by invitation, which is a different first run that arrives in a full tenant.
128
+ - (8) Come back: sign out, sign in, and use the recovery path once. Note where the drawings promise what the app lacks.
129
+ - (9) Record the first plan gate or paywall in the first session: what it says, and whether the next step is clear.
130
+
131
+ **Done when:** `First Run` has one row per point, and each point whose condition is unmet has an `N/A` row with evidence.
132
+
133
+ - [ ] **Step 10 — Heuristics:** The drawing says how a screen should look, but nothing above asks whether the drawn design is usable, so a screen that matches a bad drawing passes. Walk each primary flow, and check every screen against Nielsen's 10 heuristics. Each violation is a finding that names its heuristic (`H1` visibility of system status through `H10` help and documentation). **If** the same problem is in the drawing → it is a finding for the drawing first. **Done when:** each primary flow has a line in `Checked`, and the violations are findings.
134
+ - [ ] **Step 11 — Sessions:** A screenshot review is not evidence from users. Every second run, run the same scripted tasks with real people: five participants from the segments `Project Instructions` names, thinking aloud, with one script kept in `Sessions` for the next round. For each task, record success (unaided, with help, failed), time on task, and the Single Ease Question. For each session, record SUS or UMUX-Lite: pick one, and keep it. Put each figure beside the previous session's. **If** there are no participants → record the last round's date and the next due date, and do not invent figures. **Done when:** `Sessions` holds the figures beside the previous session's, or the next due date.
135
+ - [ ] **Step 12 — AI Features:** Check each feature that shows the user a result against the human-AI guidelines: the user sees what it did and why; each extracted field can be corrected, and each created item undone; low confidence is flagged, not silently saved; and a failure says what happened and what to do next (Step 9 point 6 covers the first one). **If** the screen already does this and the fault is the model's output → `bkit-audit-llm`. **Done when:** `AI Features` has one row per feature: guideline · what the user sees · verdict.
136
+ - [ ] **Step 13 — Errors:** Trigger every validation and server error on the primary forms. Check that each one says what happened and how to fix it, in plain language, next to the field. Check that input survives a failed submit, going offline mid-form, and session expiry. Check that every destructive action has an undo or a confirmation, behaves the same on every platform, and is not the most prominent control when the drawing shows otherwise. **Done when:** `Errors` has one row per form and per destructive action.
137
+ - [ ] **Step 14 — Dates:** **If** the product has dates, times or recurrence → use accounts in different locales and timezones. Check that the date format, the first day of the week, and 12- or 24-hour time follow the locale. For members in different timezones, record which timezone each one sees, and whether the app says so when they differ. Check that an event crossing a daylight-saving change keeps its wall-clock time. When a recurring event is edited, check that the choice (this event, this and following, all events) is clear, and that each option does what it says. **If** there are no dates → skip with evidence. **Done when:** `Dates` holds the answers, or the skip is recorded.
138
+ - [ ] **Step 15 — Standards:** Confirm the current version of each anchor standard, and read what changed since the previous report's version. Give `Standards Coverage` one row per Nielsen heuristic, ISO 9241-110 interaction principle and HAX guideline, each marked checked (naming 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.
139
+ - [ ] **Step 16 — Anything Else:** (a) Give a one-line verdict on each change since the previous report's commit that touches usability: screens and routes, shared components, drawings, copy, emails, notifications, plan gates and AI-produced results. (b) In a bounded pass of about 30 minutes, note what a senior UX researcher would flag that no step asks about. Read what happened since the previous run (incidents, new `docs/failures.jsonl` rows), and ask 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`.
121
140
 
122
141
  ### 🔒 Gate 2: Probes Check
123
142
 
124
- **Checkpoint.** Verify and check `[x]` all boxes below, then continue to `Findings` without asking.
125
-
126
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
127
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
128
- - [ ] **Canary isolated:** seeded copies are not product shots in this report, and were not written into the app.
143
+ - [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
144
+ - [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
145
+ - [ ] **Canary isolated:** no seeded copy appears as a product shot in this report.
146
+ - [ ] **App untouched:** no seeded copy was written into the app.
129
147
  - [ ] **Pipeline ruled out:** no finding is OS chrome, the region below a cut drawing, or a blocked native cell.
130
- - [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off.
148
+ - [ ] **Gate 2 — Verified:** every item above holds.
131
149
 
132
150
  ## Findings
133
151
 
134
152
  <!-- prettier-ignore -->
135
153
  | Severity | Use |
136
154
  | --- | --- |
137
- | `CRITICAL` | Broken primary flow with no workaround; typed input or a record lost with no recovery; destructive action with no undo that loses data |
138
- | `HIGH` | User cannot finish a task, and a workaround exists; empty first screen with no next step; destructive confirmation missing on one platform |
139
- | `MEDIUM` | Screen ≠ drawing, the drawing is right, and it stops nobody; error text that does not say how to fix it; wrong locale format; one concept named two ways |
140
- | `LOW` | Cosmetic mismatch; region below a cut drawing reported as missing and then corrected to not-reached |
155
+ | `CRITICAL` | A broken primary flow with no workaround. Typed input or a record lost with no recovery. A destructive action with no undo that loses data |
156
+ | `HIGH` | The user cannot finish a task, and a workaround exists. An empty first screen with no next step. A destructive confirmation missing on one platform |
157
+ | `MEDIUM` | A screen that differs from its drawing, where the drawing is right and the difference stops nobody. Error text that does not say how to fix the problem. A wrong locale format. One concept named two ways |
158
+ | `LOW` | A cosmetic mismatch. A region below a cut drawing reported as missing, then corrected to not-reached |
141
159
 
142
- Scale per `.bkit/jsonl.md` § Severity. Within a severity: blocked tasks first. Set bucket from frequency (how many users meet it), impact (whether they can get past it), persistence (whether it bothers them every time). Task user cannot finish = `HIGH`, or `CRITICAL` with no workaround. Drawing mismatch that stops nobody = `MEDIUM` or `LOW`.
160
+ Within a severity, list blocked tasks first. Set the bucket from frequency (how many users meet it), impact (whether they can get past it) and persistence (whether it bothers them every time). A task the user cannot finish is `HIGH`, or `CRITICAL` when there is no workaround. A drawing mismatch that stops nobody is `MEDIUM` or `LOW`.
143
161
 
144
162
  <!-- prettier-ignore -->
145
163
  | ID | Severity | Location | Evidence | Expected |
146
164
  | --- | --- | --- | --- | --- |
147
165
  | PENDING | PENDING | PENDING | PENDING | PENDING |
148
166
 
149
- Empty and clean → one row `None`.
167
+ **If** the run finds nothing → write one row: `None`.
150
168
 
151
169
  ## Report
152
170
 
@@ -231,17 +249,17 @@ PENDING
231
249
 
232
250
  ### 🔒 Gate 3: Report Check
233
251
 
234
- **Checkpoint.** Verify and check `[x]` all boxes below, then stop.
235
-
236
- - [ ] **No placeholders:** Findings table and every `Report` section have no `PENDING`.
237
- - [ ] **Summary:** names count per severity, cells captured vs blocked per platform, and the canary hit rate.
238
- - [ ] **Series:** every series beside previous report's numbers, or marked baseline.
239
- - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
240
- - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
241
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
242
- - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
243
-
244
- > `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.
252
+ - [ ] **No placeholders:** no `PENDING` is left.
253
+ - [ ] **Summary:** `Summary` gives the count per severity.
254
+ - [ ] **Cells:** `Summary` gives the cells captured against blocked per platform.
255
+ - [ ] **Canary rate:** `Summary` gives the canary hit rate.
256
+ - [ ] **Series:** the report shows every series beside the previous report's numbers, or marks the run as baseline.
257
+ - [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
258
+ - [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
259
+ - [ ] **Process Improvements:** `Universal` and `Project` are both filled.
260
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
261
+ - [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
262
+ - [ ] **Gate 3 — Verified:** every item above holds.
245
263
 
246
264
  <!-- bkit:end -->
247
265