@cbartens/bkit 0.0.0-stage → 5.0.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 (373) hide show
  1. package/.bkit/README.md +421 -0
  2. package/.bkit/core/.agents/context.md +95 -0
  3. package/.bkit/core/.agents/docs.md +62 -0
  4. package/.bkit/core/.agents/rules.md +147 -0
  5. package/.bkit/core/.agents/skills.md +43 -0
  6. package/.bkit/core/.bkit/LICENSE.md +151 -0
  7. package/.bkit/core/.bkit/README.md +421 -0
  8. package/.bkit/core/.bkit/cloud.md +502 -0
  9. package/.bkit/core/.bkit/comparison.md +318 -0
  10. package/.bkit/core/.bkit/install.md +496 -0
  11. package/.bkit/core/.bkit/jsonl.md +497 -0
  12. package/.bkit/core/.bkit/prompts.md +474 -0
  13. package/.bkit/core/.bkit/providers.md +598 -0
  14. package/.bkit/core/.bkit/templates.md +471 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1546 -0
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
  22. package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
  24. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
  26. package/.bkit/core/AGENTS.md +77 -0
  27. package/.bkit/core/LICENSE.md +149 -0
  28. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
  29. package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
  30. package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
  31. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
  32. package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
  33. package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
  34. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
  35. package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
  36. package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
  37. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
  38. package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
  39. package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
  40. package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
  41. package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
  42. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
  43. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
  44. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
  45. package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
  46. package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
  47. package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
  48. package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
  49. package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
  50. package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
  51. package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
  52. package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
  53. package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
  54. package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
  55. package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
  56. package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
  57. package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
  58. package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
  59. package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
  60. package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
  61. package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
  62. package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
  63. package/.bkit/core/docs/templates/bkit-plan.md +476 -0
  64. package/.bkit/core/engine/checks/after/auth.ts +247 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +739 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +556 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  70. package/.bkit/core/engine/checks/after/vercel.ts +101 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +201 -0
  73. package/.bkit/core/engine/checks/before/files.ts +202 -0
  74. package/.bkit/core/engine/checks/before/index.ts +206 -0
  75. package/.bkit/core/engine/checks/before/mcp.ts +127 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +77 -0
  77. package/.bkit/core/engine/checks/before/version.ts +67 -0
  78. package/.bkit/core/engine/checks/status-holes.ts +479 -0
  79. package/.bkit/core/engine/cli.ts +871 -0
  80. package/.bkit/core/engine/commands/analysis.ts +550 -0
  81. package/.bkit/core/engine/commands/ci/ci.ts +483 -0
  82. package/.bkit/core/engine/commands/comply.ts +415 -0
  83. package/.bkit/core/engine/commands/harvest.ts +459 -0
  84. package/.bkit/core/engine/commands/install/check.ts +70 -0
  85. package/.bkit/core/engine/commands/install/doctor.ts +247 -0
  86. package/.bkit/core/engine/commands/install/install.ts +528 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +972 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1026 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +494 -0
  91. package/.bkit/core/engine/commands/registry.ts +53 -0
  92. package/.bkit/core/engine/commands/setup/setup.ts +184 -0
  93. package/.bkit/core/engine/commands/telemetry.ts +32 -0
  94. package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
  95. package/.bkit/core/engine/commands/workflow/context.ts +961 -0
  96. package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
  97. package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
  98. package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
  99. package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
  100. package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
  101. package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
  102. package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
  103. package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
  104. package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
  105. package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
  106. package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
  107. package/.bkit/core/engine/commands/workflow/status.ts +455 -0
  108. package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
  109. package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
  110. package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
  111. package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
  112. package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
  113. package/.bkit/core/engine/install/cloud-env.ts +925 -0
  114. package/.bkit/core/engine/install/managed-block.ts +212 -0
  115. package/.bkit/core/engine/install/manifest.ts +448 -0
  116. package/.bkit/core/engine/install/modules/claude.ts +362 -0
  117. package/.bkit/core/engine/install/modules/cloud.ts +174 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +600 -0
  120. package/.bkit/core/engine/install/modules/cursor.ts +231 -0
  121. package/.bkit/core/engine/install/modules/index.ts +242 -0
  122. package/.bkit/core/engine/install/modules/opencode.ts +573 -0
  123. package/.bkit/core/engine/install/placeholders.ts +108 -0
  124. package/.bkit/core/engine/install/template-copies.ts +119 -0
  125. package/.bkit/core/engine/install/version-file.ts +284 -0
  126. package/.bkit/core/engine/install/write.ts +467 -0
  127. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  128. package/.bkit/core/engine/ledgers/status.ts +213 -0
  129. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  130. package/.bkit/core/engine/render/hosts.ts +372 -0
  131. package/.bkit/core/engine/render/models.ts +323 -0
  132. package/.bkit/core/engine/render/parts.ts +38 -0
  133. package/.bkit/core/engine/render/trackers.ts +170 -0
  134. package/.bkit/core/engine/shared/egress.ts +345 -0
  135. package/.bkit/core/engine/shared/json.ts +16 -0
  136. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  137. package/.bkit/core/engine/shared/package-json.ts +29 -0
  138. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  139. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  140. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  141. package/.bkit/core/engine/shared/settings.ts +72 -0
  142. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  143. package/.bkit/core/engine/tools/wording.ts +748 -0
  144. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  145. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  146. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  147. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  148. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  149. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  150. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  155. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  156. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  157. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  158. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  159. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  160. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  161. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  162. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  165. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  166. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  169. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  170. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  171. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  172. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  173. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  174. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  175. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  176. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  178. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  179. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  180. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  181. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  182. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  185. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  186. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  187. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  188. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  189. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  190. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  191. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  192. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  193. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  194. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  195. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  196. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  197. package/.bkit/core/workflows/bkit-auto.md +121 -0
  198. package/.bkit/core/workflows/bkit-build.md +802 -0
  199. package/.bkit/core/workflows/bkit-debug.md +642 -0
  200. package/.bkit/core/workflows/bkit-design.md +495 -0
  201. package/.bkit/core/workflows/bkit-plan.md +510 -0
  202. package/.bkit/core/workflows/bkit-ship.md +650 -0
  203. package/.bkit/shared/.bkit/.env.example +108 -0
  204. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  205. package/.bkit/shared/.claude/settings.json +88 -0
  206. package/.bkit/shared/.codex/hooks.json +26 -0
  207. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  208. package/.bkit/shared/.cursor/hooks.json +26 -0
  209. package/.bkit/shared/.cursor/mcp.json +15 -0
  210. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  211. package/.bkit/shared/.gitattributes +37 -0
  212. package/.bkit/shared/.mcp.json +16 -0
  213. package/.bkit/shared/.opencode/opencode.json +62 -0
  214. package/.bkit/shared/CLAUDE.md +11 -0
  215. package/.bkit/shared/LICENSE.md +22 -0
  216. package/.bkit/shared/docs/architecture.md +19 -0
  217. package/.bkit/shared/docs/data-schema.md +19 -0
  218. package/.bkit/shared/docs/deployments.md +438 -0
  219. package/.bkit/shared/docs/design.md +39 -0
  220. package/.bkit/shared/docs/noise.md +19 -0
  221. package/.bkit/shared/docs/observability.md +25 -0
  222. package/.bkit/shared/docs/security.md +42 -0
  223. package/.bkit/shared/docs/setup.md +30 -0
  224. package/.bkit/shared/docs/technology.md +18 -0
  225. package/.bkit/shared/docs/testing.md +413 -0
  226. package/.bkit/shared/gitignore +92 -0
  227. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +192 -0
  228. package/.bkit/templates/.cursor/Dockerfile +68 -0
  229. package/.bkit/templates/.cursor/environment.json +6 -0
  230. package/.bkit/templates/.cursor/settings.json +11 -0
  231. package/.bkit/templates/.envrc +7 -0
  232. package/.bkit/templates/.github/dependabot.yml +52 -0
  233. package/.bkit/templates/.github/renovate.json5 +239 -0
  234. package/.bkit/templates/.github/workflows/bkit-ci.yml +1082 -0
  235. package/.bkit/templates/.github/workflows/bkit-cloud.yml +566 -0
  236. package/.bkit/templates/.github/workflows/bkit-renovate.yml +107 -0
  237. package/.bkit/templates/.graphifyignore +108 -0
  238. package/.bkit/templates/.husky/pre-commit +16 -0
  239. package/.bkit/templates/.husky/pre-push +91 -0
  240. package/.bkit/templates/.lintstagedrc.json +3 -0
  241. package/.bkit/templates/.prettierignore +41 -0
  242. package/.bkit/templates/.serena/project.yml +243 -0
  243. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  244. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  245. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  246. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  247. package/.bkit/templates/.vale.ini +67 -0
  248. package/.bkit/templates/LICENSE.md +22 -0
  249. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  250. package/.bkit/templates/context/bkit-expo.md +186 -0
  251. package/.bkit/templates/context/bkit-github.md +79 -0
  252. package/.bkit/templates/context/bkit-inngest.md +45 -0
  253. package/.bkit/templates/context/bkit-maestro.md +76 -0
  254. package/.bkit/templates/context/bkit-playwright.md +62 -0
  255. package/.bkit/templates/context/bkit-resend.md +36 -0
  256. package/.bkit/templates/context/bkit-sentry.md +65 -0
  257. package/.bkit/templates/context/bkit-serena.md +33 -0
  258. package/.bkit/templates/context/bkit-stripe.md +36 -0
  259. package/.bkit/templates/context/bkit-supabase.md +59 -0
  260. package/.bkit/templates/context/bkit-tavily.md +49 -0
  261. package/.bkit/templates/context/bkit-vercel.md +64 -0
  262. package/.bkit/templates/docs/capabilities.md +72 -0
  263. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  264. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  266. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  268. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  280. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  281. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  282. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  283. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  284. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  286. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  288. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  289. package/.bkit/templates/slop-scan.config.json +120 -0
  290. package/CHANGELOG.md +1486 -0
  291. package/LICENSE.md +161 -0
  292. package/README.md +185 -2
  293. package/dist/checks/after/auth.js +232 -0
  294. package/dist/checks/after/ci-yml.js +718 -0
  295. package/dist/checks/after/github.js +400 -0
  296. package/dist/checks/after/index.js +447 -0
  297. package/dist/checks/after/managed.js +187 -0
  298. package/dist/checks/after/tools.js +351 -0
  299. package/dist/checks/after/vercel.js +102 -0
  300. package/dist/checks/before/context-fetch.js +426 -0
  301. package/dist/checks/before/env.js +173 -0
  302. package/dist/checks/before/files.js +185 -0
  303. package/dist/checks/before/index.js +162 -0
  304. package/dist/checks/before/mcp.js +111 -0
  305. package/dist/checks/before/repo.js +71 -0
  306. package/dist/checks/before/version.js +60 -0
  307. package/dist/checks/status-holes.js +393 -0
  308. package/dist/cli.js +692 -0
  309. package/dist/commands/analysis.js +325 -0
  310. package/dist/commands/ci/ci.js +438 -0
  311. package/dist/commands/comply.js +310 -0
  312. package/dist/commands/harvest.js +354 -0
  313. package/dist/commands/install/check.js +61 -0
  314. package/dist/commands/install/doctor.js +207 -0
  315. package/dist/commands/install/install.js +461 -0
  316. package/dist/commands/install/uninstall.js +815 -0
  317. package/dist/commands/install/upgrade.js +771 -0
  318. package/dist/commands/launch.js +118 -0
  319. package/dist/commands/lib.js +362 -0
  320. package/dist/commands/registry.js +50 -0
  321. package/dist/commands/setup/setup.js +158 -0
  322. package/dist/commands/telemetry.js +29 -0
  323. package/dist/commands/workflow/branches.js +1265 -0
  324. package/dist/commands/workflow/context.js +846 -0
  325. package/dist/commands/workflow/counters.js +227 -0
  326. package/dist/commands/workflow/fids.js +224 -0
  327. package/dist/commands/workflow/issues.js +585 -0
  328. package/dist/commands/workflow/ledgers.js +472 -0
  329. package/dist/commands/workflow/locks.js +364 -0
  330. package/dist/commands/workflow/prs.js +904 -0
  331. package/dist/commands/workflow/repo.js +199 -0
  332. package/dist/commands/workflow/roadmap.js +495 -0
  333. package/dist/commands/workflow/runs.js +1717 -0
  334. package/dist/commands/workflow/runtime.js +257 -0
  335. package/dist/commands/workflow/skills.js +110 -0
  336. package/dist/commands/workflow/status.js +392 -0
  337. package/dist/commands/workflow/steps.js +1093 -0
  338. package/dist/commands/workflow/tests.js +144 -0
  339. package/dist/commands/workflow/workflows.js +1342 -0
  340. package/dist/commands/workflow/workstreams.js +141 -0
  341. package/dist/commands/workflow/worktrees.js +473 -0
  342. package/dist/install/cloud-env.js +819 -0
  343. package/dist/install/managed-block.js +182 -0
  344. package/dist/install/manifest.js +376 -0
  345. package/dist/install/modules/claude.js +288 -0
  346. package/dist/install/modules/cloud.js +152 -0
  347. package/dist/install/modules/codex.js +193 -0
  348. package/dist/install/modules/core.js +511 -0
  349. package/dist/install/modules/cursor.js +186 -0
  350. package/dist/install/modules/index.js +152 -0
  351. package/dist/install/modules/opencode.js +504 -0
  352. package/dist/install/placeholders.js +87 -0
  353. package/dist/install/template-copies.js +106 -0
  354. package/dist/install/version-file.js +204 -0
  355. package/dist/install/write.js +342 -0
  356. package/dist/ledgers/clamp-log.js +27 -0
  357. package/dist/ledgers/status.js +156 -0
  358. package/dist/ledgers/telemetry.js +637 -0
  359. package/dist/render/hosts.js +339 -0
  360. package/dist/render/models.js +288 -0
  361. package/dist/render/parts.js +33 -0
  362. package/dist/render/trackers.js +135 -0
  363. package/dist/shared/egress.js +299 -0
  364. package/dist/shared/json.js +16 -0
  365. package/dist/shared/log-prefix.js +7 -0
  366. package/dist/shared/package-json.js +22 -0
  367. package/dist/shared/package-manager.js +32 -0
  368. package/dist/shared/package-roots.js +145 -0
  369. package/dist/shared/protected-paths.js +153 -0
  370. package/dist/shared/settings.js +44 -0
  371. package/dist/shared/timeouts.js +19 -0
  372. package/dist/tools/wording.js +680 -0
  373. package/package.json +101 -4
