@cbartens/bkit 5.5.0 → 6.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 (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -71,13 +71,13 @@ BKIT_GH_TOKEN=
71
71
  # Generate at: https://linear.app/settings/api
72
72
  BKIT_LINEAR_API_KEY=
73
73
 
74
- # BKIT_JIRA_API_TOKEN — Atlassian API token for the Jira MCP server
74
+ # BKIT_JIRA_API_KEY — Atlassian API token for the Jira MCP server
75
75
  # (mcp.atlassian.com/v2/mcp), sent as `Authorization: Bearer`. Create it with
76
76
  # "Create API token with scopes" and pick the app "Atlassian MCP V2"; a classic
77
77
  # token or another app is refused. An org admin must first allow API-token sign-in
78
78
  # for the Rovo MCP server. Steps: .bkit/trackers.md § jira.
79
79
  # Generate at: https://id.atlassian.com/manage-profile/security/api-tokens
80
- BKIT_JIRA_API_TOKEN=
80
+ BKIT_JIRA_API_KEY=
81
81
 
82
82
  # BKIT_ANTHROPIC_API_KEY — Anthropic API key. Only needed if you run Claude Code
83
83
  # without a Claude subscription (pay-per-token mode). Subscription users leave
@@ -16,6 +16,17 @@
16
16
  "Bash(rm -rf /*)",
17
17
  "Bash(rm -rf ~/*)",
18
18
  "Bash(rm -rf $HOME/*)",
19
+ "Bash(rm -rf ~)",
20
+ "Bash(rm -rf $HOME)",
21
+ "Bash(rm -rf ${HOME})",
22
+ "Bash(rm -rf ${HOME}/*)",
23
+ "Bash(rm -fr /*)",
24
+ "Bash(rm -fr ~)",
25
+ "Bash(rm -fr ~/*)",
26
+ "Bash(rm -fr $HOME)",
27
+ "Bash(rm -fr $HOME/*)",
28
+ "Bash(rm -fr ${HOME})",
29
+ "Bash(rm -fr ${HOME}/*)",
19
30
  "Bash(chmod -R 777 /:*)",
20
31
  "Bash(git push --force)",
21
32
  "Bash(git push --force *)",
@@ -16,7 +16,7 @@
16
16
  "type": "http",
17
17
  "url": "https://mcp.atlassian.com/v2/mcp",
18
18
  "headers": {
19
- "Authorization": "Bearer ${BKIT_JIRA_API_TOKEN}"
19
+ "Authorization": "Bearer ${BKIT_JIRA_API_KEY}"
20
20
  }
21
21
  }
22
22
  }
@@ -7,6 +7,6 @@ alwaysApply: true
7
7
 
8
8
  {{BKIT_MANAGED_MARKER}}
9
9
 
10
- - **Rules:** Read `.agents/rules.md` → FOLLOW ALL rules.
10
+ - **Rules file:** Read `.agents/rules.md` → follow all rules.
11
11
 
12
12
  <!-- bkit:end -->
@@ -23,7 +23,7 @@ docs/roadmap.md merge=union
23
23
  .bkit/stats.jsonl merge=union
24
24
 
25
25
  # `.bkit/friction.jsonl` is deliberately absent: it is the one ledger rows are
26
- # REMOVED from (`bkit harvest` drains it). Union would resurrect rows a drain
26
+ # REMOVED from (bkit's harvest drains it). Union would resurrect rows a drain
27
27
  # deleted, so a conflict there carries real information and must stay blocking.
28
28
 
29
29
  # Append-only NDJSON workflow status logs: union auto-concatenates both branches'
@@ -16,7 +16,7 @@
16
16
  "type": "http",
17
17
  "url": "https://mcp.atlassian.com/v2/mcp",
18
18
  "headers": {
19
- "Authorization": "Bearer ${BKIT_JIRA_API_TOKEN}"
19
+ "Authorization": "Bearer ${BKIT_JIRA_API_KEY}"
20
20
  }
21
21
  }
22
22
  }
@@ -53,6 +53,17 @@
53
53
  "rm -rf /*": "deny",
54
54
  "rm -rf ~/*": "deny",
55
55
  "rm -rf $HOME/*": "deny",
56
+ "rm -rf ~": "deny",
57
+ "rm -rf $HOME": "deny",
58
+ "rm -rf ${HOME}": "deny",
59
+ "rm -rf ${HOME}/*": "deny",
60
+ "rm -fr /*": "deny",
61
+ "rm -fr ~": "deny",
62
+ "rm -fr ~/*": "deny",
63
+ "rm -fr $HOME": "deny",
64
+ "rm -fr $HOME/*": "deny",
65
+ "rm -fr ${HOME}": "deny",
66
+ "rm -fr ${HOME}/*": "deny",
56
67
  "git push --force*": "deny",
57
68
  "git push -f*": "deny",
58
69
  "git push --force-with-lease*": "allow",
@@ -4,8 +4,8 @@
4
4
 
5
5
  {{BKIT_MANAGED_MARKER}}
6
6
 
7
- - **Rules:** Read `.agents/rules.md` → FOLLOW ALL rules.
7
+ - **Rules file:** Read `.agents/rules.md` → follow all rules.
8
8
 
9
- **Memory hygiene:** Claude Code auto-memories (`MEMORY.md` + `memory/*.md`) are POINTERS, never copies. Facts in `docs/*.md`, `.agents/rules.md`, or `CLAUDE.md` → ONLY save path, section, and one-line hook. Issue states → query tracker or `docs/roadmap.md`; NEVER snapshot into memory.
9
+ **Memory hygiene:** Claude Code auto-memories (`MEMORY.md` + `memory/*.md`) are pointers, never copies. Facts in `docs/*.md`, `.agents/rules.md`, or `CLAUDE.md` → ONLY save path, section, and one-line hook. Issue states → query tracker or `docs/roadmap.md`; NEVER snapshot into memory.
10
10
 
11
11
  <!-- bkit:end -->
@@ -4,8 +4,8 @@
4
4
 
5
5
  {{BKIT_MANAGED_MARKER}}
6
6
 
7
- - **Rules:** Read `.agents/rules.md` → FOLLOW ALL rules.
7
+ - **Rules file:** Read `.agents/rules.md` → follow all rules.
8
8
 
9
- **Memory hygiene:** durable facts live in `docs/*.md`, `.agents/rules.md`, or this file — Antigravity loads `GEMINI.md` as a workspace rule, so keep it a pointer, never a copy. Issue states → query the tracker or `docs/roadmap.md`; NEVER snapshot them here.
9
+ **Memory hygiene:** durable facts live in `docs/*.md`, `.agents/rules.md`, or this file — Antigravity loads `GEMINI.md` as a workspace rule, so keep it a pointer, never a copy. Issue states → query tracker or `docs/roadmap.md`; NEVER snapshot them here.
10
10
 
11
11
  <!-- bkit:end -->
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - Topology / boundaries only; operational rules and library lists → domain docs.
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - One section / table: `Field | Type | Unique | Notes`, `Indices`, `Pending`.
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - Pre-push runs project gate set locally (see "Pre-push checklist" below); never `--no-verify`.
@@ -117,8 +117,8 @@ Bkit `bkit-ci.yml` recognises tags below. Case-sensitive, literal `[...]` form;
117
117
  <!-- prettier-ignore -->
118
118
  | Tag | Effect | Scope |
119
119
  | --- | --- | --- |
