@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,82 +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.
11
- >
12
- > **Rules:**
13
- >
14
- > - Any tools mentioned below are examples only; swap for actual tools in final output; drop inapplicable.
15
- > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
16
- > - Read `.agents/docs.md` → load docs for workflow / step / task; skip missing; cite docs inline where required.
17
- > - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
18
- > - Source of truth: literal `[x]` vs `[ ]` checkboxes in this document; `[ ]` means not DONE regardless of context.
10
+ > **Purpose:** The implementation plan: pre-flight checks, gates, the runbook, verification and rollback.
19
11
 
20
12
  ## Context & Goals
21
13
 
22
- [High-level overview of problem/feature and why it is necessary; initially set to `PENDING`.]
23
-
24
- > Success criteria once in `Acceptance Scenario → Success Criteria`; each runbook task has own `Done when`. Do not restate success list here.
14
+ [The problem or feature, and why it is needed. Initially set to `PENDING`.]
25
15
 
26
16
  **Related Issues:**
27
17
 
28
- - [Issue references from plan input (linked/referenced in issue text). Tracker refs only (e.g. `#N — title (state)`); not full content. Dedupe/scope-awareness; not scope mandate. None → `None`. Workflow fetch-context step runs fresh tracker search for reviewers, not this section.]
18
+ - [One `#N — title (state)` line per related issue. **If** none → `None`. Initially set to `PENDING`.]
29
19
 
30
20
  ---
31
21
 
32
22
  ## 👤 ⚠️ Acceptance Scenario
33
23
 
34
24
  > [!CAUTION]
35
- > **🛑 HUMAN must READ and CONFIRM this SECTION.**
36
- > 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.
37
27
  >
38
- > **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). Agent handles rest.
39
-
40
- ### Spec
41
-
42
- > [!IMPORTANT]
43
- > What good looks like; canonical for the plan phase. Subagents (plan generate, plan review, plan summary) must follow this spec. No plan subagent restates rules; this section = single source of truth for the plan.
44
-
45
- - **Narrative:** 1–2 sentences, user POV (not system POV). User action + what they get back. Source, first that carries it wins: design `## Acceptance Scenario` → verbatim; issue `Narrative` (change shape, `.bkit/trackers.md` § Issue shapes) → verbatim; audits only (`docs/audits/`) → user/operator impact from in-scope findings. None → both fields = `⚠️ MISSING: no design doc, no issue Narrative and no audit report — human must provide before plan proceeds`; never fabricate; Gate 1 blocked until human fills.
46
- - **Success Criteria:** <=5 bullets, measurable / testable. Outcomes (e.g. "user sees their event in the list within 2s"), not steps (e.g. "call API, render component"). Design count ≠ 5 → smallest set proving feature. Design → verbatim. No design → issue `Success Criteria` verbatim. Audits only → one bullet per in-scope finding id from `Expected`; no 5-bullet cap.
47
- - **Process Sketch:** Design → plan inherits/refines. same happy-path (`Concrete Example`) + branches (`Edge Cases`) as `WHEN X → THEN Y` (3–7 lines); reuse exact examples, do not invent. Outcomes, not steps.
48
- - **Key Edge Cases:** Design → plan inherits. Concurrency, conflicts, failures, cross-feature — not trivial validation (plan adds that).
49
- - **Edge Cases:** Plan phase — design Key Edge Cases verbatim (no design → issue `Edge Cases` rows verbatim) + validation / error / boundary cases.
50
- - **Concrete Example:** Plan phase only. Role, starting state, numbered steps, observable outcome. One scenario, not a list.
51
- - **Derived Test Matrix:** Plan phase only. One row per testable behaviour → exactly one `Agent Execution Runbook` task. No row without a target file. In-scope audit behaviour → one row. Issue `Derived Test Matrix` rows → kept verbatim; add missing rows.
28
+ > **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). The agent handles the rest.
52
29
 
53
30
  ### Narrative
54
31
 
