@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,51 +1,51 @@
1
- <!-- Note: Plans live at `docs/plans/{YYYYMM}/{FID}-plan.md` (canonical month bucket). `{YYYYMM}` = creation month, set once by the first workflow run for `{FID}`. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/` and are delete-eligible. The canonical copy is stamped with a `bkit:anchor` block recording the base commit (`baseSha`), its ref (`baseRef`), and the design it targets (`designPath`, `designBaseSha`); never hand-author or edit it. `@bkit-plan-generate` fills this template. -->
2
-
3
1
  <!-- bkit:start -->
4
2
 
5
3
  {{BKIT_MANAGED_MARKER}}
6
4
 
5
+ <!-- Note: @bkit-plan-generate fills this template. The plan lives at `docs/plans/{YYYYMM}/{FID}-plan.md`, the canonical month bucket, where `{YYYYMM}` is the month the first workflow run for `{FID}` created it, set once. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/`, and may be deleted. The canonical copy is stamped with a `bkit:anchor` block that records the base commit (`baseSha`), its ref (`baseRef`) and the design it targets (`designPath`, `designBaseSha`). NEVER write or edit that block by hand. -->
6
+
7
7
  # [Plan Title] Implementation Plan
8
8
 
9
9
  > [!CAUTION]
10
- > **Purpose:** Implementation plan — pre-flight, gates, runbook, verification, rollback.
10
+ > **Purpose:** The implementation plan: pre-flight checks, gates, the runbook, verification and rollback.
11
11
 
12
12
  ## Context & Goals
13
13
 
14
- [Problem or feature, and why it is needed; initially set to `PENDING`.]
14
+ [The problem or feature, and why it is needed. Initially set to `PENDING`.]
15
15
 
16
16
  **Related Issues:**
17
17
 
18
- - [`#N — title (state)` per related issue. None → `None`; initially set to `PENDING`.]
18
+ - [One `#N — title (state)` line per related issue. **If** none → `None`. Initially set to `PENDING`.]
19
19
 
20
20
  ---
21
21
 
22
22
  ## 👤 ⚠️ Acceptance Scenario
23
23
 
24
24
  > [!CAUTION]
25
- > **🛑 HUMAN must READ and CONFIRM this SECTION.**
26
- > Testable feature contract — implementation, tests, verification derive from what you confirm here. Wrong here → wrong downstream.
25
+ > 🛑 The owner reads and confirms this section.
26
+ > This is the feature's testable contract. The implementation, the tests and the verification all follow from what you confirm here, so a mistake here carries into every later step.
27
27
  >
28
- > **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). Agent handles rest.
28
+ > **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). The agent handles the rest.
29
29
 
30
30
  ### Narrative
31
31
 