@@ -0,0 +1,259 @@
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. `@bkit-audit-generate` fills this template. -->
2
+
3
+ <!-- bkit:start -->
4
+
5
+ {{BKIT_MANAGED_MARKER}}
6
+
7
+ # Failures Triage
8
+
9
+ > [!CAUTION]
10
+ > **Purpose:** Verdict on every open failure — reachable, already fixed, mis-framed, unconfirmed, or a repeat of a known defect.
11
+ >
12
+ > **Rules:**
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 evidence (`file:line`, or command / query and its output) and tool behind it.
21
+ > - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
22
+ > - NEVER append or edit a ledger line. Close, regression, triage, and knowledge rows live in `Expected` only. `ts` is minted at append (`.bkit/jsonl.md` § Write Idiom), never written in this report.
23
+ > - A security row (`category: "security"`, or an auth, secrets, or data-exposure hole) carries key, verdict, and severity only. `file:line` stays in the ledger row. A public repo uses a draft repository security advisory, not this report.
24
+
25
+ ## Universal Instructions
26
+
27
+ ### Context & Goals
28
+
29
+ `docs/failures.jsonl` logs discovered bugs (`.bkit/jsonl.md` § Ledgers & Writers). Rows append at discovery; never re-validated. Four drifts:
30
+
31
+ - Silently fixed — bug fixed, row not `CLOSED`
32
+ - Mis-framed — not reachable, or path moved
33
+ - Understated — one instance of a systemic defect
34
+ - Untracked — reachable, no issue carries it
35
+
36
+ Row text that says found by reading and must be confirmed later = hypothesis, not established bug. Nothing forces confirmation. Target failure: **an open row for a bug the code has already fixed, or a live bug the row understates or never confirmed.**
37
+
38
+ **Applies when:** `docs/failures.jsonl` exists, or agents append `kind: "failure"`. None → one `N/A` row with evidence, never "clean".
39
+
40
+ **Cadence:** once per ship cycle, and at least monthly when no cycle ships. Extra pass when new `CRITICAL` row lands (age target 7 days), or after incident on production or preview.
41
+
42
+ **Anchor Standards:** record version and date read. Newer version → `Standards` step reads what changed.
43
+
44
+ - Problem management and the known-error database (e.g. ITIL 4; record the edition). The deferred and known-error review it describes (e.g. ITIL-aligned known-error monitoring).
45
+ - Postmortem action items (e.g. Google SRE Workbook, Postmortem Culture).
46
+ - Bug triage and resolution states, including an incomplete state for an unanswered reproduction request (e.g. Mozilla defect severity guide, Bugzilla triage).
47
+ - Age targets, set by this procedure: 7 days for `CRITICAL`, 30 days for `HIGH`, from the row's first `ts`. No published standard.
48
+
49
+ ### Scope
50
+
51
+ - Fold `docs/failures.jsonl` last-row-wins. Open = winning `status != "CLOSED"`.
52
+ - Age against target. Whether CI gate on open `CRITICAL` failures is installed, and whether it reads this ledger.
53
+ - Verify every open row against source, including hypotheses, mis-framing, and understatement.
54
+ - Incident follow-ups, and whether each incident has a postmortem with a preventing action.
55
+ - Recurrences and regressions.
56
+ - Known-error workaround on record. Root-cause classes, and the top class as a gate candidate.
57
+ - Security rows routed without exploit detail.
58
+
59
+ ### Out of Scope
60
+
61
+ <!-- prettier-ignore -->
62
+ | Excluded item | Why | Where it belongs |
63
+ | --- | --- | --- |
64
+ | Deliberate deferred work | Deferral register | `bkit-audit-deferrals` |
65
+ | Exploit reproduction; auth and exposure as an attack sweep | Security sweep reads the ledger row | `bkit-audit-security` |
66
+ | Flake diagnosis in depth | Flake sweep | `bkit-audit-flakes` |
67
+ | Log volume, alert rules, drain coverage | Log sweep | `bkit-audit-logs` |
68
+ | Closing rows the code already finished; locator fixes; `TRIAGED` when an issue already exists | Ledger writes. For `category: "testing"`, the utility closes only on a landed deterministic fix, never a recent green run | `@bkit-utility-update-failures` |
69
+ | Opening issues; writing the failing test or the postmortem | Audit reports only | Plan from this report |
70
+
71
+ ### Verdicts
72
+
73
+ One per verified row.
74
+
75
+ - **CONFIRMED:** real and reachable. Reproduced, or path read end to end with cited `file:line` (citation out of report when row is security). Record reach: flow, roles that hit it, live event counts when error tracker available. No issue → `Expected` names issue to open. Bug not reproducible is not fixed from row alone. Failing test = next step in `Expected`, not written here.
76
+ - **FIXED:** already resolved. `Expected` = `CLOSED` same-`key` row, with `references` that closed it, and test that would fail if bug returned. Fix with no such test is not FIXED: `Expected` = `TRIAGED` row whose follow-up is missing test.
77
+ - **MIS-FRAMED:** row wrong. Bug not reachable, component/path moved, or one instance of systemic defect. `Expected` = corrected row, or `CLOSED` row with close reason.
78
+ - **TRACKED:** real; open issue covers it. `Expected` = issue to point row at.
79
+ - **UNCONFIRMED:** hypothesis; not yet reproduced or read end to end. `Expected` = probe or failing test to settle it. Still unsettled on third run → `CLOSED` as not reproducible, and say so.
80
+ - **DUPLICATE:** same defect as another row under different `key`. `Expected` = canonical key, and `CLOSED` row for this one.
81
+ - **OTHER:** fits none. Say what it is, why, and where it goes. Same `OTHER` on 2 runs → propose new verdict in `Process Improvements`.
82
+
83
+ **FIXED and MIS-FRAMED are the verdicts most likely to hide a live bug.** Language server under-reporting biases that way. Either verdict needs positive reason — fix commit, deleted file, or changed guard. Empty query is not absence. Error-tracker events on matching issue after fix commit → bug not fixed.
84
+
85
+ Row text awaiting confirmation = UNCONFIRMED until reproduced or read end to end.
86
+
87
+ ### Pre-Flight / Dependencies
88
+
89
+ **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.
90
+
91
+ #### Core
92
+
93
+ Always verify.
94
+
95
+ - [ ] **Ledger:** Steps 3–7 — `docs/failures.jsonl` and `.bkit/jsonl.md`. Fallback: file absent → one `N/A` row after Step 3 and STOP.
96
+ - [ ] **Git History:** Steps 2, 5 — commits since the previous report, fix commits. Fallback: closures and regression-by-commit `Not Checked`.
97
+ - [ ] **Web:** Step 8 — fetch anchor standards. Fallback: versions recorded as unread.
98
+
99
+ #### Conditional
100
+
101
+ Verify only when applicable.
102
+
103
+ - [ ] **Language Server:** Typed language → Step 4 — symbol at current path, caller chain, diagnostics for one file without full typecheck, e.g. Serena, `tsserver`. Fallback: text search. Reach and close needing callers stay hypotheses until corroborated.
104
+ - [ ] **Error Tracker:** Production or preview events exist → Steps 4, 5 — event counts and flows after fix commit, e.g. Sentry, platform logs. Fallback: code only. Event counts `Not Checked`.
105
+ - [ ] **Tracker:** Issues wired → Steps 4, 7 — issue carrying bug, postmortem tracking issue. Fallback: issue pointers `Not Checked`.
106
+ - [ ] **CI Config:** Workflow can fail build → Step 3 — gate on open `CRITICAL` failures. Fallback: gate check `Not Checked`.
107
+
108
+ ### 🔒 Gate 1: Prerequisites Check
109
+
110
+ **Checkpoint.** Verify and check `[x]` all applicable boxes above, then continue to `Probe Steps` without asking.
111
+
112
+ - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
113
+ - [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
114
+
115
+ ### Probe Steps
116
+
117
+ - [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. 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.
118
+ - [ ] **Step 2 — Closures:** Re-verify every FIXED and MIS-FRAMED row from previous report at `HEAD`. Each no longer holding = finding, with what changed. **Done when:** `Closures` holds every row, each failure, and failure rate, or run marked baseline.
119
+ - [ ] **Step 3 — Fold:** Last-row-wins per `key`, not per line. Append-only file (`.gitattributes` `merge=union`); editing a line keeps stale copy beside replacement. Highest numeric `ts` wins (`.bkit/jsonl.md` § Updating a Row). `key` whose `ts` is not a number → last line in file is latest. Open = every winning row with `status != "CLOSED"`, including `TRIAGED` (diagnosed is not fixed), `RESOLVED`, `FIXED`, `SUPERSEDED`, and rows with no `status`. Word that looks finished is not done. `RESOLVED` or `FIXED` row really done → `CLOSED` row in `Expected`, with `references` that closed it. Not skipped because word looks finished. Order: `CRITICAL`, then `HIGH`, then oldest `ts`. Compare `severity` case-insensitively. No `severity` → assign with verdict. Age from row's first `ts`: list every `CRITICAL` older than 7 days and every `HIGH` older than 30 days. Where CI check goes red while any `CRITICAL` row has `status != "CLOSED"`, report whether installed. Green check beside such row = finding (gate not reading ledger). Absent → record in `Checked`. Large open set may be partial pass → record rows verified / rows open. Winning future `ts` that would outrank close → name `key`. No later `ts` invented. **Done when:** `Trend` holds open counts, age-target breaches, gate result, and verified / open, or `N/A` and STOP.
120
+ - [ ] **Step 4 — Source:** No verdict before this step. Under-reporting biases toward closing live bug.
121
+
122
+ <!-- prettier-ignore -->
123
+ | Row claims | Check with |
124
+ | --- | --- |
125
+ | "`X` in `path` is broken" and the path looks stale | Language server, symbol lookup, at its current path. Settles MIS-FRAMED without a manual hunt |
126
+ | "Reachable from the API" or from a caller | Language server, references. A caller chain, not an assumption. No callers is a hint, not proof |
127
+ | "One instance of a systemic defect" | Text search for the literal signature, repo-wide. An understated row is a pattern question |
128
+ | A type or interop failure in one file | Language-server diagnostics for that file, not a full typecheck |
129
+ | A ledger, migration, workflow, SQL, config, or string literal | Text search. A language server reads one language |
130
+ | FIXED, or the reach of CONFIRMED | Error tracker and platform logs. Events after the fix commit mean not fixed. Counts and flows are the reach |
131
+
132
+ Pace reference queries. Re-run empty or surprisingly low result before close verdict. Partial answer indistinguishable from real one. Empty inconclusive, not absence. Packages/files outside project graph, mock-factory keys invisible → text search.
133
+
134
+ Incident rows (seen on production or preview, not in review) need follow-ups checked. Remediation usually names more than code fix: regression test, monitor, alert, doc change. Check each landed. Fix landed, test or monitor did not → not FIXED. `Expected` names each missing follow-up and issue to open.
135
+
136
+ Each incident: written postmortem; ≥1 action preventing or detecting repeat, with owner and tracking issue at top priority. User-affecting outage needs ≥1 top-priority bug. Missing postmortem, or postmortem with only mitigation items = finding. `Expected` = issue to open. **Done when:** every row verified this pass has evidence and tool on finding. `Incidents` lists follow-ups and postmortem gaps, or `none`. Unverified rows stay counted in `Trend`; not passed.
137
+
138
+ - [ ] **Step 5 — Recurrences:** Same-`key` append recording defect seen again = recurrence (`.bkit/jsonl.md` § Updating a Row). Omit appends that only change `status`. For `category: "testing"`, flake count = `key`'s row count under that rule. Rank open rows by count. Then regressions: each row `CLOSED` since previous report → look for later row same `key`, new row same defect under another `key`, or error-tracker events on matching issue after close. Each → `Expected` = `OPEN` row to append. **Done when:** `Recurrences` ranks open rows and lists regressions, or `none`.
139
+ - [ ] **Step 6 — Classes:** (a) Known errors carry workaround. For every `TRIAGED` or CONFIRMED row agents keep hitting (≥2 recurrences in Step 5, or parked row whose blocker not in winning row), check `docs/knowledge.jsonl` has `ACTIVE` row with workaround. Missing → finding. `Expected` = knowledge row to append. (b) Count open and recently closed rows by `category`, package, root-cause class. Top recurring class this run = gate candidate → name for `bkit-audit-gates`. **Done when:** `Classes` holds workaround gaps, counts, gate candidate, or `none`.
140
+ - [ ] **Step 7 — Classify:** Every row, as Step 4 left it, gets one verdict. This run does not append or open issues. Security row → `bkit-audit-security`: key, verdict, severity only in this report. Flaky test diagnosis → `bkit-audit-flakes`. Older flake diagnoses may sit on tracker issues predating that audit. Search those too.
141
+
142
+ <!-- prettier-ignore -->
143
+ | Finding | Expected |
144
+ | --- | --- |
145
+ | CONFIRMED | The issue to open if none carries it. The failing test is the next step |
146
+ | FIXED | The `CLOSED` row, with the `references` that closed it, and the regression test |
147
+ | Fix with no regression test, or an incident follow-up that did not land | The `TRIAGED` row, and the issue to open for each missing follow-up |
148
+ | Missing postmortem, or one with only mitigation items | The issue to open |
149
+ | MIS-FRAMED | The corrected row, or the `CLOSED` row with the close reason |
150
+ | TRACKED | The issue to point the row at |
151
+ | UNCONFIRMED | The probe or failing test. On its third run, the `CLOSED` row as not reproducible |
152
+ | DUPLICATE | The canonical key, and the `CLOSED` row for this one |
153
+ | Regression | The `OPEN` row to append |
154
+ | Known error with no workaround on record | The `docs/knowledge.jsonl` row to append |
155
+ | Top recurring root-cause class | Named for `bkit-audit-gates`, as a gate candidate |
156
+ | Security row | `bkit-audit-security`. Key, verdict, and severity only |
157
+ | Flaky test's diagnosis | `bkit-audit-flakes` |
158
+ | OTHER | Where it goes |
159
+
160
+ **Done when:** every verified row has one verdict. Security rows in Findings carry no `file:line` and no exploit detail.
161
+
162
+ - [ ] **Step 8 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per practice (known-error records, proactive problem review, postmortem action items, triage resolution states, age targets) → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
163
+ - [ ] **Step 9 — Anything Else:** (a) Everything changed since previous report's commit touching failures (schema and writers in `.bkit/jsonl.md`, steps and agents that append rows, CI gate on open `CRITICAL` failures, flake register `bkit-audit-flakes`, error-tracker projects and alert rules) → one-line verdict each. (b) Bounded ~30 min pass: what senior problem manager flags that no step asks; read since previous run (incidents, `bkit-audit-logs` sweeps, vendor status incidents) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
164
+
165
+ ### 🔒 Gate 2: Probes Check
166
+
167
+ **Checkpoint.** Verify and check `[x]` all boxes below, then continue to `Findings` without asking.
168
+
169
+ - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
170
+ - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
171
+ - [ ] **Read-only:** no ledger line, code, or config changed. Every close, regression, and knowledge row is `Expected` only.
172
+ - [ ] **Security:** security rows carry key, verdict, and severity only. No exploit detail, no `file:line`.
173
+ - [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off.
174
+
175
+ ## Findings
176
+
177
+ <!-- prettier-ignore -->
178
+ | Severity | Use |
179
+ | --- | --- |
180
+ | `CRITICAL` | Data loss, a security hole, or a broken workflow with no workaround. Still open, including a row whose word looks finished |
181
+ | `HIGH` | Real damage or a blocked path, with a workaround. Fix landed and no regression test. Incident whose test or monitor did not land. User-affecting outage with no preventing action |
182
+ | `MEDIUM` | Mis-framed or understated. Recurrence or regression. Known error with no workaround on record. Age target breached. Hypothesis still open |
183
+ | `LOW` | Duplicate key. Path drift that does not change reach. Missing `severity` |
184
+
185
+ Scale per `.bkit/jsonl.md` § Severity. Within a severity: oldest `ts` first. Finding keeps severity when it becomes ledger row or issue. Row's bucket = ledger severity, or verdict assigns.
186
+
187
+ <!-- prettier-ignore -->
188
+ | ID | Severity | Verdict | Location | Evidence | Expected |
189
+ | --- | --- | --- | --- | --- | --- |
190
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
191
+
192
+ Empty and clean → one row `None`.
193
+
194
+ ## Report
195
+
196
+ ### Summary
197
+
198
+ PENDING
199
+
200
+ ### Previous Run
201
+
202
+ PENDING
203
+
204
+ ### Closures
205
+
206
+ PENDING
207
+
208
+ ### Trend
209
+
210
+ PENDING
211
+
212
+ ### Incidents
213
+
214
+ PENDING
215
+
216
+ ### Recurrences
217
+
218
+ PENDING
219
+
220
+ ### Classes
221
+
222
+ PENDING
223
+
224
+ ### Checked
225
+
226
+ PENDING
227
+
228
+ ### Not Checked
229
+
230
+ PENDING
231
+
232
+ ### Standards Coverage
233
+
234
+ PENDING
235
+
236
+ ### Beyond the Steps
237
+
238
+ PENDING
239
+
240
+ ### Process Improvements
241
+
242
+ PENDING
243
+
244
+ ### 🔒 Gate 3: Report Check
245
+
246
+ **Checkpoint.** Verify and check `[x]` all boxes below, then stop.
247
+
248
+ - [ ] **No placeholders:** Findings table and every `Report` section have no `PENDING`.
249
+ - [ ] **Summary:** names count per severity, age-target breach count, and rows verified / rows open.
250
+ - [ ] **Series:** open count and the recurrence ranking beside previous report's numbers, or marked baseline.
251
+ - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
252
+ - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
253
+ - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
254
+
255
+ > `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.
256
+
257
+ <!-- bkit:end -->
258
+
259
+ ## Project Instructions
@@ -0,0 +1,237 @@
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. `@bkit-audit-generate` fills this template. -->
2
+
3
+ <!-- bkit:start -->
4
+
5
+ {{BKIT_MANAGED_MARKER}}
6
+
7
+ # Flake Triage
8
+
9
+ > [!CAUTION]
10
+ > **Purpose:** Diagnosis of tests that pass only on retry, or fail on one surface and pass on another, and the change that would remove each one.
11
+ >
12
+ > **Rules:**
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 evidence (`file:line`, or command / query and its output) and tool behind it.
21
+ > - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
22
+ > - never `.skip`, quarantine, delete an assertion, or widen a timeout to green a lane. A timeout named before the trace is read is not a verdict.
23
+ > - Repro and repeat runs use the suite's test tenant only; NEVER production tenants, payments, or mail.
24
+
25
+ ## Universal Instructions
26
+
27
+ ### Context & Goals
28
+
29
+ - Ledger row can record a flake exists; useful part = mechanism (never one line).
30
+ - Standing danger: read flake as timing → widen timeout; reported error usually consequence; timeout bump before trace read turns real bug into slow green.
31
+ - Load-scaled budget on shared dev machines: sampled once at config / worker load → stale mid-run (a load ramp starves late files); re-read per test file (vitest `vi.setConfig` in a setup file, jest `jest.setTimeout` in setup), same base + cap, factor pinned 1 on CI. Freshness fix = mechanism fix, not a widen.
32
+ - Target failure: **a skip, quarantine, or wider timeout standing in for a named mechanism.**
33
+
34
+ **Applies when:** suite runs more than once (CI or local repeat). None → one `N/A` row with evidence, never "clean".
35
+
36
+ **Cadence:** biweekly; every workflow's runs since previous report; same window as `bkit-audit-logs` (both read same CI runs). Do not quarantine; flake stays until fixed → age measured, not remembered. Extra pass (one flake or red run): pass-only-on-retry or fail one surface/pass another on integration branch; after retries/workers/timeouts/trace/shared-fixture change; after fix lands → repeat rate measurement for run count `Fix` named.
37
+
38
+ **Anchor Standards:** record version and date read. Newer version → `Standards` step reads what changed.
39
+
40
+ - Flake root-cause taxonomy (Luo et al., "An Empirical Analysis of Flaky Tests", FSE 2014).
41
+ - Google, "Flaky Tests at Google and How We Mitigate Them" (Google Testing Blog, 2016).
42
+ - Order-dependence and root-cause location (e.g. iDFlakies, Lam et al., ICST 2019; Ziftci and Cavalcanti, "De-Flake Your Tests", ICSME 2020).
43
+ - Browser-runner retries, flaky status, repeat-each, fail-on-flaky (e.g. Playwright); record the version.
44
+ - Unit-runner shuffle, seed, and retry (e.g. Vitest `sequence.shuffle` / `sequence.seed` / `retry`, pytest-randomly); record the version.
45
+
46
+ ### Scope
47
+
48
+ - Every runner-reported flake, and every test failed one run/surface and passed another, since previous report.
49
+ - Measured failure rate, log through first runner line, and trace.
50
+ - CI vs local, vendor incidents, before blaming test. Fixture sharing set from tooling, not memory.
51
+ - Timezone and date. Order dependence. Device flakes: boot, retries, animation, artifact locations.
52
+ - One mechanism, one root-cause class, one verdict, and change that would remove it.
53
+
54
+ ### Out of Scope
55
+
56
+ <!-- prettier-ignore -->
57
+ | Excluded item | Why | Where it belongs |
58
+ | --- | --- | --- |
59
+ | Whether the right behaviours are tested | Testing sweep | `bkit-audit-testing` |
60
+ | Log content beyond the flake's run | Log triage | `bkit-audit-logs` |
61
+ | CI annotation quality | Annotations sweep | `bkit-audit-annotations` |
62
+ | Vendor-incident catalogue | Dependencies sweep | `bkit-audit-dependencies` |
63
+ | Quarantine, skip, or a widened timeout | Never an outcome | — |
64
+ | Applying the named fix | Audit reports only | Plan from this report |
65
+
66
+ ### Verdicts
67
+
68
+ One per flake. Root-cause class (`Mechanism`) = evidence; these = outcomes. Quarantine, `.skip`, widened timeout never outcomes.
69
+
70
+ - **FIX NAMED** — mechanism named; report names change that would remove it, with runs that prove it (`Fix`).
71
+ - **BUG** — real defect behind flake; own issue + `docs/failures.jsonl` row.
72
+ - **INFRASTRUCTURE** — host, preview, database, or vendor incident explains it; not charged to test.
73
+ - **PARKED** — fix waits on decision; report names decision.
74
+ - **FIXED** — fix landed since previous report; repeated rate measurement ran count `Fix` named, no failure.
75
+ - **not ESTABLISHED** — no mechanism fits; say what is not established and what would establish it; stays open.
76
+ - **OTHER** — fits none; say why. Same `OTHER` on 2 runs → propose new verdict in `Process Improvements`.
77
+
78
+ ### Pre-Flight / Dependencies
79
+
80
+ **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.
81
+
82
+ #### Core
83
+
84
+ Always verify.
85
+
86
+ - [ ] **CI History:** Steps 2, 3 — workflow runs since previous report, e.g. `gh run list`, Actions API, GitLab pipelines. Fallback: local repeats only; ranked CI list `Not Checked`.
87
+ - [ ] **Repeat Runner:** Steps 4, 7, 8 — repeat with retries off, e.g. Playwright `--repeat-each`, pytest-repeat. Fallback: rate `Not Checked`; do not mark `FIX NAMED` on unmeasured flake unless mechanism deterministic and report says rate unknown.
88
+ - [ ] **Web:** Steps 6, 13 — vendor status pages and anchor standards. Fallback: incidents and versions recorded as unread.
89
+
90
+ #### Conditional
91
+
92
+ Verify only when applicable.
93
+
94
+ - [ ] **Traces:** Browser E2E → Step 5 — trace, video, screenshot of failed attempt, e.g. Playwright trace, Cypress. Fallback: log only; geometry claims `Not Checked`.
95
+ - [ ] **Language Server:** Typed language → Steps 6, 11 — which specs share fixture, e.g. Serena, `tsserver`. Fallback: text search; name it. Guessing sharing set misattributes diagnosis.
96
+ - [ ] **Vendor Status:** Failure time may overlap vendor window → Step 6 — e.g. GitHub status, hosting preview, database host. Fallback: `INFRASTRUCTURE` `Not Checked`.
97
+ - [ ] **Device Runner:** Native flake → Step 9 — e.g. Maestro, EAS, XCUITest. Fallback: native flakes `Not Checked`.
98
+
99
+ ### 🔒 Gate 1: Prerequisites Check
100
+
101
+ **Checkpoint.** Verify and check `[x]` all applicable boxes above, then continue to `Probe Steps` without asking.
102
+
103
+ - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
104
+ - [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
105
+
106
+ ### Probe Steps
107
+
108
+ - [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. 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.
109
+ - [ ] **Step 2 — List:** Before triage, list every test with runner status flaky (failed, passed on retry) and every pass-only-on-retry, across every workflow since previous report. Also list fail one run/surface, pass another: with retries off, `flaky` never appears; a noticed red run is input, not the list. Rank by flake rate (flaky or failed runs ÷ runs) and reruns caused. Per open flake: first-seen, last-seen, age. Report median age of open flakes. Red run absent from list → detection finding. Triage in rank order. **Done when:** ranked list, ages, median in `Flakes`.
110
+ - [ ] **Step 3 — Pin:** Per triaged flake: run id, commit, job that failed vs downstream-only. Control run and valid scope. Prior red run = control only when failure mode differs — auth failure redirecting every lane to sign-in is control for tenant-minting lane only. **Done when:** run, job, control in `Pin`.
111
+ - [ ] **Step 4 — Rate:** Spec with repeat-each, retries off, at CI worker count: k failures in N runs. Repeat with CPU throttled/loaded. Record N, k, workers, commit. Without measured rate, nothing to compare fix against (Step 11). **Done when:** N, k, workers, commit in `Rate`, or why not measured.
112
+ - [ ] **Step 5 — Log:** Reported error usually consequence. Read up to first runner line. Closed-target/crashed-browser → downstream of test timeout. Unmatched locator can be passing assertion. Row-level denial → silent zero rows, like empty mock. Open trace (where runner records one). Geometry (cell, y, in/out viewport) from trace or local repro at same viewport — never layout reasoning. Negative bounding box or pointer dragged out of viewport = that shape. Recognise, do not stop at: assertion at runner default beside explicit longer timeout; retrying helper burning most of test timeout before body. Check capture settings. Every CI browser / device runner keeps trace or nearest artefact (log, video, screenshot) of failed first attempt, not only the retry (e.g. Playwright `retain-on-first-failure` and `retain-on-failure-and-retries` keep it; `on-first-retry` records retry — usually passing attempt for flake). Missing setting = finding. From trace or HAR, list third-party requests (analytics, fonts, maps); recommend route stub for any blocking load/response. **Done when:** first runner line, trace notes, capture settings, third-party requests in `Log`.
113
+ - [ ] **Step 6 — Surfaces:** CI vs local = different apps (e.g. production build on preview deploy vs dev server reusing process). Fail one, not other → hydration timing, build output, stale dev server before test blame. Record CI and local `TZ`. Rule out infrastructure: failure time vs host status, preview deploy/cold-start (if used), database/vendor status. Infra-explained flake → class `infrastructure` in Step 10, verdict `INFRASTRUCTURE`, not charged to test. Same split inside CI. Worker-scoped fixture shared by many specs: mutating tenant fails whichever spec runs next. Sharing set from language server, not memory: which specs reference fixture/helper; moved helper location; type errors without full typecheck. Pace queries — back-to-back reference queries → partial results; re-run surprisingly small sets. No language server for mock-factory key. Non-typed fixture wiring (runner deps, CI YAML, scripts) → text search. Stale reference counts from before tests joined project graph. **Done when:** surface split, infra check, sharing set in `Surfaces`.
114
+ - [ ] **Step 7 — Time:** Date-touching flake → local repro with clock pinned (e.g. Playwright `page.clock.setFixedTime`, `vi.setSystemTime`): failed date, month end, DST change. `TZ` local then CI; set `TZ` before workers spawn. **Done when:** results in `Time`, or skip with evidence flake does not touch dates.
115
+ - [ ] **Step 8 — Order:** Unit runner → shuffle with recorded seed (e.g. Vitest `--sequence.shuffle --sequence.seed=<n>`). Browser runner → different worker/shard count. Record seed and counts. Tests cross-spec contamination (e.g. Step 6 shared fixture) by running, not only reference graph. **Done when:** seed, counts, result in `Order`.
116
+ - [ ] **Step 9 — Native:** Device-runner flake (e.g. Maestro, EAS) → Steps 5–6 target browser; also boot finished before flow, device-cloud retries, animation/keyboard timing. Record artifact locations (screenshots, recordings, logs). **Done when:** answers in `Native`, or skip with evidence.
117
+ - [ ] **Step 10 — Mechanism:** Teardown deletes rows event points at → most diagnoses corroborated by mechanism, not row. Distinguish "fits" vs "proven". One root-cause class: async wait, concurrency, order dependency, shared fixture state, resource leak, network, external service, time and date, randomness, unordered collection, infrastructure, or other (describe). Luo et al.: async wait, concurrency, order dependency ≈ 78% classified. Per-class counts across open flakes = series. Before timing mechanism → floating-promise/missing-await rules on spec/helpers (e.g. `@typescript-eslint/no-floating-promises`, `playwright/missing-playwright-await`); record hits so missing `await` is not hidden behind timing. Real defect behind flake → verdict `BUG`. **Done when:** class, what is not established, await hits in `Mechanism`.
118
+ - [ ] **Step 11 — Fix:** Name cause and change that removes it; making change = next step. Never `.skip`, quarantine, delete assertion, widen timeout. Before trusting the repaired test, the next step puts the bug back, watches the test go red, restores, and confirms `git diff` on the source file is empty. That is not optional on anything touching row-level access control or a cross-tenant boundary. Shared helper/fixture change = signature change: references first. One-spec fix via shared fixture → next unattributable failure. Put bug back proves deterministic fix. Flaky fix also repeats Step 4: at rate p, ~3/p runs with no failure → 95% confidence rate below p (rule of three); report states count. One verdict from `Verdicts`. **Done when:** verdict, change, or why none, run count in `Fix`.
119
+ - [ ] **Step 12 — Route:** No finding without re-checkable evidence: `file:line`, or query/run id/measurement + tool. Language-server empty inconclusive → text search corroboration. Report names destinations (sending = next step). Every flake → `docs/failures.jsonl` row (class, rate, age). Named mechanism → recommended fix + proof runs (Step 11). Real defect → own issue + ledger row. Fix waits on decision → named decision. Mechanism error tracker also saw → `bkit-audit-logs`. Retry-pass/warning CI annotated → `bkit-audit-annotations`. Missing trace/capture, third-party stub, missing `await` → recommended change (Steps 5, 10). **Done when:** every finding's Expected names destination, including ledger row.
120
+ - [ ] **Step 13 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: row per Luo et al. class + per flake feature the runner offers (e.g. retries, flaky status, repeat-each, fail-on-flaky, sequence shuffle) → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. Do not change steps during run. **Done when:** no empty row.
121
+ - [ ] **Step 14 — Anything Else:** (a) Since previous report's commit, everything touching test stability (browser/unit config: retries, workers, timeouts, trace; shared fixtures/helpers; CI workflows/runners; preview/DB for E2E; device flows) → one-line verdict each. (b) Bounded ~30 min: senior test-infra flags no step asks; read since previous run (incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status) — 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`.
122
+
123
+ ### 🔒 Gate 2: Probes Check
124
+
125
+ **Checkpoint.** Verify and check `[x]` all boxes below, then continue to `Findings` without asking.
126
+
127
+ - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
128
+ - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
129
+ - [ ] **Verdicts:** every triaged flake has one verdict from `Verdicts`; none is skip, quarantine, or a widened timeout.
130
+ - [ ] **Rates:** every triaged flake records N and k, or why the rate was not measured.
131
+ - [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off.
132
+
133
+ ## Findings
134
+
135
+ <!-- prettier-ignore -->
136
+ | Severity | Use |
137
+ | --- | --- |
138
+ | `CRITICAL` | Flake masks cross-tenant write, data loss, or a broken workflow with no workaround |
139
+ | `HIGH` | Real defect behind the flake; the only path is blocked and the workaround is a rerun |
140
+ | `MEDIUM` | Named intermittent failure; missing trace of the failed attempt; shared fixture that can attribute a failure to the next spec; repeated rerun cost |
141
+ | `LOW` | Vendor incident not charged to the test; speculative timing with no measured rate |
142
+
143
+ Scale per `.bkit/jsonl.md` § Severity. Within a severity: real defects first.
144
+
145
+ <!-- prettier-ignore -->
146
+ | ID | Severity | Verdict | Location | Evidence | Expected |
147
+ | --- | --- | --- | --- | --- | --- |
148
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
149
+
150
+ Empty and clean → one row `None`.
151
+
152
+ ## Report
153
+
154
+ ### Summary
155
+
156
+ PENDING
157
+
158
+ ### Previous Run
159
+
160
+ PENDING
161
+
162
+ ### Flakes
163
+
164
+ PENDING
165
+
166
+ ### Pin
167
+
168
+ PENDING
169
+
170
+ ### Rate
171
+
172
+ PENDING
173
+
174
+ ### Log
175
+
176
+ PENDING
177
+
178
+ ### Surfaces
179
+
180
+ PENDING
181
+
182
+ ### Time
183
+
184
+ PENDING
185
+
186
+ ### Order
187
+
188
+ PENDING
189
+
190
+ ### Native
191
+
192
+ PENDING
193
+
194
+ ### Mechanism
195
+
196
+ PENDING
197
+
198
+ ### Fix
199
+
200
+ PENDING
201
+
202
+ ### Checked
203
+
204
+ PENDING
205
+
206
+ ### Not Checked
207
+
208
+ PENDING
209
+
210
+ ### Standards Coverage
211
+
212
+ PENDING
213
+
214
+ ### Beyond the Steps
215
+
216
+ PENDING
217
+
218
+ ### Process Improvements
219
+
220
+ PENDING
221
+
222
+ ### 🔒 Gate 3: Report Check
223
+
224
+ **Checkpoint.** Verify and check `[x]` all boxes below, then stop.
225
+
226
+ - [ ] **No placeholders:** Findings table and every `Report` section have no `PENDING`.
227
+ - [ ] **Summary:** names count per severity and per verdict, and the median age of open flakes.
228
+ - [ ] **Series:** each open flake's rate and the median age beside previous report's numbers, or marked baseline.
229
+ - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
230
+ - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
231
+ - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
232
+
233
+ > `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.
234
+
235
+ <!-- bkit:end -->
236
+
237
+ ## Project Instructions