55
- > Inherited from design, else the issue; do not rewrite.
56
-
57
- [Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Narrative. No design → per Spec above; 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`.]
58
33
 
59
34
  ### Success Criteria
60
35
 
61
- > Inherited from design, else the issue; do not rewrite.
62
-
63
- [Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Success Criteria. No design → per Spec above; initially set to `PENDING`.]
36
+ [Up to 5 measurable outcomes. Initially set to `PENDING`.]
64
37
 
65
38
  ### Process Sketch
66
39
 
67
- > Inherited from design; plan may refine. `Concrete Example` (happy path) + `Edge Cases` (branches) as `WHEN X → THEN Y`, not prose — same examples. Do not invent new examples. Sense-check top-level process HERE without prose below. Outcomes, not implementation steps.
68
-
69
- - **WHEN** [trigger / user action] **→ THEN** [observable outcome]
70
- - **WHEN** [next step] **→ THEN** [outcome]
71
- - **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]
72
43
 
73
- _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.
74
45
 
75
46
  ### Concrete Example
76
47
 
77
- > Plan expands from design.
78
-
79
- **Setup:** [User role, existing state, context]
48
+ **Setup:** [The user's role, the existing state and the context]
80
49
 
81
50
  **Steps:**
82
51
 
@@ -84,398 +53,306 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
84
53
  2. User [does X] → System [responds with Y]
85
54
  3. …
86
55
 
87
- **Outcome:** [End state the user sees that proves success]
56
+ **Outcome:** [The end state the user sees that proves success]
88
57
 
89
58
  ### Edge Cases
90
59
 
91
- > Plan expands from design's Key Edge Cases.
92
-
93
60
  <!-- prettier-ignore -->
94
61
  | Scenario | Expected Behavior |
95
62
  | --- | --- |
96
- | [Inherited from design Key Edge Cases and plan-added cases] | [Specific behavior] |
97
- | [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] |
98
65
 
99
66
  ### Derived Test Matrix
100
67
 
101
- > Each row → one Agent Execution Runbook task. Assign tier(s) via **tier-selection rubric** in `docs/testing.md` (behaviour may need more than one). Boundary rows use that doc's rigor — reach real boundary, assert ground-truth signal, `@live` for external / deployed boundaries; do not restate those rules here.
102
- >
103
- > **Discrimination (no false-green):** assertion MUST hit the **affected** surface and FAIL if behaviour broken — not transport status (200/201), not proxy surfaces, never mock away the boundary under test.
104
-
105
- **Tier Key** — use these exact tier names in the `Type` column (they must match `docs/testing.md`); pick the **lowest tier that actually exercises** the behaviour (a behaviour may need several):
106
-
107
- <!-- prettier-ignore -->
108
- | Tier | Use for | Example behaviour |
109
- | --- | --- | --- |
110
- | **Static** | every change — type / lint / format / prose / drift (global gate, not a per-feature row) | `tsc`, lint, and `bkit check` pass on the changed files |
111
- | **Unit** | pure function / single module, no I/O | service parses a payload correctly |
112
- | **Integration** | crosses a LOCAL stateful boundary (own DB / API), no mocks at the boundary, fresh instance | API endpoint enforces tenant isolation against a fresh local instance |
113
- | **@live (golden)** | crosses an EXTERNAL / DEPLOYED boundary (3rd-party API, model, payment, deployed schema, RLS) — reach it, assert a ground-truth signal | a real 3rd-party API returns content and a boundary-only identity |
114
- | **E2E** | user-visible UI flow / DOM state | user creates an event and sees it in the list |
115
- | **fresh-DB replay** | new / changed migration or seed (`bkit-tests-migration`) | migration replays from empty and the seed loads |
116
- | **Smoke** | post-deploy health of a deployed surface (global observability gate) | deployed health route returns 200 |
117
-
118
- One row per behaviour (copy the tier name from the key above verbatim into `Type`):
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.
119
69
 
120
70
  <!-- prettier-ignore -->
121
- | Test description | Type | Target file |
122
- | --- | --- | --- |
123
- | [e.g., Happy path: user creates event, sees it in list] | E2E | [e.g. `apps/web/e2e/[feature].spec.ts`] |
124
- | [e.g., Service correctly parses payload] | Unit | [e.g. `packages/[pkg]/[module].test.ts`] |
125
- | [e.g., API endpoint enforces tenant isolation] | Integration | [e.g. `packages/api/[feature].integration.test.ts`] |
126
- | [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`] |
127
- | [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 |
128
78
 
129
79
  ### 👤 ✅ Human Confirmation
130
80
 
131
81
  - [ ] **Acceptance Scenario confirmed:** I have reviewed the Narrative, Success Criteria, Process Sketch, Concrete Example, Edge Cases, and Derived Test Matrix above. They correctly describe what "done" looks like.
132
82
 
133
- > [!CAUTION]
134
- > **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
135
-
136
83
  ---
137
84
 
138
85
  ## 👤 ⚠️ Breaking Changes & Naming Review
139
86
 
140
87
  > [!CAUTION]
141
- > **🛑 HUMAN must READ and CONFIRM this SECTION.**
142
- > Review proposed names and breaking changes below.
88
+ > 🛑 The owner reads and confirms this section.
143
89
 
144
- [Proposed names: pages, files, DB tables, routes, API contracts. Breaking changes, DB structure diffs, global layout changes. Use IMPORTANT/WARNING/CAUTION alerts. If none, write "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`.]
145
91
 
146
92
  ### 👤 ✅ Human Confirmation
147
93
 
148
- - [ ] **Breaking Changes confirmed:** I have reviewed all breaking changes and naming decisions above.
149
-
150
- > [!CAUTION]
151
- > **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
94
+ - [ ] **Breaking Changes confirmed:** I have reviewed every breaking change and naming decision above.
152
95
 
153
96
  ---
154
97
 
155
98
  ## 👤 ⚠️ Open Questions & Assumptions
156
99
 
157
100
  > [!CAUTION]
158
- > **🛑 HUMAN must READ and CONFIRM this SECTION.**
159
- > Unknowns + assumptions this plan relies on. Unresolved question = risk; wrong assumption breaks downstream. If none, write "None".
160
- > **Never a bare question.** Each carries 2-3 options, a recommendation, and default if unanswered — human must decide from the page alone. Canonical plan shape.
161
- > Design → carry its options / recommendation forward where already answered.
162
-
163
- - **Assumption:** [what the plan takes as given] → [what breaks if it's wrong]
164
- - **Open Question:** [decision needed] → [who / how to resolve]
165
- - **Options:** A — [option, trade-off] · B — [option, trade-off] · C — [option, trade-off, optional]
166
- - **Recommended:** [A] — [why, 1 line]
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`.
103
+
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]
167
108
  - **Default if unanswered:** [what the agent proceeds with]
168
109
 
169
110
  ### 👤 ✅ Human Confirmation
170
111
 
171
112
  - [ ] **Open Questions & Assumptions confirmed:** I have resolved or explicitly accepted every open question and assumption above.
172
113
 
173
- > [!CAUTION]
174
- > **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
175
-
176
114
  ---
177
115
 
178
116
  ## Alternative Approaches & Recommendations
179
117
 
180
- [Document rejected paths and why. List future phase recommendations; initially set to `PENDING`.]
181
-
182
- **Selection Rule:** pick the approach with the best quality-of-end-state, not the smallest diff / lowest cost-of-change. In-scope work = complete or explicitly moved to `Out of Scope` — no 90% solutions or silent shortcuts.
118
+ [The paths rejected and why, and recommendations for a future phase. Initially set to `PENDING`.]
183
119
 
184
120
  ## Out of Scope
185
121
 
186
- [Features / fixes excluded to prevent scope creep. Every exclusion is `Exempt` per the rule below, with a reason and a home. If none, write "None"; initially set to `PENDING`.]
122
+ [Each excluded item, marked `Exempt`. **If** none → `None`. Initially set to `PENDING`.]
187
123
 
188
124
  <!-- prettier-ignore -->
189
125
  | Excluded item | Why `Exempt` | Where it belongs |
190
126
  | --- | --- | --- |
191
- | [feature/fix] | [why genuinely-additive] | [design non-goal / follow-up #N / future phase] |
192
-
193
- > [!CAUTION]
194
- > **Default = in-scope.** `Exempt` only if genuinely-additive — not required by `Success Criteria`, `Acceptance Scenario` / `Derived Test Matrix` row, or design (non-goals excepted). Required items → runbook task, never deferral; parking here = `Blocking` deferral → plan review / scope-check pulls back. Mirror each `Exempt` row in `docs/deferrals.jsonl`. Audit `LOW` → `Exempt` rows here.
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] |
195
129
 
196
130
  ## Suggested Scope Expansion
197
131
 
198
- [Prior work overlapping this plan's surfaces — related open issues, `docs/deferrals.jsonl` deferrals, `docs/failures.jsonl` failures, audit findings the input did not name — surfaced as candidate expansions for the human. Fold `docs/deferrals.jsonl` and `docs/failures.jsonl` ledgers by `key`, highest `ts` wins → read only winning rows where `status` is not `CLOSED`; never read any other rows. If none, write "None"; initially set to `PENDING`.]
132
+ [The candidates that overlap this plan's surfaces. **If** none → `None`. Initially set to `PENDING`.]
199
133
 
200
134
  <!-- prettier-ignore -->
201
135
  | Candidate | Source | Overlaps | Recommendation |
202
136
  | --- | --- | --- | --- |
203
- | [what it is] | [`#N` / `docs/deferrals.jsonl` / `docs/failures.jsonl` / audit finding id] | [surface / task it touches] | [fold in / keep deferred / needs design decision] |
204
-
205
- > [!CAUTION]
206
- > **Candidates, not scope.** Human review only — not runbook tasks, must not expand scope. Fold in only on design scope or explicit human decision → becomes task, leaves list.
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] |
207
138
 
208
139
  ## Security & Privacy
209
140
 
210
- > Reference: `docs/security.md`. Check all that apply; skip inapplicable rows.
211
-
212
- - [ ] **New API Route** — auth guard applied (e.g. a `requireMember`-style check)? Rate-limited if auth-adjacent?
213
- - [ ] **New DB Table/Column** — row / tenant access policy deny-by-default (e.g. RLS)? Tenant-scoped (e.g. via a membership join)?
214
- - [ ] **Role-Gated Mutation** — role checked at the API layer (not data-layer policy alone)?
215
- - [ ] **User Input** — validated by a schema (e.g. Zod) with `parse()` called in the handler?
216
- - [ ] **PII** — absent from logs? Audit/CDC trigger updated if a new column lands on a monitored table?
217
- - [ ] **Redirect URL** — validated against an allow-list?
218
- - [ ] **Webhook** — signature verified? Secret declared in the env schema?
219
- - [ ] **New Secret/Env Var** — added to the env schema? Stored in the project's secret manager (e.g. GCP Secret Manager / Vercel env)?
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.
220
149
 
221
- _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."]
222
151
 
223
152
  ## Pre-Flight / Dependencies
224
153
 
225
- **CRITICAL:** Check off all core items. Check conditional items only when applicable. Abort if anything required is missing.
226
-
227
154
  ### Core
228
155
 
229
- Always verify.
230
-
231
- - [ ] **Package Management:** Required packages declared; dependency manifest + lockfile in sync (e.g. `package.json` + `pnpm-lock.yaml`, `pyproject.toml` + `uv.lock`).
232
- - [ ] **Dependency Versions:** Run `pnpm bkit:deps:outdated`; spot-check toolchain + stack CLI versions (e.g. `npx tsc --version`, `pnpm --version`, `npx supabase --version`). Flag outdated deps that may silently block implementation — infra errors often = CLI vs backend version mismatch.
233
- - [ ] **Existing-Solution Search (reuse over duplicate):** per capability, three sweeps → `Reuse Inventory`: in-repo (text search for names / strings / near-miss helpers / sibling modules; symbol references via language server when configured; `docs/capabilities.md` when present), dependency (`{framework} {capability} built-in`), ecosystem (`{problem} best practice {current year}`). Empty language-server / capability-map result = inconclusive — absence needs text search. Unrecorded = unsearched. Drives `[MODIFY]` vs `[NEW]`.
234
- - [ ] **User Context:** Verify read / write access to required files. Request missing user information up front.
235
- - [ ] **Project Context:** Fold `docs/knowledge.jsonl` and `docs/decisions.jsonl` each by `key`, highest `ts` wins → read only winning rows where `status` is `ACTIVE` or absent; never read any other rows. Check for relevant patterns, decisions, gotchas.
236
- - [ ] **Testing & Quality:** Ensure testing strategy aligns with `docs/testing.md`.
237
- - [ ] **Prerequisite Plans:** List `docs/plans/...` plans that must be fully executed and verified before this one.
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`.]
238
163
 
239
164
  ### Conditional
240
165
 
241
- Verify only when applicable.
242
-
243
- - [ ] **Secrets & Env Vars:** New API keys or third-party credentials → verify the project's secret store (e.g. GCP Secret Manager, Vercel env vars) and any service-account / IAM roles.
244
- - [ ] **Schema State:** Any DB reads or writes → confirm exact database state against `docs/data-schema.md` before finalizing data-access logic.
245
- - [ ] **Architecture & UI:** New files / routes / UI → `docs/architecture.md` topology; UI/mobile → `docs/design.md`; consult named reference repos.
246
- - [ ] **Observability:** New logs / audit tables / traces → align with `docs/observability.md` (e.g. structured logger calls, correlation IDs, CDC / OTel).
247
- - [ ] **Notifications:** Alerts / toasts → notifications doc via `.agents/docs.md` for tier (e.g. 1=inline, 2=toast, 3=bell).
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.
248
171
 
249
172
  ### 🔒 Gate 1: Prerequisites Check
250
173
 
251
- **CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all applicable boxes above. **do not stop for user permission.** Proceed to `Data Schema Integration`.
252
-
253
- - [ ] **Acceptance Scenario confirmed:** Human confirmed `👤 Acceptance Scenario` section (checkbox is `[x]`).
254
- - [ ] **Breaking Changes confirmed:** Human confirmed `⚠️ Breaking Changes & Naming Review` section (checkbox is `[x]`).
255
- - [ ] **Open Questions confirmed:** Human confirmed `👤 Open Questions & Assumptions` section (checkbox is `[x]`).
256
- - [ ] **Security & Privacy checked:** All applicable `Security & Privacy` rows verified (or "None" justified).
257
- - [ ] **Reuse Inventory complete:** every capability has a row with non-empty `Search performed` + `Decision`; every `NEW` cites an allowed reason.
258
- - [ ] **Gate 1 - Verified:** All Core items checked. All 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.
259
181
 
260
182
  ## Data Schema Integration
261
183
 
262
- [Define how this feature interacts with the existing database schema and what changes are required; initially set to `PENDING`.]
263
-
264
- **Invariant Conformance:** Multi-store or privileged writes → every mutation path maintains every store a read surface depends on, under a compatible privilege, with the returned error actually checked (never swallowed). If a write can fail on privilege/constraint, the plan says how that failure surfaces — not a silent 200.
184
+ [How this feature uses the existing schema, and what changes. Initially set to `PENDING`.]
265
185
 
266
186
  ### Data Schema Usage
267
187
 
268
- [List all existing `docs/data-schema.md` tables and fields that this feature will read from (Input) or write to (Output); 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`.]
269
189
 
270
- - **Input (Read):** `users.id`, `items.title`
271
- - **Output (Write):** `items.status`, `job_audits.log`]
272
- If no existing fields are used, explicitly state "None".
190
+ - [e.g., **Input (Read):** `users.id`, `items.title`]
191
+ - [e.g., **Output (Write):** `items.status`, `job_audits.log`]
273
192
 