32
- [1-2 sentences from the user's side: what they do, what they get back; initially set to `PENDING`.]
32
+ [One or two sentences from the user's side: what they do, and what they get back. Initially set to `PENDING`.]
33
33
 
34
34
  ### Success Criteria
35
35
 
36
- [Up to 5 measurable outcomes; initially set to `PENDING`.]
36
+ [Up to 5 measurable outcomes. Initially set to `PENDING`.]
37
37
 
38
38
  ### Process Sketch
39
39
 
40
- - **WHEN** [trigger / user action] **→ THEN** [observable outcome]
41
- - **WHEN** [next step] **→ THEN** [outcome]
42
- - **IF** [edge case / failure — mirrors an Edge Cases row] **→ THEN** [handling]
40
+ - **WHEN** [the trigger or user action] **→ THEN** [the observable outcome]
41
+ - **WHEN** [the next step] **→ THEN** [its outcome]
42
+ - **IF** [an edge case or failure, mirroring an Edge Cases row] **→ THEN** [how it is handled]
43
43
 
44
- _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN** it is queued and a receipt shown; **IF** the file is malformed **→ THEN** it is rejected inline and nothing is queued.
44
+ _e.g.,_ **WHEN** a user submits the form with a valid file **→ THEN** it is queued and a receipt is shown; **IF** the file is malformed **→ THEN** it is rejected inline and nothing is queued.
45
45
 
46
46
  ### Concrete Example
47
47
 
48
- **Setup:** [User role, existing state, context]
48
+ **Setup:** [The user's role, the existing state and the context]
49
49
 
50
50
  **Steps:**
51
51
 
@@ -53,28 +53,28 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
53
53
  2. User [does X] → System [responds with Y]
54
54
  3. …
55
55
 
56
- **Outcome:** [End state the user sees that proves success]
56
+ **Outcome:** [The end state the user sees that proves success]
57
57
 
58
58
  ### Edge Cases
59
59
 
60
60
  <!-- prettier-ignore -->
61
61
  | Scenario | Expected Behavior |
62
62
  | --- | --- |
63
- | [Design Key Edge Case or plan-added case] | [Specific behavior] |
64
- | [e.g., concurrent edit from another device] | [e.g., last-write-wins, no crash] |
63
+ | [a design Key Edge Case, or a case the plan adds] | [the specific behavior] |
64
+ | [e.g., a concurrent edit from another device] | [e.g., the last write wins, with no crash] |
65
65
 
66
66
  ### Derived Test Matrix
67
67
 
68
- `Type` = a tier from `docs/testing.md`: Static, Unit, Integration, @live (golden), E2E, fresh-DB replay, Smoke.
68
+ `Type` is a tier from `docs/testing.md`: Static, Unit, Integration, @live (golden), E2E, fresh-DB replay or Smoke. `Task` is the one runbook task that lands the row's test.
69
69
 
70
70
  <!-- prettier-ignore -->
71
- | Test description | Type | Target file |
72
- | --- | --- | --- |
73
- | [e.g., Happy path: user creates event, sees it in list] | E2E | [e.g. `apps/web/e2e/[feature].spec.ts`] |
74
- | [e.g., Service correctly parses payload] | Unit | [e.g. `packages/[pkg]/[module].test.ts`] |
75
- | [e.g., API endpoint enforces tenant isolation] | Integration | [e.g. `packages/api/[feature].integration.test.ts`] |
76
- | [e.g., Real 3rd-party API returns expected shape and a boundary-only identity — not "did not throw"] | @live (golden) | [e.g. `packages/[pkg]/[feature].live.test.ts`] |
77
- | [e.g., New migration replays from empty and seed loads] | fresh-DB replay | [e.g. `supabase/migrations/*`] (replayed by `bkit-tests-migration`) |
71
+ | Test description | Type | Target file | Task |
72
+ | --- | --- | --- | --- |
73
+ | [e.g., happy path: a user creates an event and sees it in the list] | E2E | [e.g., `apps/web/e2e/[feature].spec.ts`] | 2 |
74
+ | [e.g., the service parses the payload correctly] | Unit | [e.g., `packages/[pkg]/[module].test.ts`] | 2 |
75
+ | [e.g., the API endpoint enforces tenant isolation] | Integration | [e.g., `packages/api/[feature].integration.test.ts`] | 2 |
76
+ | [e.g., the real third-party API returns the expected shape and a boundary-only identity, not just "did not throw"] | @live (golden) | [e.g., `packages/[pkg]/[feature].live.test.ts`] | 2 |
77
+ | [e.g., the new migration replays from empty and the seed loads] | fresh-DB replay | [e.g., `packages/db/migrations/*`] (replayed by `bkit-tests-migration`) | 1 |
78
78
 
79
79
  ### 👤 ✅ Human Confirmation
80
80
 
@@ -85,27 +85,26 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
85
85
  ## 👤 ⚠️ Breaking Changes & Naming Review
86
86
 
87
87
  > [!CAUTION]
88
- > **🛑 HUMAN must READ and CONFIRM this SECTION.**
89
- > Review proposed names and breaking changes below.
88
+ > 🛑 The owner reads and confirms this section.
90
89
 
91
- [Proposed names (pages, files, DB tables, routes, API contracts) and breaking changes (DB structure, global layout). None → `None`; initially set to `PENDING`.]
90
+ [Each proposed name (page, file, database table, route, API contract) and each breaking change (database structure, global layout). **If** none → `None`. Initially set to `PENDING`.]
92
91
 
93
92
  ### 👤 ✅ Human Confirmation
94
93
 
95
- - [ ] **Breaking Changes confirmed:** I have reviewed all breaking changes and naming decisions above.
94
+ - [ ] **Breaking Changes confirmed:** I have reviewed every breaking change and naming decision above.
96
95
 
97
96
  ---
98
97
 
99
98
  ## 👤 ⚠️ Open Questions & Assumptions
100
99
 
101
100
  > [!CAUTION]
102
- > **🛑 HUMAN must READ and CONFIRM this SECTION.**
103
- > Unknowns + assumptions this plan relies on. Unresolved question = risk; wrong assumption breaks downstream. If none, write "None".
101
+ > 🛑 The owner reads and confirms this section.
102
+ > These are the unknowns and assumptions this plan relies on. An unresolved question is a risk, and a wrong assumption breaks what follows. **If** there are none → write `None`.
104
103
 
105
- - **Assumption:** [what the plan takes as given] → [what breaks if it's wrong]
106
- - **Open Question:** [decision needed] → [who / how to resolve]
107
- - **Options:** A — [option, trade-off] · B — [option, trade-off] · C — [option, trade-off, optional]
108
- - **Recommended:** [A] — [why, 1 line]
104
+ - **Assumption:** [what the plan takes as given] → [what breaks if it is wrong]
105
+ - **Open Question:** [the decision needed] → [who resolves it, and how]
106
+ - **Options:** A) [option] — [trade-off] · B) [option] — [trade-off] · C) [option] — [trade-off, optional]
107
+ - **Recommended:** A) [option] — [why, in one line]
109
108
  - **Default if unanswered:** [what the agent proceeds with]
110
109
 
111
110
  ### 👤 ✅ Human Confirmation
@@ -116,190 +115,192 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
116
115
 
117
116
  ## Alternative Approaches & Recommendations
118
117
 
119
- [Rejected paths and why; future phase recommendations; initially set to `PENDING`.]
118
+ [The paths rejected and why, and recommendations for a future phase. Initially set to `PENDING`.]
120
119
 
121
120
  ## Out of Scope
122
121
 
123
- [Excluded items, each `Exempt`. None → `None`; initially set to `PENDING`.]
122
+ [Each excluded item, marked `Exempt`. **If** none → `None`. Initially set to `PENDING`.]
124
123
 
125
124
  <!-- prettier-ignore -->
126
125
  | Excluded item | Why `Exempt` | Where it belongs |
127
126
  | --- | --- | --- |