120
- | `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Runs a pull request's suite even when its files already passed a push run. Use when investigating suspected ghost-greens. | Read by `Check Tree Cache` and `Detect Direct Push` |
121
- | `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects. Runs a pull request's suite even when its files already passed a push run; deploy steps act on it only when they gate on the output. | Read by `Check Tree Cache` and `Detect Direct Push` |
120
+ | `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Use when investigating suspected ghost-greens. | Read by `Detect Direct Push` |
121
+ | `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects. Deploy steps act on it only when they gate on the output. | Read by `Detect Direct Push` |
122
122
  | `[force full]` | The hammer. `run_level=full` **and** it bypasses `web_affected`, so integration, `bkit-tests-e2e-web`, and `bkit-tests-live-web` run on any commit, including docs-only. The E2E spec set does not change, because a PR already runs the full suite. `@live` stays **push-only** (a docs-only `[force full]` push reaches it through the effective `web_affected`; never a PR, never a dispatch). | Read by `Detect Direct Push` step |
123
123
  | `[verbose ci]` | Escalates log detail for one run. Shipped stub flips turbo / Node / Vercel / Supabase / Playwright knobs: `TURBO_LOG_LEVEL=full`, `NODE_OPTIONS=--trace-warnings --trace-deprecation` (a job-level `env:` key, never a `$GITHUB_ENV` write, which the runner rejects while still reporting success), `DEBUG=vercel:*,supabase:*`, plus Playwright `--trace=on` (when E2E stub enabled). Add your stack's equivalents to the same `env:`. Use when `bkit-debug` diagnose returns thin evidence; never for routine pushes (trace.zip files are MB-scale). See `testing.md` for the full knob list and the `--reporter=line` hostile gap. | Read by the job-level `env:` of `bkit-tests-static` (copy the same `env:` onto each lane) |
124
124
  | `[skip ci]` / `[skip actions]` | Honoured natively by GitHub Actions, so it suppresses workflow dispatch entirely. Use sparingly: the suppressed run will not appear in `gh run list`, and downstream `workflow_run` triggers will not fire. | Native GitHub behaviour, not a bkit-level toggle |