274
193
  ### Data Schema Changes
275
194
 
276
- [List any new tables, new fields, or modifications to existing fields that need to be recorded in `docs/data-schema.md`; 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`.]
277
196
 
278
- - **ADD:** `items.new_field` (type: text)
279
- - **MODIFY:** `users.role` (added enum value)]
280
- If no schema changes are required, explicitly state "None".
197
+ - [e.g., **ADD:** `items.new_field` (type: text)]
198
+ - [e.g., **MODIFY:** `users.role` (added enum value)]
281
199
 
282
200
  ## Reuse Inventory
283
201
 
284
- [One row per capability plan introduces, including those search cleared as absent. Author before `Architecture & Component Changes`. No capability → no rows; "None" never substitutes for searching. Design `Reuse & Prior Art` verdicts = starting point; every row still records its own `Search performed`; initially set to `PENDING`.]
202
+ [One row per capability the plan introduces. Initially set to `PENDING`.]
285
203
 
286
204
  <!-- prettier-ignore -->
287
- | Capability | Search performed | Existing candidates | Decision | Justification |
288
- | --- | --- | --- | --- | --- |
289
- | [what the plan must do] | `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] |
290
- | [capability] | [exact commands / queries run] | None — [what was searched] | new | [reason (a)/(b)/(c)] |
291
-
292
- > [!CAUTION]
293
- > **Default = `EXTEND`.** `NEW` only allowed for:
294
- > (a) no candidate — `Search performed` shows the commands establishing absence;
295
- > (b) extending breaks the candidate's contract or callers — name both;
296
- > (c) candidate is a `Supersession Inventory` `DELETE` — replacement, not duplicate.
297
- >
298
- > never accept cleaner-fresh / messy-existing / close-but-different as a `NEW` reason — messy candidate → extend and clean it, in scope. Empty `Search performed` = UNSEARCHED, not `NEW`-eligible.
299
- >
300
- > Each `EXTEND` row must land as `[MODIFY] path/to/existing` in `Architecture & Component Changes` and a task in `Agent Execution Runbook`; each `NEW` row as `[NEW]` carrying the same reason. `[NEW]` with no row = unjustified.
205
+ | Capability | File | Search performed | Existing candidates | Decision | Justification |
206
+ | --- | --- | --- | --- | --- | --- |
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)] |
301
210
 