128
- | [feature/fix] | [why genuinely-additive] | [design non-goal / follow-up #N / future phase] |
127
+ | [the excluded feature or fix] | [why it only adds to the plan's goal] | [a design non-goal, a follow-up issue or a future phase] |
128
+ | [e.g., bulk status change] | [e.g., single changes meet the goal, and bulk changes add to it] | [e.g., follow-up #N] |
129
129
 
130
130
  ## Suggested Scope Expansion
131
131
 
132
- [Candidates overlapping this plan's surfaces. None → `None`; initially set to `PENDING`.]
132
+ [The candidates that overlap this plan's surfaces. **If** none → `None`. Initially set to `PENDING`.]
133
133
 
134
134
  <!-- prettier-ignore -->
135
135
  | Candidate | Source | Overlaps | Recommendation |
136
136
  | --- | --- | --- | --- |
137
- | [what it is] | [`#N` / `docs/deferrals.jsonl` / `docs/failures.jsonl` / audit finding id] | [surface / task it touches] | [fold in / keep deferred / needs design decision] |
137
+ | [what it is] | [`#N`, `docs/deferrals.jsonl`, `docs/failures.jsonl` or an audit finding id] | [the surface or task it touches] | [fold in, keep deferred, or needs a design decision] |
138
138
 
139
139
  ## Security & Privacy
140
140
 
141
- - [ ] **New API Route** — auth guard (e.g. a `requireMember`-style check); rate limit if auth-adjacent.
142
- - [ ] **New DB Table/Column** — deny-by-default row / tenant access policy (e.g. RLS); tenant-scoped.
143
- - [ ] **Role-Gated Mutation** — role checked at the API layer.
144
- - [ ] **User Input** — schema-validated in the handler (e.g. Zod `parse()`).
145
- - [ ] **PII** — absent from logs; audit / CDC trigger updated for new monitored columns.
146
- - [ ] **Redirect URL** — allow-list validated.
147
- - [ ] **Webhook** — signature verified; secret in the env schema.
148
- - [ ] **New Secret/Env Var** — in the env schema and the project's secret manager.
141
+ - [ ] **New API Route** — an auth guard (e.g., a `requireMember`-style check). **If** the route is auth-adjacent → a rate limit as well.
142
+ - [ ] **New DB Table/Column** — a deny-by-default row or tenant access policy (e.g., a row-level policy in the database), scoped to the tenant.
143
+ - [ ] **Role-Gated Mutation** — the role is checked at the API layer.
144
+ - [ ] **User Input** — validated against a schema in the handler (e.g., the schema library's parse call).
145
+ - [ ] **PII** — kept out of logs, and the audit or CDC trigger is updated for new monitored columns.
146
+ - [ ] **Redirect URL** — validated against an allow-list.
147
+ - [ ] **Webhook** — the signature is verified, and the secret is in the env schema.
148
+ - [ ] **New Secret/Env Var** — in the env schema and in the project's secret manager.
149
149
 
150
- _If none apply: "None — no new routes, DB writes, secrets, or user input."_
150
+ [**If** no row applies → write "None — no new routes, DB writes, secrets, or user input."]
151
151
 
152
152
  ## Pre-Flight / Dependencies
153
153
 
154
154
  ### Core
155
155
 
156
- - [ ] **Package Management:** packages declared; manifest and lockfile in sync.
157
- - [ ] **Dependency Versions:** outdated deps and toolchain / stack CLI versions checked.
158
- - [ ] **Existing-Solution Search (reuse over duplicate):** in-repo, dependency and ecosystem sweeps recorded in `Reuse Inventory`.
159
- - [ ] **User Context:** file access confirmed; missing user information requested.
160
- - [ ] **Project Context:** relevant `docs/knowledge.jsonl` and `docs/decisions.jsonl` rows read.
161
- - [ ] **Testing & Quality:** testing strategy matches `docs/testing.md`.
162
- - [ ] **Prerequisite Plans:** [plans to finish first, or `None`]
156
+ - [ ] **Package Management:** the packages are declared, and the manifest and lockfile are in sync.
157
+ - [ ] **Dependency Versions:** outdated dependencies and the toolchain and stack CLI versions are checked.
158
+ - [ ] **Existing-Solution Search (reuse over duplicate):** the in-repo, dependency and ecosystem searches are recorded in `Reuse Inventory`.
159
+ - [ ] **User Context:** access to the files is confirmed, and missing user information is requested.
160
+ - [ ] **Project Context:** the relevant `docs/knowledge.jsonl` and `docs/decisions.jsonl` rows are read.
161
+ - [ ] **Testing & Quality:** the testing strategy matches `docs/testing.md`.
162
+ - [ ] **Prerequisite Plans:** [the plans to finish first. **If** none → `None`.]
163
163
 
164
164
  ### Conditional
165
165
 
166
- - [ ] **Secrets & Env Vars:** secret store and service-account roles checked.
167
- - [ ] **Schema State:** database state confirmed against `docs/data-schema.md`.
168
- - [ ] **Architecture & UI:** `docs/architecture.md` topology; `docs/design.md` for UI.
169
- - [ ] **Observability:** logs, audit tables and traces per `docs/observability.md`.
170
- - [ ] **Notifications:** alert / toast tier per the notifications doc.
166
+ - [ ] **Secrets & Env Vars:** the secret store and the service-account roles are checked.
167
+ - [ ] **Schema State:** the database state is confirmed against `docs/data-schema.md`.
168
+ - [ ] **Architecture & UI:** the topology is checked against `docs/architecture.md`, and any UI against `docs/design.md`.
169
+ - [ ] **Observability:** logs, audit tables and traces follow `docs/observability.md`.
170
+ - [ ] **Notifications:** the alert or toast tier follows the notifications doc.
171
171
 
172
172
  ### 🔒 Gate 1: Prerequisites Check
173
173
 
174
- - [ ] **Acceptance Scenario confirmed:** Human confirmed `👤 Acceptance Scenario` section (checkbox is `[x]`).
175
- - [ ] **Breaking Changes confirmed:** Human confirmed `⚠️ Breaking Changes & Naming Review` section (checkbox is `[x]`).
176
- - [ ] **Open Questions confirmed:** Human confirmed `👤 Open Questions & Assumptions` section (checkbox is `[x]`).
177
- - [ ] **Security & Privacy checked:** applicable rows verified, or `None` justified.
178
- - [ ] **Reuse Inventory complete:** every capability has a row with `Search performed` and `Decision`; every `NEW` cites its reason.
179
- - [ ] **Gate 1 - Verified:** Core items and applicable Conditional items checked.
174
+ - [ ] **Acceptance Scenario confirmed:** the `👤 ⚠️ Acceptance Scenario` checkbox is `[x]`, ticked by a human.
175
+ - [ ] **Breaking Changes confirmed:** the `👤 ⚠️ Breaking Changes & Naming Review` checkbox is `[x]`, ticked by a human.
176
+ - [ ] **Open Questions confirmed:** the `👤 ⚠️ Open Questions & Assumptions` checkbox is `[x]`, ticked by a human.
177
+ - [ ] **Security & Privacy checked:** every applicable row is verified, or `None` is justified.
178
+ - [ ] **Reuse Inventory complete:** every capability has a row with `Search performed` and `Decision` filled in.
179
+ - [ ] **Reuse reasons:** every `NEW` row cites its reason.
180
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
180
181
 
181
182
  ## Data Schema Integration
182
183
 
183
- [How this feature uses the existing schema and what changes; initially set to `PENDING`.]
184
+ [How this feature uses the existing schema, and what changes. Initially set to `PENDING`.]
184
185
 
185
186
  ### Data Schema Usage
186
187
 
187
- [Existing `docs/data-schema.md` tables and fields read (Input) or written (Output). None → `None`; initially set to `PENDING`. e.g.,
188
+ [The existing `docs/data-schema.md` tables and fields the feature reads (Input) or writes (Output). **If** none → `None`. Initially set to `PENDING`.]
188
189
 
189
- - **Input (Read):** `users.id`, `items.title`
190
- - **Output (Write):** `items.status`, `job_audits.log`]
190
+ - [e.g., **Input (Read):** `users.id`, `items.title`]
191
+ - [e.g., **Output (Write):** `items.status`, `job_audits.log`]
191
192
 
192
193
  ### Data Schema Changes
193
194
 
194
- [New tables, new fields, or changed fields to record in `docs/data-schema.md`. None → `None`; initially set to `PENDING`. e.g.,
195
+ [The new tables, new fields and changed fields to record in `docs/data-schema.md`. **If** none → `None`. Initially set to `PENDING`.]
195
196
 
196
- - **ADD:** `items.new_field` (type: text)
197
- - **MODIFY:** `users.role` (added enum value)]
197
+ - [e.g., **ADD:** `items.new_field` (type: text)]
198
+ - [e.g., **MODIFY:** `users.role` (added enum value)]
198
199
 
199
200
  ## Reuse Inventory
200
201
 
201
- [One row per capability the plan introduces; initially set to `PENDING`.]
202
+ [One row per capability the plan introduces. Initially set to `PENDING`.]
202
203
 
203
204
  <!-- prettier-ignore -->
204
205
  | Capability | File | Search performed | Existing candidates | Decision | Justification |
205
206
  | --- | --- | --- | --- | --- | --- |
206
- | [what the plan must do] | `path/to/existing` | `grep -rn "..."`; references to `{symbol}`; `docs/capabilities.md`; `{framework} {capability} built-in` | `path/to/existing` — covers [X], missing [Y] | EXTEND | [what changes in it to close the gap] |
207
- | [e.g., item status column] | `supabase/migrations/{timestamp}_add_items_status.sql` | [exact commands / queries run] | None — [what was searched] | NEW | [reason (a)/(b)/(c)] |
208
- | [e.g., status change action] | `packages/api/src/items/setStatus.ts` | [exact commands / queries run] | None — [what was searched] | NEW | [reason (a)/(b)/(c)] |
207
+ | [what the plan must do] | `path/to/existing` | `grep -rn "..."`, references to `{symbol}`, `docs/capabilities.md`, `{framework} {capability} built-in` | `path/to/existing` — covers [X], missing [Y] | EXTEND | [what changes in it to close the gap] |
208
+ | [e.g., item status column] | `packages/db/migrations/{timestamp}_add_items_status.sql` | [the exact commands and queries run] | None — [what was searched] | NEW | [reason (a), (b) or (c)] |
209
+ | [e.g., status change action] | `packages/api/src/items/setStatus.ts` | [the exact commands and queries run] | None — [what was searched] | NEW | [reason (a), (b) or (c)] |
209
210
 
210
211
  ## Architecture & Component Changes
211
212
 
212
- [Files grouped by area (DB, API, Backend, Frontend, Cron, Observability), one header each; initially set to `PENDING`.]
213
- **Ledger rows:** [Backticked `key` of every `docs/decisions.jsonl` / `docs/deferrals.jsonl` row written for this plan, comma-separated. If none, write "None"; initially set to `PENDING`.]
213
+ [The files, grouped by area (DB, API, Backend, Frontend, Cron, Observability), with one heading per area. Initially set to `PENDING`.]
214
+ **Ledger rows:** [The backticked `key` of every `docs/decisions.jsonl` and `docs/deferrals.jsonl` row written for this plan, comma-separated. **If** none → write "None". Initially set to `PENDING`.]
214
215
 
215
216
  ### Database Migrations
216
217
 
217
- [New tables / columns / access policies (e.g. RLS) and the migration that adds them; initially set to `PENDING`.]
218
+ [The new tables, columns and access policies (e.g., row-level policies), and the migration that adds them. Initially set to `PENDING`.]
218
219
 
219
220
  ### [Component Area 1]
220
221
 
221
- [Summary of component changes; initially set to `PENDING`.]
222
+ [A summary of the component changes. Initially set to `PENDING`.]
222
223
 
223
224
  #### [MODIFY] `path/to/file.ext`
224
225
 
225
- - **Existence Check:** [file exists]
226
- - [Logic, schema, or API contract changes.]
226
+ - **Existence Check:** [the file exists]
227
+ - [The logic, schema or API contract changes.]
227
228
 
228
229
  #### [new] `path/to/file.ext`
229
230
 
230
- - **Reuse Check:** [`Reuse Inventory` row + reason (a)/(b)/(c)]
231
- - [Purpose, access policies (e.g. RLS), input validation (e.g. Zod), naming.]
231
+ - **Reuse Check:** [the `Reuse Inventory` row, and reason (a), (b) or (c)]
232
+ - [The purpose, access policies, input validation and naming.]
232
233
 
233
234
  #### [DELETE] `path/to/file.ext`
234
235
 
235
- - [Reason]
236
+ - [The reason]
236
237
 
237
238
  ### Cron Jobs & Scheduled Tasks
238
239
 
239
- [Scheduled tasks (e.g. Vercel cron, pg_cron, Inngest). None → `None`; initially set to `PENDING`.]
240
+ [The scheduled tasks (e.g., a hosting platform's cron, a database scheduler or a background-job runner). **If** none → `None`. Initially set to `PENDING`.]
240
241
 
241
242
  ## Supersession Inventory
242
243
 
243
- [Existing artifacts the new code replaces. None → `None`; initially set to `PENDING`.]
244
+ [The existing artifacts the new code replaces. **If** none → `None`. Initially set to `PENDING`.]
244
245
 
245
246
  <!-- prettier-ignore -->
246
247
  | Existing artifact | Replaced by | Decision | Justification |
247
248
  | --- | --- | --- | --- |
248
- | `path/to/old-thing` | `path/to/new-thing` | DELETE | [reason] |
249
+ | `path/to/old-thing` | `path/to/new-thing` | DELETE | [the reason] |
249
250
 
250
251
  ## Documentation Updates
251
252
 
252
- [One row per doc this change touches; others via `.agents/docs.md`.]
253
+ [One row per doc this change touches. Find any doc not listed here through `.agents/docs.md`.]
253
254
 
254
255
  <!-- prettier-ignore -->
255
256
  | Doc | Change required |
256
257
  | --- | --- |
257
- | `docs/knowledge.jsonl` | [learnings, gotchas] |
258
+ | `docs/knowledge.jsonl` | [learnings and gotchas] |
258
259
  | `docs/decisions.jsonl` | [architecture decisions] |
259
- | `docs/architecture.md` | [topology / component changes] |
260
- | `docs/technology.md` | [frameworks, libraries, conventions] |
261
- | `docs/data-schema.md` | [new tables / columns] |
262
- | `docs/design.md` | [palette, typography, components] |
263
- | `docs/testing.md` | [new test files / patterns] |
264
- | `docs/observability.md` | [new log names / spans] |
260
+ | `docs/architecture.md` | [topology or component changes] |
261
+ | `docs/technology.md` | [frameworks, libraries and conventions] |
262
+ | `docs/data-schema.md` | [new tables or columns] |
263
+ | `docs/design.md` | [palette, typography and components] |
264
+ | `docs/testing.md` | [new test files or patterns] |
265
+ | `docs/observability.md` | [new log names or spans] |
265
266
 
266
267
  ## Rollback Strategy
267
268
 
268
269
  <!-- prettier-ignore -->
269
270
  | Axis | Action | Notes |
270
271
  | --- | --- | --- |
271
- | **DB** | [Corrective migration that undoes the change; safe if additive-only] | merged migrations are immutable — ship the corrective migration through CI's migration lane; dev full reset → `docs/deployments.md` § Dev rollback runbook |
272
- | **Code** | [Git revert SHA or feature flag to disable] | `git revert {COMMIT}` |
273
- | **Risk window** | [Gap between DB migration merge and code deploy] | [e.g., "~2 min Vercel build — migration must be additive"] |
272
+ | **DB** | [A corrective migration that undoes the change. It is safe when the change only adds.] | Merged migrations are immutable, so ship the corrective migration through CI's migration lane. For a full dev reset, see `docs/deployments.md` § Dev rollback runbook. |
273
+ | **Code** | [The git revert SHA, or the feature flag that disables the change] | `git revert {COMMIT}` |
274
+ | **Risk window** | [The gap between the DB migration merge and the code deploy] | [e.g., "~2 min deploy build, so the migration must be additive"] |
274
275
 
275
- _No DB changes: "Code-only — `git revert` sufficient."_
276
+ [**If** there are no DB changes → write "Code-only — `git revert` sufficient."]
276
277
 
277
278
  ## Agent Execution Runbook
278
279
 
279
- [Chronological task checklist; initially set to `PENDING`.]
280
+ [A chronological task checklist. Initially set to `PENDING`.]
280
281
 
281
282
  **Implementation Tasks (Examples):**
282
283
 
283
284
  <!-- bkit:group 1 start -->
284
285
 
285
- ### GROUP 1: [e.g., Item status in the API]
286
+ ### TASK GROUP 1: [e.g., Item status in the API]
286
287
 
287
288
  <!-- bkit:task 1 start -->
288
289
 
289
- - [ ] **TASK 1:** [e.g., Create DB migration with the repo's migration script (`pnpm db:diff`)]
290
- - **CREATE:** `supabase/migrations/{timestamp}_add_items_status.sql`: [e.g., `items.status` column]
291
- - **DONE WHEN:** [e.g., the migration exists; `pnpm db:reset` replays it cleanly]
292
- - **TEST FIRST:** n/a — [e.g., migration; fresh-DB replay tier]
290
+ - [ ] **TASK 1:** [e.g., Create the database migration with the repo's migration script (`pnpm db:diff`)]
291
+ - **CREATE:** `packages/db/migrations/{timestamp}_add_items_status.sql`: [e.g., the `items.status` column]
292
+ - **DONE WHEN:** [e.g., the migration exists, and `pnpm db:reset` replays it cleanly]
293
+ - **TEST FIRST:** n/a — [e.g., a migration, covered by the fresh-DB replay tier]
293
294
 
294
295
  <!-- bkit:task 1 end -->
295
296
 
296
297
  <!-- bkit:task 2 start -->
297
298
 
298
- - [ ] **TASK 2:** [e.g., Implement backend API action `setStatus`]
299
- - **CREATE:** `setStatus` in `packages/api/src/items/setStatus.ts`: [e.g., Zod-validated status change]
299
+ - [ ] **TASK 2:** [e.g., Implement the backend API action `setStatus`]
300
+ - **CREATE:** `setStatus` in `packages/api/src/items/setStatus.ts`: [e.g., a validated status change]
300
301
  - **READ:** `ItemStatus` in `packages/api/src/items/schema.ts`: [e.g., the allowed statuses]
301
302
  - **DEPENDS ON:** 1
302
- - **DONE WHEN:** [e.g., unit test covers each status transition; integration test passes]
303
+ - **DONE WHEN:** [e.g., a unit test covers each status transition, and the integration test passes]
303
304
  - **TEST FIRST:**
304
305
  - `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on [e.g., an unknown status being accepted]
305
306
  - `packages/api/items.integration.test.ts` `persists the new status` fails on [e.g., no row being stored]
@@ -310,43 +311,48 @@ _No DB changes: "Code-only — `git revert` sufficient."_
310
311
 
311
312
  ### 🔒 Gate 2: Code Implementation Check
312
313
 
313
- - [ ] **No bolt-on / no gate-weakening:** every `[NEW]` traces to a `Reuse Inventory` `NEW` row; every `EXTEND` landed in its named artifact; no gate weakened.
314
- - [ ] **Every task has a test or a TEST EXCEPTION:** every planned test recorded a red before its code and is unchanged since; test-order gaps cleared only by a human-committed `TEST EXCEPTION` field.
315
- - [ ] **Gate 2 - Verified:** every box above checked.
314
+ - [ ] **No bolt-on:** every `[NEW]` file traces to a `Reuse Inventory` `NEW` row.
315
+ - [ ] **Extensions landed:** every `EXTEND` landed in the artifact its row names.
316
+ - [ ] **No gate weakened:** no gate was weakened.
317
+ - [ ] **Red before code:** the tests step recorded every planned test of the group red, or as an `updated` existing test, before its code step ran.
318
+ - [ ] **Tests unchanged:** every planned test case matches the lines its red row recorded.
319
+ - [ ] **Unproven tests:** each planned test with no proven red is cleared only by a human-committed `TEST EXCEPTION` field.
320
+ - [ ] **Gate 2 — Verified:** every box above is checked.
316
321
 
317
322
  **Mandatory Tasks (Testing & Documentation):**
318
323
 
319
- - [ ] **Verify test coverage against Derived Test Matrix:** each row's test sits in one task's `DONE WHEN`.
320
- - [ ] **Sweep existing tests:** broken tests fixed; full suite green.
321
- - [ ] **Sweep new tests:** every task's `DONE WHEN` tests exist and pass.
322
- - [ ] **Verify observability:** errors logged and traced per `docs/observability.md`.
323
- - [ ] **Update documentation:** affected docs rewritten to match.
324
+ - [ ] **Verify test coverage against Derived Test Matrix:** each row's test is in one task's `DONE WHEN`.
325
+ - [ ] **Sweep existing tests:** broken tests are fixed, and the full suite passes.
326
+ - [ ] **Sweep new tests:** every test a task's `DONE WHEN` names exists and passes.
327
+ - [ ] **Verify observability:** errors are logged and traced as `docs/observability.md` describes.
328
+ - [ ] **Update documentation:** the affected docs are rewritten to match.
324
329
 
325
330
  ### 🔒 Gate 3: Testing & Documentation Check
326
331
 
327
- - [ ] **Docs updated:** every `Documentation Updates` row done; `.agents/docs.md` accurate.
328
- - [ ] **Gate 3 - Verified:** every box above checked.
332
+ - [ ] **Docs updated:** every `Documentation Updates` row is done.
333
+ - [ ] **Docs index accurate:** `.agents/docs.md` is accurate.
334
+ - [ ] **Gate 3 — Verified:** every box above is checked.
329
335
 
330
336
  ## Verification Plan
331
337
 
332
338
  ### Automated Tests
333
339
 
334
- - [ ] **Full Local Gate Suite:** deepest declared `bkit:gate:*` script and `bkit check` pass.
335
- - [ ] **Test Synchronization:** [Existing E2E tests (e.g. Playwright) to update alongside.]
336
- - [ ] **Build Configuration:** [Test-only files kept out of the production build (e.g. `tsconfig.json` `exclude`).]
337
- - [ ] **[Test Type] (`path/to/test.spec.ts`):** [Flows / unit / E2E additions and data hygiene needs.]
338
- - [ ] **Apply local migrations:** [New migrations applied locally (e.g. `pnpm db:reset`).]
339
- - [ ] **Run all tests:** [Local unit and integration suites (e.g. `pnpm test`, `pnpm test:integration`) pass.]
340
+ - [ ] **Full Local Gate Suite:** the deepest declared `bkit:gate:*` script and `bkit check` pass.
341
+ - [ ] **Test Synchronization:** [The existing E2E tests to update alongside.]
342
+ - [ ] **Build Configuration:** [How test-only files are kept out of the production build (e.g., the compiler config's exclude list).]
343
+ - [ ] **[Test Type] (`path/to/test.spec.ts`):** [The flow, unit or E2E additions, and their data hygiene needs.]
344
+ - [ ] **Apply local migrations:** [The new migrations applied locally (e.g., `pnpm db:reset`).]
345
+ - [ ] **Run all tests:** [The local unit and integration suites (e.g., `pnpm test`, `pnpm test:integration`) pass.]
340
346
 
341
347
  ### 🔒 Gate 4: Automated Verification Check
342
348
 
343
- - [ ] **Gate 4 - Verified:** every Automated Tests box checked, with proof (test output, CLI result, API response).
349
+ - [ ] **Gate 4 — Verified:** every Automated Tests box is checked, with proof (test output, a CLI result or an API response).
344
350
 
345
- ### 👤 Manual Verification
351
+ ### Manual Verification
346
352
 
347
353
  > [!CAUTION]
348
- > **Owner-run acceptance checks — advisory only.** An unticked box blocks nothing: not the merge, not plan approval. This is not a Gate 1 human-confirmation section.
354
+ > **Owner-run acceptance checks, advisory only.** An unticked box blocks nothing: not the merge, and not plan approval. This is not a Gate 1 human-confirmation section.
349
355
 
350
- - [ ] **Step 1:** [How to verify the feature end-to-end via CLI / DB.]
356
+ - [ ] **Step 1:** [How to verify the feature end to end through the CLI or the database.]
351
357
 
352
358
  <!-- bkit:end -->
@@ -6,7 +6,6 @@ import * as path from "node:path";
6
6
  import { spawnSync } from "node:child_process";
7
7
  import type { PreflightFinding } from "../before/index.js";
8
8
  import { readJsonFile } from "../../shared/json.js";
9
- import { readBkitConfig } from "../../shared/settings.js";
10
9
 
11
10
  // ---------------------------------------------------------------------------
12
11
  // Token-surface detectors
@@ -63,7 +62,7 @@ export function detectGhMcpToken(cwd: string): PreflightFinding | null {
63
62
  detect:
64
63
  "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
65
64
  action:
66
- "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
65
+ "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Cloud Agents / Codex Cloud) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
67
66
  };
68
67
  }
69
68
  if (status === "empty") {
@@ -108,51 +107,55 @@ export function detectGhSecret(secretName: string): TokenPresence {
108
107
  }
109
108
 
110
109
  /**
111
- * Build the consolidated "three locations to sync secrets" advisory. Fires when
112
- * the consumer's repo has bkit-cloud.yml installed OR a
113
- * .claude/ or .cursor/ install present — both indicate cloud-side agent use,
114
- * which means the same three secrets need to be set in three places (GitHub
115
- * Actions, Cursor Settings online, Claude app web).
110
+ * Build the consolidated cloud-secrets checklist advisory. Fires when the consumer's
111
+ * repo has bkit-cloud.yml installed OR a `.claude/`, `.cursor/` or `.codex/` install
112
+ * present — each indicates cloud-side agent use. Lists one location per trigger present:
113
+ * GitHub Actions for the router, plus each installed host's cloud dashboard with its
114
+ * generated paste doc. Never depends on the issue tracker: every host's env block is the
115
+ * same tracker-independent set (install/cloud-env.ts).
116
116
  *
117
- * Returns null when none of the three trigger paths exist.
117
+ * Returns null when none of the trigger paths exist.
118
118
  */
119
119
  export function buildCloudDashboardsAdvisory(cwd: string): PreflightFinding | null {
120
120
  const hasRouter = fs.existsSync(path.join(cwd, ".github", "workflows", "bkit-cloud.yml"));
121
- const hasClaude = fs.existsSync(path.join(cwd, ".claude"));
122
- const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
123
- if (!hasRouter && !hasClaude && !hasCursor) return null;
124
-
125
- // cloud=claude path (bkit-cloud.yml): GitHub-tracker only, ANTHROPIC_API_KEY or federation.
126
- // cloud=cursor path (.cursor/): BKIT_LINEAR_API_KEY for Cursor dashboard; Linear-tracker only.
127
- // Distinguish by recorded variant; fall back to presence-based detection under linear.
128
- const config = readBkitConfig(cwd);
129
- const isCursorCloud =
130
- config.cloudAgents === "cursor" ||
131
- (!hasRouter && hasCursor && config.issueTracker === "linear");
132
-
133
- const secretList = isCursorCloud ? "`BKIT_LINEAR_API_KEY`" : "`ANTHROPIC_API_KEY`";
134
- const ghSetLines = isCursorCloud
135
- ? " gh secret set BKIT_LINEAR_API_KEY --body='<value>'\n\n" +
136
- " Verify: `gh secret list | grep -E 'BKIT_LINEAR_API_KEY'`\n\n"
137
- : " gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
138
- " Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n" +
139
- " Keyless alternative for bkit-cloud.yml (workload identity federation): leave the secret unset and set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (`gh variable set`) from a Claude Console federation rule.\n\n";
140
- const vendorNote = isCursorCloud
141
- ? "BKIT_LINEAR_API_KEY is read from the Linear dashboard (https://linear.app/settings/api)."
142
- : "ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.";
121
+ const hosts: Array<[string, string]> = [
122
+ [
123
+ ".cursor",
124
+ "**Cursor Cloud Agents**: open `https://cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab. Add each secret as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript). Cursor reads `.cursor/Dockerfile` + `.cursor/environment.json` from the repo but secrets come from this dashboard only; the resolved paste-ready values are in `.cursor/bkit-cloud.md` (gitignored).",
125
+ ],
126
+ [
127
+ ".claude",
128
+ "**Claude Code (web)**: open `https://claude.ai/code` → environment selector → your environment → **Environment variables**. Paste the block from `.claude/bkit-cloud.md` (gitignored), which also carries the setup script and network list. Claude reads both from the dashboard, NOT from the repo, so changes here do not require a commit.",
129
+ ],
130
+ [
131
+ ".codex",
132
+ "**Codex Cloud**: open ChatGPT → **Settings > Codex Cloud > Environments** → your environment → **Environment variables**. Paste the block from `.codex/bkit-cloud.md` (gitignored), which also carries the install script and allowed domains.",
133
+ ],
134
+ ];
135
+ const present = hosts.filter(([dir]) => fs.existsSync(path.join(cwd, dir)));
136
+ if (!hasRouter && present.length === 0) return null;
137
+
138
+ const sections: string[] = [];
139
+ if (hasRouter) {
140
+ sections.push(
141
+ "**GitHub Actions** (used by bkit-cloud.yml and your own workflows):\n" +
142
+ " gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
143
+ " Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n" +
144
+ " Keyless alternative for bkit-cloud.yml (workload identity federation): leave the secret unset and set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (`gh variable set`) from a Claude Console federation rule.\n\n" +
145
+ " ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.",
146
+ );
147
+ }
148
+ for (const [, text] of present) sections.push(text);
143
149
  return {
144
150
  id: "cloud-secrets-three-locations",
145
151
  severity: "advisory",
146
- detect: `The secrets used by bkit's cloud integration (${secretList}) must also be set in the relevant cloud dashboards. Bkit cannot verify dashboard state — surface the checklist so you don't ship a half-configured cloud setup.`,
152
+ detect:
153
+ "The secrets bkit's cloud integration uses must also be set in each cloud location you use. Bkit cannot verify dashboard state — surface the checklist so you don't ship a half-configured cloud setup.",
147
154
  action:
148
155
  "Set each secret in the required locations:\n\n" +
149
- "1. **GitHub Actions** (used by bkit-cloud.yml and your own workflows):\n" +
150
- ghSetLines +
151
- "2. **Cursor Cloud Agents** (used by Cursor's cloud agent runner): open `https://cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab. Add each secret as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript). Cursor reads `.cursor/Dockerfile` + `.cursor/environment.json` from the repo but secrets come from this dashboard only; the resolved paste-ready values are in `.cursor/bkit-cloud.md` (gitignored).\n\n" +
152
- "3. **Claude Code (web)** (used by Claude.ai's cloud agent runner): open `https://claude.ai/code` → Settings → Setup → Environment Variables. Add each secret. Claude reads its setup script from the dashboard, NOT from the repo, so changes here do not require a commit.\n\n" +
156
+ sections.map((s, i) => `${i + 1}. ${s}\n\n`).join("") +
153
157
  "**Context-fetch (`/bkit-debug` in the cloud):** if you run the debug workflow in these cloud agents, the observability creds your `.agents/context.md` context-fetch blocks use (e.g. `VERCEL_TOKEN`, `SUPABASE_ACCESS_TOKEN`) must ALSO be set in the same dashboards above — non-interactively, since headless agents cannot `vercel login`. These are operator/observability READ creds, not app-runtime secrets. Commit the non-secret selectors (team scope / project ref / `--environment`) in your copied block so they need no dashboard entry. The CLIs those blocks call install automatically in the cloud from each block's `context-fetch:provision` sibling — no manual setup.\n\n" +
154
- "Same VALUE in all places. " +
155
- vendorNote,
158
+ "Same VALUE in all places.",
156
159
  };
157
160
  }
158
161