@@ -151,7 +151,7 @@ Bkit ships a **mostly flat, wide** scaffold: `bkit-tests-scope` (always-on; read
151
151
  <!-- prettier-ignore -->
152
152
  | Run level | When | Runs | Defers |
153
153
  | --- | --- | --- | --- |
154
- | `none` | `[skip ci]` / `[skip actions]`, or `cache.outputs.skip == 'true'` (this SHA went green in the last 7 days); or release-PR mirror mode (the capstone copies the `dev` push run — § One CI run per dev commit). | Planner, then stop. | Every test lane. |
154
+ | `none` | `[skip ci]` / `[skip actions]`; or release-PR mirror mode (the capstone copies the `dev` push run — § One CI run per dev commit). | Planner, then stop. | Every test lane. |
155
155
  | `partial` | Push to `dev` that came from a merged PR, and no `[force build]` / `[force full]`. | Static, unit, integration when `web_affected`, build lanes, migration. `@live` (`bkit-tests-live-web`) still runs on this push when `web_affected`. | `bkit-tests-e2e-web`. Deploy (not the default branch). |
156
156
  | `full` | Pull request; `workflow_dispatch`; push to `{{DEFAULT_BRANCH}}`; direct push to `dev` (no merged PR); `[force build]` / `[force full]`. | Partial's lanes, plus `bkit-tests-e2e-web` when `web_affected`. Same spec set as a push (`testing.md` § E2E on PRs). | `@live` off a PR and off a dispatch. On a default-branch push, `bkit-tests-deploy` promotes **before** the E2E / `@live` lanes run; it is not required, and its own `concurrency:` group stops two releases overlapping. Health runs as `workflow_run` after CI. |
157
157
 
@@ -168,21 +168,20 @@ A newer run cancels the older one on every event **except the default branch, wh
168
168
 
169
169
  A push diffs against the head of the last successful CI run on that branch, not `github.event.before`. Fall back to `github.event.before` only when there is no such run or it is no longer an ancestor. A `workflow_dispatch` has no base commit: short-circuit the affected step to fully affected. `HEAD~1` is only for the delta gates on a dispatch. Markers are inert on dispatch; steer with inputs (§ Commit-message force tags). The planner parses markers once; every lane reads `plan.markers_present`. The only re-read of the commit or PR text is the workflow-level task-runner cache bust (e.g. `TURBO_FORCE`). Plan JSON: validate with `has()` / `!= null`. jq `//` treats `false` as absent and drops a real `run_live: false`.
170
170
 
171
- Migration-immutability and slop-delta run on every event against that same base. The starter's copies of those steps are still `pull_request`-only; that `if:` is the pre-planner shape. Point them at the planner base once `bkit-tests-scope` exists.
171
+ Migration-immutability and slop-delta run on every event against that same base. The starter's copies of those steps are still `pull_request`-only; that `if:` is the pre-planner shape. Point them at the planner base once `bkit-tests-scope` exists. Pre-push on a `dev` push resolves the same base (`resolve-push-base.mjs --local`, `.bkit/templates.md` § Git hooks) and exports it as `SLOP_BASE_REF`; a repo-owned migration-immutability pre-push check reads that variable too.
172
172
 
173
173
  Composition guidance:
174
174
 
175
- - `cache.outputs.skip` = `none` gate — every step: `if: steps.cache.outputs.skip != 'true'`.
176
175
  - `steps.detect.outputs.should_force_build` / `should_run_full` = escalation into `full`.
177
176
  - No merged PR on `dev` push (auto cache bust, e.g. `TURBO_FORCE=1`) = recovery signal — partial CI with cache busted.
178
177
  - Health (or smoke, when the probe is a script rather than a health URL): separate workflow, `workflow_run` after CI success — not a required check. One of the two, unless the probes differ (§ Smoke trigger plumbing).
179
- - Capstone `bkit-tests-check` = SOLE branch-protection required check (`bkit setup protect-main` applies it, reading the check name from `bkit.capstoneJob` and the workflow from `bkit.ciWorkflow`). Green = expected tiers ran and passed (`green == validated`), not merely "tests job didn't fail". A `partial` or cache-skipped green is not a `full` validation.
178
+ - Capstone `bkit-tests-check` = SOLE branch-protection required check (`bkit setup protect-main` applies it, reading the check name from `bkit.testing.ciCapstone` and the workflow from `bkit.testing.ciWorkflow`). Green = expected tiers ran and passed (`green == validated`), not merely "tests job didn't fail". A `partial` or cache-skipped green is not a `full` validation.
180
179
 
181
180
  ### Parallel test lanes (one lane per tier)
182
181
 
183
182
  Each tier = **own parallel lane** (job) — `bkit-tests-static` / `-unit` / `-integration` / `-e2e-web` (+ `-migration` / `-live-web`, and optional `-build-ios` / `-e2e-ios` / `-build-android` / `-e2e-android`) — **not** monolithic `bkit-tests` steps. Proven shape: bkit CI + consumer repos run separate lanes. Wall-clock = `max(lane)` not **sum** of serial steps; each tier gets honest coverage + executed-count + job-level permissions; slow tier can't serialise fast ones. Cost: per-lane setup duplicate (checkout / install, shared infra e.g. local DB) — mitigate with a remote task-runner cache (e.g. turbo) + DB service container. Capstone `needs:` **all** lanes; each emits executed-count for non-hollow assertion (`testing.md` § Validated means executed). Starter: `-static` + `-unit`; add lane per tier. Tiny repo: collapse tiers into one lane steps — capstone must assert each tier count via step outputs. E2E full-suite parity + local-vs-preview DB routing → `testing.md` § "E2E on PRs".
184
183
 
185
- **Shared resource: reset first, clean up last** (optional). WHEN: 2+ lanes use one long-lived resource. `bkit-tests-reset` runs after scope + migration, takes a lease, and puts the resource in its known state before any of those lanes start. `bkit-tests-cleanup` runs last, `if: always()`, and releases the lease. The lease is what serialises an overlapping PR and `dev` push. The planner names at most one target; an empty target skips both jobs. Capstone reds if a planned reset skipped or either job failed. DROP both when the resource is provisioned fresh per run (`testing.md` § Provision backing services fresh — the preferred answer).
184
+ **Shared resource: reset first, clean up last** (optional). WHEN: 2+ lanes use one long-lived resource. `bkit-tests-reset` runs after scope + migration, takes a lease, and puts the resource in its known state before any of those lanes start. `bkit-tests-cleanup` runs last, `if: always()`, and releases the lease. The lease is what serialises an overlapping PR and `dev` push. The planner names at most one target; an empty target skips both jobs. Capstone reds if a planned reset skipped or either job failed. Drop both when the resource is provisioned fresh per run (`testing.md` § Provision backing services fresh — the preferred answer).
186
185
 
187
186
  **Runner size = per-lane lever, only for pole.** Flat graph → one lane defines wall-clock (commonly E2E). Larger runner (more vCPU / RAM) raises internal parallelism (more workers, concurrent E2E projects) → can cut long lane substantially; scope via `runs-on: <your-larger-runner-label>` to **one** lane, default runner elsewhere. Two caveats: (1) **higher per-minute rate** — confirm before adopting (may not appear until first invoice). [Depot](https://depot.dev/docs/github-actions/runner-types) labels (e.g. `depot-ubuntu-24.04-8`) ~30% cheaper than GitHub-hosted; `bkit-ci.yml`, `bkit-cloud.yml` and `bkit-renovate.yml` are templates you own, so set `runs-on` in your copy. (2) **Zero wall-clock** when aimed at non-pole lane: consumer measured bigger E2E runner **+0.0 min** while `@live` stayed pole — worth ~7 min only after `@live` gate removed and E2E became pole. Measure first, re-measure after: pole moves. (3) **A label that does not exist does not fail, so the job queues.** Typo'd / retired label → no error anywhere, job queued indefinitely, run neither reds nor completes. Label set in exactly one place, every `runs-on:` derived from it, planner fails closed on no label.
188
187
 
@@ -227,7 +226,7 @@ Optional. A same-repo promotion PR into the default branch — head `dev`, or a
227
226
  | In progress | Waits (`--max-minutes 170`, job `timeout-minutes` 180 in this mode only) | `4` at the limit |
228
227
  | Failed / cancelled / capstone absent or skipped | Red | `1` |
229
228
  | None within 10 min (`[skip ci]` at the `dev` tip dispatches none) | Red — push a commit without it to `dev`, re-run the check | `3` |
230
- | GitHub API error 3× in a row | Red | `20` |
229
+ | GitHub API error 3x in a row | Red | `20` |
231
230
 
232
231
  **Preconditions — mirroring copies whatever the push run validated:**
233
232
 
@@ -243,17 +242,6 @@ Optional. A same-repo promotion PR into the default branch — head `dev`, or a
243
242
  - Release PR gives up PR-only output (coverage comments, PR-only coverage measurement). None blocks a merge.
244
243
  - Feature → `dev` PRs are unaffected: `pull_request ⇒ run_level=full` (§ Consumer CI contract) still holds there, which is what `/bkit-ship`'s gate relies on.
245
244
 
246
- ### Pull request tree cache (`Check Tree Cache`)
247
-
248
- A pull request lane skips its suite when the PR's files already passed that lane in a push run. Push and dispatch runs never skip: the run on a push to `dev` or the default branch is the record of what that branch holds.
249
-
250
- - **Key = files, not commit.** `scripts/ci/lanes/check-tree-cache.mjs` compares the git tree of the checked-out commit (the PR's merge preview) with the head tree of every green push run in the last 7 days. A commit ID cannot match: a PR run tests a merge commit no push run ever had.
251
- - **The same lane must have run.** A tree match counts only when that run's job of the same name concluded `success`. A `[skip ci]` / `run_level=none` push concludes green with every lane skipped, which proves nothing.
252
- - **Bypass:** `[force build]` / `[force cache]` in the PR title.
253
- - **Fails open to running.** Any `gh` / `git` failure → `skip=false`. A missing script (`scripts/ci/lanes/` not copied) → `skip=false` with a notice.
254
- - **Capstone:** a skipped lane sets `cache_skip=true`, so `bkit-tests-check` asserts no executed-test count for it.
255
- - **Needs `actions: read`** on every lane with a job-level `permissions:` block (job-level replaces the workflow-level block).
256
-
257
245
  ## Workflow-file limits GitHub does not enforce visibly
258
246
 
259
247
  **The 21,000-character expression cap.** GitHub compiles every block scalar containing a `${{ … }}` expression as one expression and refuses to compile the workflow past 21,000 characters:
@@ -274,7 +262,7 @@ Undocumented, and invisible to the toolchain, because the file stays valid YAML,
274
262
 
275
263
  - **Trigger scope.** Dispatch jobs gate on `workflow_run.head_repository` being this repo, so a fork PR's CI completion never boots one; on `dev` the same gate excludes `conclusion == 'success'` outright, so a green post-merge run costs zero runner minutes (the merge already happened, so that run only confirms the regression check passed).
276
264
  - **FID recovery on `dev`.** No open PR exists, so `{FID}` comes from the squash-merge commit scope (`feat({FID}): …`, primary), falling back to the `bkit:fid` marker in the body of the merged same-repo PR for that SHA. Neither resolving → no-op, no dispatch.
277
- - **Loop bound.** A `dev` CI failure dispatches `/bkit-debug` under `MAX_DEV_DISPATCH_ATTEMPTS` — distinct failed CI SHAs per `{FID}`. `/bkit-debug` creates no branch of its own, so on this surface it remediates on `dev` itself and its push re-triggers this same router; the cap is what terminates that loop. `feat/**` is not capped here (in-session `MAX_DEBUG_ATTEMPT` bounds it).
265
+ - **Loop bound.** A `dev` CI failure dispatches `/bkit-debug` until the `{FID}` has `bkit.workflows.debug.fix.maxAttempts` + `bkit.workflows.debug.soak.maxAttempts` distinct failed CI SHAs (2 + 2 by default). `/bkit-debug` creates no branch of its own, so on this surface it remediates on `dev` itself and its push re-triggers this same router; the cap is what terminates that loop. `feat/**` is not capped here (`/bkit-debug` bounds it with the same two limits, counted across every debug run of the feature).
278
266
 
279
267
  **Auto-route contract:** the `bkit [auto route]` free-tier gate marker is threaded by `/bkit-ship` onto the squash-merge `--subject` (not just the sync-merge commit) whenever the issue carries `bkit:auto` — this is what admits `dev`-triggered runs through the existing `bkit-cloud.yml` gate; there is no second gate path. The `[skip ci]` ship-DONE close commit that follows the squash merge never carries the marker and never triggers CI, so it cannot interact with this trigger. Trust surface, kill switch and the cap's tamper caveat → `docs/security.md` § CI Auto-Route Trust.
280
268
 
@@ -284,7 +272,7 @@ Undocumented, and invisible to the toolchain, because the file stays valid YAML,
284
272
 
285
273
  ## Ship gate + bookkeeping
286
274
 
287
- `/bkit-ship` is keyed on `bkit branches sync --head=<PR head>`, which reports whether `origin/dev` is an ancestor of the PR head (`basePath`). **Path A** — `dev` has not moved — resumes read-only, no rebase, no bookkeeping commits, no push; merge. **Path B** — `dev` moved — integrates (B1 `gh pr update-branch`, or B2 worktree + `@bkit-ship-conflict-resolve` + `bkit branches push --mode=feature`, a `--force-with-lease` push), then re-validates unconditionally. Both paths end at the same gate: `bkit runs gate --head=<current>` exits 0 (capstone concluded `success`) at the **current** PR head.
275
+ `/bkit-ship` is keyed on `bkit branches sync --head=<PR head>`, which reports whether `origin/dev` is an ancestor of the PR head (`basePath`). **Path A** — `dev` has not moved — resumes read-only, no rebase, no bookkeeping commits, no push; merge. **Path B** — `dev` moved — integrates (B1 `bkit prs update-branch --only-if-required`, which refreshes the head only when `dev` requires status checks, or B2 worktree + `@bkit-ship-conflict-resolve` + `bkit branches push --mode=feature`, a `--force-with-lease` push), then re-validates when the head moved. A B1 head left unchanged merges at the head CI passed at; the `dev` push run tests the merged result. Both paths end at the same gate: `bkit runs gate --head=<current>` exits 0 (capstone concluded `success`) at the **current** PR head.
288
276
 
289
277
  ### Consumer CI contract — `pull_request` resolves to `run_level=full`
290
278
 
@@ -294,11 +282,11 @@ The merge gate (`bkit runs gate`) asserts the capstone job's `conclusion=success
294
282
  - **A docs-only short-circuit** in the host's build-cancel (Vercel `ignoreCommand` / Netlify) that cancels the run mid-flight → capstone may land `cancelled` (gate code 15) or never complete (code 11).
295
283
  - **A `[skip ci]` token** in a feature-branch commit subject when the PR opens → GitHub suppresses the `pull_request` run entirely; the PR's `statusCheckRollup` is vacuously empty → no run at head (gate code 10).
296
284
 
297
- `bkit runs gate` covers the **common** violation shapes. A skipped non-capstone lane is **reported, not refused**, because the planned-vs-vacuous judgement belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself: the jobs API reports no reason for a skip (a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array), and a tree-cache short-circuit concludes `success` with step-level skips plus a `cache_skip` output, never `skipped`.
285
+ `bkit runs gate` covers the **common** violation shapes. A skipped non-capstone lane is **reported, not refused**, because the planned-vs-vacuous judgement belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself: the jobs API reports no reason for a skip (a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array).
298
286
 
299
- **Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.shipGateRequiredLanes` (package.json array); the default empty list never refuses. A blanket refuse-on-any-skip is **unsatisfiable by construction** for the CI shape bkit ships: a lane whose `if:` is event-scoped — `bkit-tests-live-web` runs on a push to `dev` or the default branch only — cannot run pre-merge at any head, so a pre-merge gate demanding it refuses every PR forever. Device lanes (`-ios` / `-android`) use the same rule on a pull request and a push; do not treat them as post-merge canaries. Name a lane in `shipGateRequiredLanes` only when your capstone does not assert it and the lane genuinely can run pre-merge. `BKIT_SHIP_GATE_OVERRIDE` remains the audited per-head escape hatch. What still carries the anti-vacuity guarantee is codes 10-15: a run exists, at this head, completed, not cancelled, capstone present, capstone green. Code 14 (green at a superseded head) requires `--branch`: the head-keyed run query is filtered server-side, so a moved head returns the same empty list as a head that never ran, and only a second branch-scoped query separates them. A run that is **present but degraded-but-not-skipped** (e.g. a required lane ran with a reduced test set due to a consumer config the gate cannot see) is a **residual risk named here, not claimed as covered**: the capstone is green because bkit's own `run_level` planner computed `full`; a consumer narrowing inside a lane bkit does not own is invisible to the gate. Keep the capstone (`bkit-tests-check`) as the sole branch-protection required check so `green == validated` survives a docs-only push; do not add per-lane required checks (a hollow lane then green-bars the capstone).
287
+ **Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.testing.shipGate` (package.json array); the default empty list never refuses. A blanket refuse-on-any-skip is **unsatisfiable by construction** for the CI shape bkit ships: a lane whose `if:` is event-scoped — `bkit-tests-live-web` runs on a push to `dev` or the default branch only — cannot run pre-merge at any head, so a pre-merge gate demanding it refuses every PR forever. Device lanes (`-ios` / `-android`) use the same rule on a pull request and a push; do not treat them as post-merge canaries. Name a lane in `shipGateRequiredLanes` only when your capstone does not assert it and the lane genuinely can run pre-merge. `BKIT_SHIP_GATE_OVERRIDE` remains the audited per-head escape hatch. What still carries the anti-vacuity guarantee is codes 10-15: a run exists, at this head, completed, not cancelled, capstone present, capstone green. Code 14 (green at a superseded head) requires `--branch`: the head-keyed run query is filtered server-side, so a moved head returns the same empty list as a head that never ran, and only a second branch-scoped query separates them. A run that is **present but degraded-but-not-skipped** (e.g. a required lane ran with a reduced test set due to a consumer config the gate cannot see) is a **residual risk named here, not claimed as covered**: the capstone is green because bkit's own `run_level` planner computed `full`; a consumer narrowing inside a lane bkit does not own is invisible to the gate. Keep the capstone (`bkit-tests-check`) as the sole branch-protection required check so `green == validated` survives a docs-only push; do not add per-lane required checks (a hollow lane then green-bars the capstone).
300
288
 
301
- **No duplicate dispatch on an already-triggered head (ship Step 9):** a branch push / `gh pr update-branch` fires `pull_request` at the new SHA on its own. The scaffold keys a pull request on `pr-{number}` and a `workflow_dispatch` on `github.ref`. The two are separate groups, so a redundant dispatch is never cancelled and burns a full duplicate run. Ship probes the head whose CI the gate will check (`VALIDATED_HEAD`) with `bkit runs wait --head=<VALIDATED_HEAD> --branch=<branch> --until=present --dispatch-if-absent`, which dispatches only when no run appears; the probe is not a pass condition. The completion wait (`bkit runs wait --head=<VALIDATED_HEAD> --until=completed`) reads only runs at that exact head, so a completed run from a superseded head never answers it. Gate codes 10 / 11 / 14 / 17 re-enter that probe-and-poll only, never the deferred sweep, bounded by `MAX_REVALIDATE_ATTEMPT`.
289
+ **No duplicate dispatch on an already-triggered head (ship Step 9):** a branch push / `gh pr update-branch` fires `pull_request` at the new SHA on its own. The scaffold keys a pull request on `pr-{number}` and a `workflow_dispatch` on `github.ref`. The two are separate groups, so a redundant dispatch is never cancelled and burns a full duplicate run. Ship probes the head whose CI the gate will check (`VALIDATED_HEAD`) with `bkit runs wait --head=<VALIDATED_HEAD> --branch=<branch> --until=present --dispatch-if-absent`, which dispatches only when no run appears; the probe is not a pass condition. The completion wait (`bkit runs wait --head=<VALIDATED_HEAD> --until=completed`) reads only runs at that exact head, so a completed run from a superseded head never answers it. Gate codes 10 / 11 / 14 / 17 re-enter that probe-and-poll only, never the deferred sweep, bounded by `bkit.workflows.ship.merge.maxAttempts`, which counts gate refusals and failed merges together.
302
290
 
303
291
  **No CI run for ship's own docs commit (validated-head carry-forward):** ship's pre-merge `[skip ci]` bookkeeping commit (docs, summaries, ledgers, skill removals) runs no CI. Every path between the last CI-tested commit and the PR head on the bookkeeping allow-list (`bkit ledgers only-bookkeeping`) → `bkit runs gate --validated=<sha>` checks CI at the tested commit; else code 17. Merge still pins the exact head (`--match-head-commit`). Green PR → zero extra runs. Bookkeeping commit merges untested; post-merge `dev` CI (`ship-merge-ci` row) is the backstop. `dev` REQUIRES status checks (classic branch protection or ruleset) → GitHub refuses a head with no run → ship runs CI at the PR head.
304
292
 
@@ -319,7 +307,7 @@ Smoke runs **after** deploy, in its own workflow, off the merge gate (what it ac
319
307
 
320
308
  - **Deploy happens inside CI** → key smoke to **`workflow_run`** (the CI workflow `completed` + `conclusion == 'success'`). Mind the 3-level `workflow_run` chain cap, because a fourth chained workflow will not fire.
321
309
  - **An external platform deploys after merge** (Vercel / Netlify-style Git integration) → key to a **post-deploy** signal — `deployment_status` (`state == 'success'`) or the platform's `repository_dispatch` event — so smoke fires when the deploy is actually **live**, not merely when CI finished. `workflow_run` here smokes a not-yet-serving (or about-to-be-replaced) deployment.
322
- - Either way: separate workflow, **non-blocking** (never a required check), and wait for the target to be **serving** before probing, because ready ≠ serving (`testing.md` § Deploy-reachability).
310
+ - Either way: separate workflow, **non-blocking** (never a required check), and wait for the target to be **serving** before probing, because ready != serving (`testing.md` § Deploy-reachability).
323
311
  - **Not:** smoke wired into branch protection (it gates observability, not merges), or a `workflow_run`-keyed smoke against an externally-deployed app that probes the old build.
324
312
 
325
313
  ## Applying migrations at deploy time
@@ -392,7 +380,7 @@ Elevated-permission workflows (`packages: write`, `id-token: write`, `contents:
392
380
  | Renovate (self-hosted runner) | `.bkit/templates/.github/workflows/bkit-renovate.yml` → `.github/workflows/bkit-renovate.yml` | Mend's 3 GB runner OOMs (`kernel-out-of-memory`) on a large pnpm graph. `ubuntu-latest` is ~16 GB. Edit `runs-on` in the copy. |
393
381
  | Dependabot | `.bkit/templates/.github/dependabot.yml` → `.github/dependabot.yml` | First-party GitHub. No App. One PR per package. No lockfile-maintenance job. |
394
382
 
395
- Use one. Both open PRs for the same packages. `bkit.depUpdater: "none"` skips the install-time absence advisory.
383
+ Use one. Both open PRs for the same packages. `bkit.dependencies.updater: "none"` skips the install-time absence advisory.
396
384
 
397
385
  **Gate on known advisories.** Updater PRs never fail CI on a vulnerable version already in the lockfile. Copy `.bkit/templates/scripts/ci/check-dependency-audit.mjs`, its `.test.mjs` and `accepted-advisories.json` → `scripts/ci/`; the `Check Dependency Audit` step (`bkit-tests-static`) self-skips until then. It runs `pnpm audit --json`; a blocking advisory (default high / critical) without an acceptance fails:
398
386
 
@@ -447,7 +435,7 @@ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs
447
435
  | Dependabot alerts | Read |
448
436
  | Metadata | Read-only |
449
437
 
450
- `Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. There is no separate Checks permission on a fine-grained PAT. Classic equivalent: scopes `repo`, `workflow`, `security_events` (plus `user:email` for commit authorship). Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
438
+ `Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. A fine-grained PAT has no separate Checks permission. Classic equivalent: scopes `repo`, `workflow`, `security_events` (plus `user:email` for commit authorship). Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
451
439
 
452
440
  **pnpm 11 on Mend's runner.** A large graph can OOM during `pnpm update --lockfile-only`. The example sets `minimumReleaseAge: "7 days"` and caps `PNPM_WORKERS`. To clear the per-install gate, set `minimumReleaseAge: 0` in `pnpm-workspace.yaml`. Deleting the key does not: pnpm 11 defaults it to 1440. Self-hosted on `ubuntu-latest` has the memory; the freshness setting is still yours to keep or drop.
453
441
 
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - No ad-hoc hex — theme tokens only; all colours must support Dark Mode.
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
15
15
  > - Append-only; one entry per downgraded file / line, archived issue, or raised threshold.
16
16
  > - Downgrade only when trigger known / expected; record trigger, not just verdict.
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - **Never log PII.** Scrub sensitive fields at the source.
@@ -18,7 +18,7 @@
18
18
 
19
19
  ## Context Fetch
20
20
 
21
- Failure-evidence fetching for `/bkit-debug` (`context-fetch:*` blocks + cloud CLI provisioning) → configure in `.agents/context.md`. Ready-made blocks, one file per provider: `.bkit/templates/context/` (`.bkit/templates.md` § Context-fetch blocks). Author and enable each context there — `ci`, `diff`, `e2e`, `runtime` (default) and the optional `web`. bkit hardcodes no CI host, workflow filename, branch name or e2e framework; a context with no enabled block is fetched for no run and reported `NOT CONFIGURED` every attempt. The `context=web` search host ships in bkit's egress registry, so it needs no declaration; a block whose host is unreachable anyway self-skips → external signal `UNCHECKED`, never "no known upstream issue".
21
+ Failure-evidence fetching for `/bkit-debug` (`context-fetch:*` blocks + cloud CLI provisioning) → configure in `.agents/context.md`. Ready-made blocks, one file per provider: `.bkit/templates/context/` (`.bkit/templates.md` § Context-fetch blocks). Author and enable each context there — `ci`, `diff`, `e2e`, `runtime` (default) and the optional `web`. bkit hardcodes no CI host, workflow filename, branch name, or e2e framework; a context with no enabled block is fetched for no run and reported `NOT CONFIGURED` every attempt. The `context=web` search host ships in bkit's egress registry, so it needs no declaration; a block whose host is unreachable anyway self-skips → external signal `UNCHECKED`, never "no known upstream issue".
22
22
 
23
23
  The workflow commits every captured payload inside an untrusted fence (`===== BEGIN UNTRUSTED =====` … `===== END UNTRUSTED =====`, data-only instruction above it) — fetched web / log / diff text is data, never instructions. A block emits no fence of its own; two wraps read as one nested payload.
24
24
 
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - Auth standards live only here. Other docs link, do not restate.
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - Local seed / test fixtures must never run against remote projects.
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - List technology and usage; **Why** → `decisions.jsonl`.
@@ -10,7 +10,7 @@
10
10
  > **Rules:**
11
11
  >
12
12
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
- > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
13
+ > - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - Tiers strictly separated — Static · Unit · Integration · E2E · @live · Smoke.
@@ -79,7 +79,7 @@ Scripts these files do not ship, so the plan names them and you write them: mark
79
79
  - **`bkit-tests-build-web`** — web compile, or the host deployment gate (e.g. Vercel: create this SHA's deployment, publish `deployment_url` + `deployment_id`, leave it un-promoted on the default branch). Emits no `*_ran`.
80
80
  - **`bkit-tests-build-ios` / `-e2e-ios` / `bkit-tests-build-android` / `-e2e-android`** (optional) — device build and device flows. Same rule on a PR, a push, and a dispatch: not a post-merge canary. `bkit-tests-e2e-ios` `needs:` scope, migration, reset, `bkit-tests-build-ios`, and `bkit-tests-build-web`. Android matches, with `bkit-tests-build-android`. A planned red reds the capstone. Drop any platform you do not ship. e.g. a hosted build service plus a device-flow runner.
81
81
  - **`bkit-tests-live-web`** runs `@live` against the deployed URL (`run_live`; drop the job if no deploy). Push to `dev` or the default branch only, when `web_affected`. Not a pull request. Not a dispatch. `needs:` planner + migration + reset + `bkit-tests-build-web`. Do **not** gate behind static / unit / integration / e2e. A planned failure reds the capstone. `/bkit-ship` still filters a job named `bkit-tests-live`; this name does not match, so the capstone is the gate.
82
- - **`bkit-tests-reset` / `bkit-tests-cleanup`** (optional; one shared long-lived resource) — reset takes the lease and puts the resource in its known state **before** any lane uses it; cleanup runs last, `if: always()`, and releases the lease. Planner names at most one target. Empty target skips both. Capstone reds if a planned reset skipped or either job failed. DROP both when the resource is provisioned fresh per run (§ Provision backing services fresh — the preferred answer).
82
+ - **`bkit-tests-reset` / `bkit-tests-cleanup`** (optional; one shared long-lived resource) — reset takes the lease and puts the resource in its known state **before** any lane uses it; cleanup runs last, `if: always()`, and releases the lease. Planner names at most one target. Empty target skips both. Capstone reds if a planned reset skipped or either job failed. Drop both when the resource is provisioned fresh per run (§ Provision backing services fresh — the preferred answer).
83
83
  - **Logging probe** (optional step, not a lane) — inside each runtime lane, emit one marked event and ask the error tracker whether it arrived. e.g. Sentry. Skip when that lane did not run the probe.
84
84
  - **`bkit-tests-deploy`** (optional) — on a push to the default branch only, **before** the E2E / `@live` lanes. Promotes the exact `deployment_id` `bkit-tests-build-web` published; each tenant lane `needs:` it and starts by proving production serves this run's build (by deployment id). Carries its own `concurrency:` group (`cancel-in-progress: false`) and is not a required check. A red job means the previous deployment stays live.
85
85
  - **Health** (optional, separate workflow) — `workflow_run` after CI succeeds on the default branch; smoke the deployment this SHA promoted. Not a required check. Copy the stub to `.github/workflows/health.yml`.
@@ -260,6 +260,15 @@ A plan's `Derived Test Matrix` (`docs/templates/bkit-plan.md`) is the per-featur
260
260
  - **Test name:** as the runner reports it, or its last segment (`clamp > keeps a value inside the range` → `keeps a value inside the range`).
261
261
  - **The red test stays:** after the red, the test may gain tests or formatting; a weakened, removed or rewritten assertion fails the build's verify.
262
262
 
263
+ ## JUnit reports for bkit
264
+
265
+ `bkit tests run` counts a gate's failures from JUnit XML, not from its log. It empties a report folder before each run and passes its absolute path to the gate as `$BKIT_TEST_REPORT_DIR`.
266
+
267
+ - **Every runner in a gate writes JUnit there** when the variable is set: one file per runner or per run, `*.xml`, any name. Two runs in one gate never write the same file name.
268
+ - **Counted:** failing plus erroring test cases across every file. Skipped cases do not count.
269
+ - **No reports:** `failures` is `null` (count unknown) and a hint says to turn the reporters on. The verdict still comes from the gate's exit code.
270
+ - **Unset variable:** the runner behaves as it always does, so a gate run by hand writes nothing extra.
271
+
263
272
  ## What each tier must do
264
273
 
265
274
  Tier-by-tier rules: **do** the rule, avoid the **Not** (the failure it prevents). Stack tools (Vitest / Playwright / a Supabase-style local stack / a Vercel-style preview) appear only as worked examples, because the rule is the principle; implement it for your stack.
@@ -288,8 +297,8 @@ Tier-by-tier rules: **do** the rule, avoid the **Not** (the failure it prevents)
288
297
 
289
298
  ### Deploy-reachability (between integration and E2E)
290
299
 
291
- - Before any tier runs against a freshly-deployed URL, assert it is **actually serving** — **ready ≠ serving**. A platform can report a deployment ready while it 404s / 500s; a bare "did the deploy finish" check passes anyway.
292
- - Make a missing target an **honest failure**, not a silent skip: assert ≥1 reachability test actually ran (per-file executed-count), so an unreachable target reds the build instead of green-no-op.
300
+ - Before any tier runs against a freshly-deployed URL, assert it is **actually serving** — **ready != serving**. A platform can report a deployment ready while it 404s / 500s; a bare "did the deploy finish" check passes anyway.
301
+ - Make a missing target an **honest failure**, not a silent skip: assert >=1 reachability test actually ran (per-file executed-count), so an unreachable target reds the build instead of green-no-op.
293
302
  - **Not:** an E2E suite that "passes" because every spec silently skipped against a target that was never serving.
294
303
 
295
304
  ### E2E
@@ -364,7 +373,15 @@ A tier that needs a stateful backing service (database, cache, queue, search ind
364
373
 
365
374
  bkit's `bkit-tests-migration` lane (`bkit-stub:bkit-tests-migration`) is the ready-made home: **always-on** (no job-level `if:` because e2e / live `needs:` it for remote-push ordering; a skip cascades). Replay + seed assert stay plan- / path-gated per-step. On every push to `dev`/`main` the same lane owns remote apply of new migrations (e.g. `supabase db push --linked --include-all`) (un-gated by `run_migration` so it self-heals; after replay so from-empty failure never reaches remote). Capstone asserts `result == success` whenever scope succeeded. Fold into `bkit-tests-check`'s `needs:`.
366
375
 
367
- **Local integration freshness.** If your local stack reuses a warm data volume (e.g. Docker + `supabase start`), a bare start can leave migrations unapplied (stale-volume footgun). Prefer a reset-by-default runner over a bare integration run (e.g. `turbo run test:integration`) — mirror local E2E: reset unless `--no-reset`. Shape: `pnpm test:integration:local` → script that starts local stack, hides remote env file (e.g. `.env.local`), resets from empty (e.g. `supabase db reset --local`), then runs integration (CI passthrough, because CI boots its own hermetic stack).
376
+ **Local integration freshness.** If your local stack reuses a warm data volume (e.g. Docker + `supabase start`), a bare start can leave migrations unapplied (stale-volume footgun). Prefer a reset-by-default runner over a bare integration run (e.g. `turbo run test:integration`) — mirror local E2E: reset unless `--no-reset`. Shape: `pnpm test:integration:local` → script that starts local stack, exports its URL + keys, resets from empty (e.g. `supabase db reset --local`), then runs integration (CI passthrough, because CI boots its own hermetic stack).
377
+
378
+ **Local runners never touch env files** (e.g. `.env.local`, `.env.production`; may be the only copy of live credentials):
379
+
380
+ - Target local stack by exporting its values before config loads; loaders (Next, dotenv `override: false`) never override a set key.
381
+ - Blank a hosted key with `export KEY=""`, never `unset` (loader refills unset keys from the file).
382
+ - Never delete, move or hide-and-restore the file (a killed run loses it).
383
+ - Never `vercel env pull` onto it (replaces it with the host's keys only); pull to a scratch file, copy keys across.
384
+ - Guard test fails any tracked script that deletes, moves or overwrites an env file.
368
385
 
369
386
  **"Fresh" means replay-from-empty, not a reused volume.** A bare "start the local stack" command often **reuses an existing data volume** and applies only what's missing, so a "fresh" start can silently run a months-old schema while reporting success. Only a reset / replay from an **empty** store is a freshness proof. And a green replay is not a green **seed**: assert the seed actually loaded (a known row exists), because the reset can exit 0 while a conditional insert no-ops or the seed aborts mid-file (§ Migration-replay + seed carries the full seed-determinism rules).
370
387
 
@@ -374,9 +391,9 @@ bkit's `bkit-tests-migration` lane (`bkit-stub:bkit-tests-migration`) is the rea
374
391
 
375
392
  Beyond the gates above, three practices raise confidence further — opt-in, not baseline:
376
393
 
377
- - **Mutation testing** (e.g. StrykerJS over a Vitest suite) automates the "executed ≠ exercised" intent: it injects bugs into production code and fails when no test catches them. Run it locally, on demand. It is not a CI lane and not a nightly workflow. Gate a local run on a survival-score threshold, never 100% (equivalent mutants make perfection unreachable). Capstone asks "did tests run?"; mutation asks "do they catch injected bugs?".
394
+ - **Mutation testing** (e.g. StrykerJS over a Vitest suite) automates the "executed != exercised" intent: it injects bugs into production code and fails when no test catches them. Run it locally, on demand. It is not a CI lane and not a nightly workflow. Gate a local run on a survival-score threshold, never 100% (equivalent mutants make perfection unreachable). Capstone asks "did tests run?"; mutation asks "do they catch injected bugs?".
378
395
  - **E2E sharding** (`--shard` matrix + report merge) cuts wall-clock on a large browser suite, but it is **gated on per-shard data isolation** (the unique-ID independence above). A single shared seed pins `workers: 1` and blocks sharding until the data is isolated. Isolated data is still not enough once several invocations share one job — § Concurrent invocations collide on disk, not just in the database.
379
- - **Bounded flaky-retry with tracking.** A capped retry on the flake-prone E2E tier is low-risk **only** when paired with explicit flake **tracking**, because an auto-retry that silently passes hides a real regression, the inverse of "validated ≠ didn't fail".
396
+ - **Bounded flaky-retry with tracking.** A capped retry on the flake-prone E2E tier is low-risk **only** when paired with explicit flake **tracking**, because an auto-retry that silently passes hides a real regression, the inverse of "validated != didn't fail".
380
397
 
381
398
  ## Coverage on PRs
382
399
 
@@ -390,11 +407,11 @@ Report coverage on each PR **without a paid product or a third-party service**
390
407
  - **Reporters are load-bearing.** The action reads `coverage-summary.json` (from the `json-summary` reporter, mandatory) and `coverage-final.json` (from `json`, required for `file-coverage-mode: changes`). Enable both in `coverage.reporter` or the step no-ops.
391
408
  - **Two runs, separate dirs.** `vitest run --coverage --coverage.reportsDirectory=coverage/unit --exclude '**/*.integration.test.ts'` for unit; a second run into `coverage/integration` for the integration tier. Separate dirs also avoid the last-writer-wins **clobber** a second same-dir `--coverage` run would cause.
392
409
  - **Thresholds are opt-in and per tier:**
393
- - **Unit = the gate.** Put `coverage.thresholds.branches: <current>` in a `vitest.unit.config.ts` (`mergeConfig` over `vitest.config`) that **only** the unit run loads via `-c`, because **branches** is the meaningful floor (line / statement % overstates confidence); set it to your **current** coverage and ratchet up. vitest coverage is per-**run** (root config), **not** per-project, so `projects` does **not** scope it and a `thresholds` block in `vitest.config` would red **both** runs; the `-c` file is what keeps the gate off integration. A `--coverage.thresholds.branches=<n>` CLI flag also gates, but the report step cannot read it. 80% is convention, not best practice, because a fetishised high bar breeds assertion-free line-touching tests; the executed-≠-exercised rule (§ Validated means executed) matters far more than the number.
410
+ - **Unit = the gate.** Put `coverage.thresholds.branches: <current>` in a `vitest.unit.config.ts` (`mergeConfig` over `vitest.config`) that **only** the unit run loads via `-c`, because **branches** is the meaningful floor (line / statement % overstates confidence); set it to your **current** coverage and ratchet up. vitest coverage is per-**run** (root config), **not** per-project, so `projects` does **not** scope it and a `thresholds` block in `vitest.config` would red **both** runs; the `-c` file is what keeps the gate off integration. A `--coverage.thresholds.branches=<n>` CLI flag also gates, but the report step cannot read it. 80% is convention, not best practice, because a fetishised high bar breeds assertion-free line-touching tests; the executed-!=-exercised rule (§ Validated means executed) matters far more than the number.
394
411
  - **Floor beside the figure.** The unit report step runs on **every** event (a red run too, via `!cancelled()` plus a `hashFiles` guard), passes `vite-config-path: vitest.unit.config.ts`, and comments only on same-repo PRs (`comment-on: pr`, else `none`), so every job summary, pushes included, shows the measured % against its 🎯 floor. The action regex-matches `<metric>: <number>` in that file's raw text: keep the floor on one unquoted line and no other metric name + colon + number in the file, because a broken match drops the target silently while the gate keeps passing.
395
412
  - **Integration = report-only.** Gate integration on **execution** (the capstone's `integration_ran > 0`), **not** a %. A whole-repo integration % is denominator-noise, because integration covers boundaries / flows, not pure logic, and rarely drives every branch, so a hard threshold on it punishes the correct pyramid shape. If you want a real integration %, add `--coverage.include='src/server/**'` on the integration run (same CLI-flag idiom as `--exclude`) to scope it to the integration surface, **then** set a floor, or **ratchet from current** — never a number picked from thin air.
396
413
  - **Share the unit gate with the build workflow.** Put the unit run (`vitest run -c vitest.unit.config.ts --coverage …`) in a `test:coverage:unit` script and chain it into `bkit:gate:static-unit` in place of `pnpm test`, never beside it (both run every unit test, so each runs twice) — the CI unit lane calls the script, `/bkit-build` Run Tests calls the gate, so the floor has **one source** and a regression fails in the worktree, not only on the PR. Never duplicate the command and sync it by comment, because that drifts. The build runs only the deepest declared `bkit:gate:*`, never the script by name: **left out of the chain, it never gates the build**. (bkit's own repo does exactly this.)
397
- - **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), and the tree-cache step reads runs and jobs, so re-include `actions: read` too or it breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
414
+ - **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), so re-include `contents: read` too or the checkout breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
398
415
  - **Fork PRs.** `GITHUB_TOKEN` is read-only for PRs from a fork, so commenting fails — the shipped unit step sets `comment-on: none` there (its job summary still lands) and the integration step's `head.repo == repo` guard skips it; adopt the action's `workflow_run` two-workflow pattern if you must comment on fork PRs. The integration step is also guarded on `hashFiles(...)` so a repo with **no integration tier** skips it cleanly.
399
416
  - **Base-branch delta** (▲▼ vs the default branch) is **not** shipped by default, because it needs the base's `coverage-summary.json` (a second run or a stored artifact); wire the action's `json-summary-compare-path` if you want it.
400
417
 
@@ -406,7 +423,7 @@ The **E2E tier** (`bkit-stub:e2e-coverage`) reports Playwright coverage the same
406
423
  - **Report with Monocart.** `monocart-coverage-reports` (wired via the `monocart-reporter` Playwright reporter) ingests **either** V8 or Istanbul input and emits Istanbul-format `coverage/e2e/coverage-summary.json` + `coverage-final.json` — the **same two files** the vitest action reads (`reports: ['json-summary', 'json', 'lcov']`), so no new commenter is needed.
407
424
  - **Comment by reuse.** Point `davelosert/vitest-coverage-report-action@v2` at `coverage/e2e` with `name: e2e`. If Monocart's `coverage-final.json` isn't accepted for `file-coverage-mode: changes`, drop to `file-coverage-mode: all`, or comment via a cobertura action (`irongut/CodeCoverageSummary`) on Monocart's `cobertura` report.
408
425
  - **Report-only — no threshold by default.** A whole-app E2E % is denominator-noise (E2E exercises user **flows**, not every branch), so gate the tier on the **E2E step succeeding**, not a number. For a real E2E %, scope Monocart's `entryFilter`/`sourceFilter` to the surface E2E is meant to cover, **then** ratchet from current — never a picked number.
409
- - **Permissions / forks.** The E2E coverage report runs in the **`bkit-tests-e2e-web` lane** (or, with the combined starter, in `bkit-tests-unit`), and needs that lane's job-level `pull-requests: write` + `actions: read` + `contents: read` block, or the comment can't post. The `head.repo == repo` guard skips fork PRs; a `hashFiles('coverage/e2e/coverage-summary.json')` guard skips repos with no E2E coverage.
426
+ - **Permissions / forks.** The E2E coverage report runs in the **`bkit-tests-e2e-web` lane** (or, with the combined starter, in `bkit-tests-unit`), and needs that lane's job-level `pull-requests: write` + `contents: read` block, or the comment can't post. The `head.repo == repo` guard skips fork PRs; a `hashFiles('coverage/e2e/coverage-summary.json')` guard skips repos with no E2E coverage.
410
427
 
411
428
  ## CI verbosity (`[verbose ci]`)
412
429
 
@@ -137,7 +137,7 @@ if [ -f .agents/context.md ]; then
137
137
  if [ ! -x "$BKIT" ] || ! command -v jq >/dev/null 2>&1; then
138
138
  log "context-fetch provisioning: SKIPPED — bkit (node_modules/.bin/bkit) or jq is missing. Fix: a working 'pnpm install' and the cloud setup script from .claude/bkit-cloud.md."
139
139
  else
140
- PROVISION=$("$BKIT" context list-blocks 2>/dev/null | jq -r '.provision[]' 2>/dev/null || true)
140
+ PROVISION=$("$BKIT" context list-blocks --json 2>/dev/null | jq -r '.provision[]' 2>/dev/null || true)
141
141
  if [ -n "$PROVISION" ]; then
142
142
  log "provisioning context-fetch CLIs from .agents/context.md"
143
143
  # pnpm refuses `add -g` unless its global-bin dir is on PATH (corepack pnpm skips
@@ -8,9 +8,9 @@ body:
8
8
  - type: markdown
9
9
  attributes:
10
10
  value: |
11
- Write this as the plan: a build with no plan builds from this issue.
12
- - `/bkit-plan #<issue number>` turns it into a checked plan; the build then proves each **Test first** test fails before its code exists.
13
- - `/bkit-build #<issue number>` builds straight from this issue and, when Tasks keep the exact shape below, proves each **Test first** test fails before its code exists. **Done when** guides rather than gates.
11
+ Write this as the plan: a build with no plan converts this issue into one.
12
+ - `/bkit-plan #<issue number>` turns it into a checked plan; the build then proves each **TEST FIRST** test fails before its code exists.
13
+ - `/bkit-build #<issue number>` converts this issue into a plan, then builds it and proves each **TEST FIRST** test fails before its code exists.
14
14
  - `build:lite` builds from this issue too but checks nothing: no failing-test proof, gates, PR or CI.
15
15
 
16
16
  Keep the title short: it names the feature folder. Nothing ticks boxes in an issue.
@@ -56,9 +56,30 @@ body:
56
56
  attributes:
57
57
  label: Tasks
58
58
  description: |
59
- In build order, one line each, in exactly this shape. **Done when** = a check you can verify in the code (file exists, test passes, behaviour observable). **Test first** = the matrix test that fails before the code exists, as `` `test file` `test name` fails on what it asserts ``; or `n/a — reason` for docs, config, a pure refactor, or E2E / @live only.
59
+ In build order, preferably in this shape, the same group and task blocks a plan uses: groups of up to `bkit.workflows.tasks.maxPerGroup` tasks (default 3) and `bkit.workflows.tasks.maxTestsPerGroup` **TEST FIRST** tests (default 15), each task a block, task numbers unique across the issue. **CREATE** / **READ** / **UPDATE** / **DELETE** = one line per file the task touches, as `` `symbol` in `file`: what to do `` or `` `file`: what to do ``. **DEPENDS ON** = the numbers of tasks it builds on, in the same or an earlier group. **DONE WHEN** = a check you can verify in the code (file exists, test passes, behaviour observable). **TEST FIRST** = the matrix tests that fail before the code exists, 1 to `bkit.workflows.tasks.maxTestsPerTask` per task (default 10) across up to `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3), one line each as `` `test file` `test name` fails on what goes wrong ``; or `n/a — reason` for docs, config, a pure refactor, or E2E / @live only. **TEST EXCEPTION** = written only by the owner: tests whose test-order gap you accept, each as in **TEST FIRST** ending `— reason`; it counts once committed alone in the plan. A **TEST EXCEPTION** written here is a request: the build copies it word for word, stops on it, and the owner confirms it at the build's Decision Pause, where Accept rewrites it with the owner's reason and date. Free text works too: the build converts it. A plan file for this issue wins: once one exists, the build reads its tasks only from the plan, never from here.
60
60
  placeholder: |
61
- - [ ] **Task 1:** What changes. **Done when:** what you can check. **Test first:** `path/to/list.test` `rejects an empty name` fails on the thrown error.
61
+ <!-- bkit:group 1 start -->
62
+ ### GROUP 1: Saving items
63
+ <!-- bkit:task 1 start -->
64
+ - [ ] **TASK 1:** Refuse an empty item name
65
+ - **UPDATE:** `saveItem` in `path/to/items`: refuse an empty name
66
+ - **READ:** `path/to/list`: where saved items show
67
+ - **DONE WHEN:** saving an empty name stores nothing and shows why
68
+ - **TEST FIRST:**
69
+ - `path/to/list.test` `rejects an empty name` fails on an empty name being saved
70
+ <!-- bkit:task 1 end -->
71
+ <!-- bkit:task 2 start -->
72
+ - [ ] **TASK 2:** Show saved items in the list
73
+ - **CREATE:** `path/to/list-row`: one row per saved item
74
+ - **DELETE:** `ItemPreview` in `path/to/list`: replaced by the new row
75
+ - **DEPENDS ON:** 1
76
+ - **DONE WHEN:** a saved item appears in the list
77
+ - **TEST FIRST:**
78
+ - `path/to/list.test` `shows a saved item` fails on the list staying empty
79
+ - **TEST EXCEPTION:**
80
+ - `path/to/list.test` `shows a saved item` — the old preview already shows saved items, so it cannot fail first
81
+ <!-- bkit:task 2 end -->
82
+ <!-- bkit:group 1 end -->
62
83
  validations:
63
84
  required: true
64
85
  - type: textarea