302
211
  ## Architecture & Component Changes
303
212
 
304
- [Group files logically (DB, API, Backend, Frontend, Cron, Observability). Separate by headers; initially set to `PENDING`.]
305
- **CRITICAL:** Justify new file locations per `docs/architecture.md` topology.
306
- **CRITICAL:** Prefer `[MODIFY]` over `[NEW]`. Every `[NEW]` must trace to a `Reuse Inventory` `NEW` row and carry its reason — no parallel reimplementation. Superseded → `Supersession Inventory` as `DELETE`.
307
- **CRITICAL:** Frontend/Mobile → adhere to `docs/design.md`.
308
- **CRITICAL:** Verify `[MODIFY]` files exist (else `[NEW]`). Before changing exported symbol/signature/contract: find callers/importers/schemas/consumers (language-server references when configured + text search), list blast radius.
309
- **CRITICAL:** Include backend actions for new schema validations (e.g. Zod `schema.parse`).
310
- **CRITICAL:** NEVER weaken gate to pass: no type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), deleted assertions, empty `catch` / error-swallowing, mocking-away unit under test. Fix root causes; per-file opt-out needs explicit human sign-off.
311
- **CRITICAL:** Auto-capture (e.g. log drains / CDC) does not replace explicit logging — log edge cases escaping auto-capture with the project's structured logger (e.g. `console.error("[Context] Message", payload)`). See `docs/observability.md` for naming, severity, correlation IDs, label taxonomy.
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`.]
312
215
 
313
216
  ### Database Migrations
314
217
 
315
- [Define new tables / columns / access policies (e.g. RLS) with your migration tool (e.g. `db:diff`). **NEVER apply to shared remotes by hand** (e.g. `db push` to Dev/Main) — CI's migration lane applies them; see `docs/deployments.md` § Applying migrations at deploy time; initially set to `PENDING`.]
316
-
317
- > [!WARNING]
318
- > **If adding/removing columns on CDC/audit-monitored tables (e.g. `users` and the other tenant tables your project monitors):**
319
- >
320
- > 1. Update the monitored-column allow-list in the schema-assurance test (e.g. a `knownSafeColumns` list).
321
- > 2. If a column contains PII → update the audit trigger to scrub it.
322
- > 3. See `docs/data-schema.md` for the full checklist.
218
+ [The new tables, columns and access policies (e.g., row-level policies), and the migration that adds them. Initially set to `PENDING`.]
323
219
 
324
220
  ### [Component Area 1]
325
221
 
326
- [Summary of component changes; initially set to `PENDING`.]
222
+ [A summary of the component changes. Initially set to `PENDING`.]
327
223
 
328
224
  #### [MODIFY] `path/to/file.ext`
329
225
 
330
- - **Existence Check:** [Verify file exists first.]
331
- - [Detail logic, schema, or API contracts.]
226
+ - **Existence Check:** [the file exists]
227
+ - [The logic, schema or API contract changes.]
332
228
 
333
229
  #### [new] `path/to/file.ext`
334
230
 
335
- - **Reuse Check:** [`Reuse Inventory` row + reason (a)/(b)/(c) — why no existing artifact can be evolved.]
336
- - [Detail 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.]
337
233
 
338
234
  #### [DELETE] `path/to/file.ext`
339
235
 
340
- - [Reason]
236
+ - [The reason]
341
237
 
342
238
  ### Cron Jobs & Scheduled Tasks
343
239
 
344
- [Define scheduled tasks (e.g. Vercel cron, pg_cron, Inngest). Record them in the project's cron/scheduled-jobs doc if it has one (resolve via `.agents/docs.md`); 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`.]
345
241
 
