@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,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,19 +11,20 @@
11
11
  >
12
12
  > **Rules:**
13
13
  >
14
- > - NEVER commit, push, or start a metered native build to produce shots. Use an artifact that already exists.
15
- > - Seeded-defect copies stay in scratch. never write them into the app, the manifest under test, or this report as product shots.
16
- > - 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.
17
18
 
18
19
  ## Universal Instructions
19
20
 
20
21
  ### Context & Goals
21
22
 
22
- 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.
23
24
 
24
- **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".
25
26
 
26
- **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`.
27
28
 
28
29
  **Anchor Standards:**
29
30
 
@@ -31,102 +32,139 @@ Automated checks never look at a screen. They pass when a title is centred on on
31
32
  - NN/g severity ratings: frequency, impact, and persistence.
32
33
  - ISO 9241-11:2018 (effectiveness, efficiency, and satisfaction).
33
34
  - ISO 9241-110:2020 (interaction principles).
34
- - Platform interface guidelines (e.g. Apple Human Interface Guidelines, Material Design 3). Living documents; record the date read.
35
- - Human-AI interaction guidelines (e.g. Microsoft HAX, 18 guidelines; Google PAIR Guidebook).
36
- - 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.
37
38
 
38
39
  ### Scope
39
40
 
40
- - Rendered screens beside their drawings and beside the same screen on other platforms.
41
- - Routes and states the capture did not reach.
42
- - A new user's first journey, per platform.
43
- - Heuristics on the primary flows, including when the drawing itself is the defect.
44
- - Copy, locale format, findability, platform conventions, notifications, poor network, and device switching.
45
- - Errors, forms, and destructive actions.
46
- - AI features the user must see, correct, and undo.
47
- - 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.
48
49
 
49
50
  ### Out of Scope
50
51
 
51
52
  <!-- prettier-ignore -->
52
53
  | Excluded item | Why | Where it belongs |
53
54
  | --- | --- | --- |
54
- | Contrast, target size, focus, labels | Same screens, different sweep | `bkit-audit-accessibility` |
55
- | A value or control implemented twice | Duplication sweep | `bkit-audit-duplication` |
56
- | Funnel or feedback instrumentation | Analytics sweep | `bkit-audit-analytics` |
57
- | Store listing declarations | Store sweep | `bkit-audit-app-store` |
58
- | Model output, when the screen already shows, corrects, and undoes it | Model sweep | `bkit-audit-llm` |
59
- | Price, renewal, or cancel wording vs consumer law | Privacy sweep | `bkit-audit-privacy` |
60
- | Capture pipeline (bad crop, unpaired row, missing cell, canary miss) | Pipeline, not the screen | Plan from this report |
61
- | 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 |
62
63
 
63
64
  ### Pre-Flight / Dependencies
64
65
 
65
66
  #### Core
66
67
 
67
- - [ ] **Permissions:** blocked calls recorded
68
- - [ ] **Screens:** Steps 2, 7-14 — open product (local or existing preview). Fallback: drawings and source only; live claims = hypotheses.
69
- - [ ] **Drawings:** Steps 5, 7, 9 — reference drawings readable. Fallback: live vs live only; drawing comparison `Not Checked`.
70
- - [ ] **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.
71
72
 
72
73
  #### Conditional
73
74
 
74
- - [ ] **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.
75
- - [ ] **Vision:** Image review → Steps 5-6 — agent opens every PNG. Fallback: hand comparison; record images not opened.
76
- - [ ] **Phone Runtimes:** Phone apps ship → Step 8 — simulator, emulator, or device. Fallback: web only; phone `Not Checked`.
77
- - [ ] **Locale Catalogue:** More than one locale, or a pseudo-locale → Step 8. Fallback: source-language copy only.
78
- - [ ] **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`.
79
80
 
80
81
  ### 🔒 Gate 1: Prerequisites Check
81
82
 
82
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
83
- - [ ] **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.
84
85
 
85
86
  ### Probe Steps
86
87
 
87
- - [ ] **Step 1 — Previous Run:** **Done when:** closure rate in `Previous Run`, or run marked baseline.
88
- - [ ] **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`.
89
- - [ ] **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.
90
- - [ ] **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.
91
- - [ ] **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 x state x size x 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`.
92
- - [ ] **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`.
93
- - [ ] **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.
94
- - [ ] **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.
95
- - [ ] **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.
96
- - [ ] **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.
97
- - [ ] **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.
98
- - [ ] **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.
99
- - [ ] **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.
100
- - [ ] **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.
101
- - [ ] **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.
102
- - [ ] **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`.
103
140
 
104
141
  ### 🔒 Gate 2: Probes Check
105
142
 
106
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
107
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
108
- - [ ] **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.
109
147
  - [ ] **Pipeline ruled out:** no finding is OS chrome, the region below a cut drawing, or a blocked native cell.
110
- - [ ] **Gate 2 — Verified:** Every checkbox above independently verified and checked off.
148
+ - [ ] **Gate 2 — Verified:** every item above holds.
111
149
 
112
150
  ## Findings
113
151
 
114
152
  <!-- prettier-ignore -->
115
153
  | Severity | Use |
116
154
  | --- | --- |
117
- | `CRITICAL` | Broken primary flow with no workaround; typed input or a record lost with no recovery; destructive action with no undo that loses data |
118
- | `HIGH` | User cannot finish a task, and a workaround exists; empty first screen with no next step; destructive confirmation missing on one platform |
119
- | `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 |
120
- | `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 |
121
159
 
122
- 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`.
123
161
 
124
162
  <!-- prettier-ignore -->
125
163
  | ID | Severity | Location | Evidence | Expected |
126
164
  | --- | --- | --- | --- | --- |
127
165
  | PENDING | PENDING | PENDING | PENDING | PENDING |
128
166
 
129
- Empty and clean → one row `None`.
167
+ **If** the run finds nothing → write one row: `None`.
130
168
 
131
169
  ## Report
132
170
 
@@ -211,13 +249,17 @@ PENDING
211
249
 
212
250
  ### 🔒 Gate 3: Report Check
213
251
 
214
- - [ ] **No placeholders:** no `PENDING` left
215
- - [ ] **Summary:** names count per severity, cells captured vs blocked per platform, and the canary hit rate.
216
- - [ ] **Series:** every series beside previous report's numbers, or marked baseline.
217
- - [ ] **Writes:** only this report, template `Project Instructions`, and ledger rows changed; throwaway worktrees / remote targets removed.
218
- - [ ] **Process Improvements:** `Universal` and `Project` filled
219
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
220
- - [ ] **Gate 3 — Verified:** Every checkbox above independently verified and checked off.
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.
221
263
 
222
264
  <!-- bkit:end -->
223
265