346
242
  ## Supersession Inventory
347
243
 
348
- [Existing artifacts the new code replaces — shared triggers/routes, redundant exports, etc. If plan adds without replacing, write "None"; initially set to `PENDING`.]
244
+ [The existing artifacts the new code replaces. **If** none → `None`. Initially set to `PENDING`.]
349
245
 
350
246
  <!-- prettier-ignore -->
351
247
  | Existing artifact | Replaced by | Decision | Justification |
352
248
  | --- | --- | --- | --- |
353
- | `path/to/old-thing` | `path/to/new-thing` | DELETE | [reason] |
354
-
355
- > [!CAUTION]
356
- > **Default = `DELETE`.** `RETAIN-WITH-REASON` only allowed for:
357
- > (a) external contract — atomic migration impossible (third-party callers, public API);
358
- > (b) staged rollout with kill-date and follow-up issue link.
359
- >
360
- > never accept `@deprecated` and still exported as a resolution. Each `DELETE` row must be mirrored as `[DELETE] path/to/file` in `Architecture & Component Changes` and as a removal task in `Agent Execution Runbook`.
249
+ | `path/to/old-thing` | `path/to/new-thing` | DELETE | [the reason] |
361
250
 
362
251
  ## Documentation Updates
363
252
 
364
- > Docs this change touches only; delete rest. Core below; others via `.agents/docs.md`. Code-change treatment — rewrite prose, no lazy bullet appends.
253
+ [One row per doc this change touches. Find any doc not listed here through `.agents/docs.md`.]
365
254
 
366
255
  <!-- prettier-ignore -->
367
256
  | Doc | Change required |
368
257
  | --- | --- |
369
- | `docs/knowledge.jsonl` | [learnings, gotchas] |
258
+ | `docs/knowledge.jsonl` | [learnings and gotchas] |
370
259
  | `docs/decisions.jsonl` | [architecture decisions] |
371
- | `docs/architecture.md` | [topology / component changes] |
372
- | `docs/technology.md` | [frameworks, libraries, conventions] |
373
- | `docs/data-schema.md` | [new tables / columns] |
374
- | `docs/design.md` | [palette, typography, components] |
375
- | `docs/testing.md` | [new test files / patterns] |
376
- | `docs/observability.md` | [new log names / spans] |
377
-
378
- _Delete rows with no change; add a row per other affected doc (resolve via `.agents/docs.md`)._
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] |
379
266
 
380
267
  ## Rollback Strategy
381
268
 
382
269
  <!-- prettier-ignore -->
383
270
  | Axis | Action | Notes |
384
271
  | --- | --- | --- |
385
- | **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 |
386
- | **Code** | [Git revert SHA or feature flag to disable] | `git revert {COMMIT}` |
387
- | **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"] |
388
275
 
389
- _No DB changes: "Code-only — `git revert` sufficient."_
276
+ [**If** there are no DB changes → write "Code-only — `git revert` sufficient."]
390
277
 
391
278
  ## Agent Execution Runbook
392
279
 
393
- [Chronological, step-by-step checklist guiding implementation. **MANDATORY**; initially set to `PENDING`.]
394
-
395
- > [!IMPORTANT]
396
- > **Continuous Execution:** Run runbook autonomously; no user permission at Gates; `[x]` as you go.
397
- > **Step Isolation:** Finish task (verify + checkbox) before next.
398
- > **Integration Shape:** may suggest PR / commit / sequencing — advisory, never a gate; one PR for all tasks always OK. Do not specify merge method.
280
+ [A chronological task checklist. Initially set to `PENDING`.]
399
281
 
400
282
  **Implementation Tasks (Examples):**
401
283
 
402
- > Every task MUST include `**Done when:**` — terse, testable, codebase-verifiable (file exists / signature matches / test passes / behaviour observable). Plan-verify asserts before `[x]`. No task without `Done when:`. One task per in-scope audit finding id; group only on one shared root cause in report — every id still named.
403
- >
404
- > **Tests ship with their task.** Task adding / changing logic → names its own unit tests in `Done when`, matrix row or not; tests it breaks → fixed in same task. never defer task tests to later tasks to avoid splits that leave untested code and drop coverage gates.
405
- >
406
- > **Build order and test source.** Order tasks by build dependency (schema → API → UI). Behaviour tests only from `Derived Test Matrix` rows — do not invent. Boundary-crossing tasks (DB / API / model / network / migration) carry paired non-mock `Done when` tests; pure-function tasks exempt from pairing, not from unit tests.
407
- >
408
- > **Test first.** Every task MUST include `**Test first:**` after `Done when`. Behaviour change at unit / integration tier → one or more tests, `;`-separated, each `` `{test file}` `` `` `{test name}` `` fails on {assertion} — repo-relative test files, test names as the runner reports them or their last segments, no `;` in assertion text; build sees each fail against stubs before writing the task's code. No behaviour change (docs, config, pure refactor) or E2E / `@live` tier only → `n/a — {reason naming which}`.
409
- >
410
- > **Issue tasks.** Change-shape issue (`.bkit/trackers.md` § Issue shapes) → its `Tasks` lines are the starting runbook; keep each `Done when` / `Test first` (tighten, never weaken); renumber in build order.
284
+ <!-- bkit:group 1 start -->
411
285
 
412
- - [ ] **Task 1:** [e.g., Create DB migration (`npx supabase db diff`)]. **Done when:** [e.g., `supabase/migrations/{timestamp}_add_items_status.sql` exists; `npx supabase db push --local` applies cleanly]. **Test first:** [e.g., n/a — migration; fresh-DB replay tier].
413
- - [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes]. **Test first:** [e.g., `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on the thrown validation error — stub accepts any status; `packages/api/items.integration.test.ts` `persists the new status` fails on the stored row — stub writes nothing].
414
- - [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state]. **Test first:** [e.g., n/a — E2E tier only; runs in CI].
286
+ ### TASK GROUP 1: [e.g., Item status in the API]
415
287
 
416
- ### 🔒 Gate 2: Code Implementation Check
288
+ <!-- bkit:task 1 start -->
417
289
 
418
- **CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Testing & Documentation`.
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]
419
294
 
420
- - [ ] **No bolt-on / no gate-weakening:** every `[NEW]` traces to a `Reuse Inventory` `NEW` row and its search still holds — reusable artifact found mid-build → add a row, fold code into it; every `EXTEND` landed as a modification of the named artifact, not a parallel file. No type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), empty `catch` / error-swallowing introduced to make a gate pass.
421
- - [ ] **Test first:** every task naming `Test first` tests recorded a red per test before its code; tests unchanged since except added tests / formatting.
422
- - [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off against the plan.
295
+ <!-- bkit:task 1 end -->
423
296
 
424
- > [!IMPORTANT]
425
- > **Testing Strategy** (see `docs/testing.md`):
426
- >
427
- > - **Backend / pipeline logic** — test at the unit/integration tier (e.g. Vitest), not through a browser. Mock HTTP and assert against the real datastore natively.
428
- > - **End-to-end integration** — core data paths need at least 1 integration test firing the real API against a local DB _without_ ORM/DB mocking.
429
- > - **UI E2E (browser or device) for UI only** (e.g. Playwright) — don't drive a UI for non-visual logic.
430
- >
431
- > **UI E2E Conventions** — test-auth + data-factory per `docs/testing.md`: shared `setup` logs in once, reuses auth state (sign-in / sign-up / account-deletion tests opt out); typed factories with per-test overrides, not inline strings.
297
+ <!-- bkit:task 2 start -->
298
+
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]
301
+ - **READ:** `ItemStatus` in `packages/api/src/items/schema.ts`: [e.g., the allowed statuses]
302
+ - **DEPENDS ON:** 1
303
+ - **DONE WHEN:** [e.g., a unit test covers each status transition, and the integration test passes]
304
+ - **TEST FIRST:**
305
+ - `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on [e.g., an unknown status being accepted]
306
+ - `packages/api/items.integration.test.ts` `persists the new status` fails on [e.g., no row being stored]
307
+
308
+ <!-- bkit:task 2 end -->
309
+
310
+ <!-- bkit:group 1 end -->
311
+
312
+ ### 🔒 Gate 2: Code Implementation Check
313
+
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.
432
321
 
433
322
  **Mandatory Tasks (Testing & Documentation):**
434
323
 
435
- - [ ] **Verify test coverage against Derived Test Matrix:** Each `Acceptance Scenario → Derived Test Matrix` row → one runbook task whose `Done when` carries its test; gaps → add to that task, not here.
436
- - [ ] **Sweep existing tests:** Each task fixed the tests it broke; full suite green per `docs/testing.md`. Fix only what tasks missed.
437
- - [ ] **Sweep new tests:** Each task's `Done when` tests exist and pass per Testing Strategy; add only what tasks missed — not where tests are first written. Reuse data factories + auth conventions (above) for UI E2E tests.
438
- - [ ] **Verify observability:** Observable per `docs/observability.md` — errors logged via the project's structured logger (e.g. `console.error("[Context] Message", payload)`), correlation IDs through pipeline, audit coverage on monitored tables where the project has it (e.g. audit / CDC triggers); update doc for new log names / labels / tracing scopes.
439
- - [ ] **Update documentation:** Integrate logic/schemas into affected docs — `docs/architecture.md`, `docs/data-schema.md`, `docs/knowledge.jsonl`, `docs/decisions.jsonl`, others via `.agents/docs.md`. Rewrite ground-truth prose; do not append lazy bullet points.
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.
440
329
 
441
330
  ### 🔒 Gate 3: Testing & Documentation Check
442
331
 
443
- **CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Verification Plan`.
444
-
445
- - [ ] **Docs updated:** Every row in `Documentation Updates` completed. `.agents/docs.md` still accurate.
446
- - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
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.
447
335
 
448
336
  ## Verification Plan
449
337
 
450
- > [!IMPORTANT]
451
- > **Advisory build-phase checks, not merge gates.** Only `Agent Execution Runbook` `Done when` lines gate merge; nothing here does. Do not write "before merge" on untickable boxes — CI/human-only preconditions (lane RUN, deployed state, operator step) unenforceable. Work that MUST block merge → runbook task + codebase-verifiable `Done when`; lane that must run → CI config, not plan prose.
452
-
453
338
  ### Automated Tests
454
339
 
455
- - [ ] **Full Local Gate Suite:** Full local gates — deepest declared `bkit:gate:*` script up to integration (`pnpm bkit:gate:static-unit-integration`, else `pnpm bkit:gate:static-unit`; e.g. typecheck, lint, `format:check`, prose, `slop:delta`, unit, in-process integration) + `bkit check`. Do not weaken gates (anti-suppression CRITICAL under Architecture & Component Changes).
456
- - [ ] **Test Synchronization:** [List existing E2E tests (e.g. Playwright) to update synchronously to prevent CI failures.]
457
- - [ ] **Build Configuration:** [Keep new test-only files (mocks, test configs) out of the production build (e.g. `tsconfig.json` `exclude`).]
458
- - [ ] **[Test Type] (`path/to/test.spec.ts`):** [Describe flows/unit/E2E additions. Note data hygiene needs.]
459
- - [ ] **Apply local migrations:** New migrations → apply locally (e.g. `npx supabase db push --local`); else integration tests fail on stale schema.
460
- - [ ] **Run all tests:** Local unit + integration (e.g. `pnpm test`, `pnpm test:integration`); fix failures before Gate 4.
461
-
462
- > [!IMPORTANT]
463
- > **No Architectural Downgrades:** Build / compiler / test errors during verification → never hot-fix or anti-pattern; follow `docs/architecture.md` + named reference repos. Halt if stuck.
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.]
464
346
 
465
347
  ### 🔒 Gate 4: Automated Verification Check
466
348
 
467
- **CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Manual Verification`.
349
+ - [ ] **Gate 4 — Verified:** every Automated Tests box is checked, with proof (test output, a CLI result or an API response).
468
350
 
469
- - [ ] **Gate 4 - Verified:** Every checkbox in Automated Tests independently verified and checked off. Explicit proof (test outputs, CLI results, API responses) gathered.
470
-
471
- ### 👤 Manual Verification
351
+ ### Manual Verification
472
352
 
473
353
  > [!CAUTION]
474
- > **Owner-run acceptance checks — advisory only.** Run during build wherever a CLI can (Dashboard Ban below). An unticked box blocks nothing: not the merge, not plan approval. This is not a Gate 1 human-confirmation section.
475
-
476
- > [!WARNING]
477
- > **Dashboard Ban:** Proactively use local CLIs (e.g. `gh`, `vercel`, `npx supabase`) to verify CI/CD pipelines instead of asking users to check dashboards.
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.
478
355
 
479
- - [ ] **Step 1:** [Instructions for agent/user to verify feature end-to-end via CLI/DB.]
356
+ - [ ] **Step 1:** [How to verify the feature end to end through the CLI or the database.]
480
357
 
481
358
  <!-- bkit:end -->