@cbartens/bkit 5.5.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -8,24 +8,14 @@
8
8
 
9
9
  > [!CAUTION]
10
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.
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
+ [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
+ - [`#N — title (state)` per related issue. None → `None`; initially set to `PENDING`.]
29
19
 
30
20
  ---
31
21
 
@@ -37,35 +27,16 @@
37
27
  >
38
28
  > **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). Agent handles rest.
39
29
 
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.
52
-
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
+ [1-2 sentences from the user's side: what they do, 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
40
  - **WHEN** [trigger / user action] **→ THEN** [observable outcome]
70
41
  - **WHEN** [next step] **→ THEN** [outcome]
71
42
  - **IF** [edge case / failure — mirrors an Edge Cases row] **→ THEN** [handling]
@@ -74,8 +45,6 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
74
45
 
75
46
  ### Concrete Example
76
47
 
77
- > Plan expands from design.
78
-
79
48
  **Setup:** [User role, existing state, context]
80
49
 
81
50
  **Steps:**
@@ -88,34 +57,15 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
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] |
63
+ | [Design Key Edge Case or plan-added case] | [Specific behavior] |
97
64
  | [e.g., concurrent edit from another device] | [e.g., last-write-wins, 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` = a tier from `docs/testing.md`: Static, Unit, Integration, @live (golden), E2E, fresh-DB replay, Smoke.
119
69
 
120
70
  <!-- prettier-ignore -->
121
71
  | Test description | Type | Target file |
@@ -130,9 +80,6 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
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
@@ -141,15 +88,12 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
141
88
  > **🛑 HUMAN must READ and CONFIRM this SECTION.**
142
89
  > Review proposed names and breaking changes below.
143
90
 
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`.]
91
+ [Proposed names (pages, files, DB tables, routes, API contracts) and breaking changes (DB structure, global layout). None → `None`; initially set to `PENDING`.]
145
92
 
146
93
  ### 👤 ✅ Human Confirmation
147
94
 
148
95
  - [ ] **Breaking Changes confirmed:** I have reviewed all breaking changes and naming decisions above.
149
96
 
150
- > [!CAUTION]
151
- > **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
152
-
153
97
  ---
154
98
 
155
99
  ## 👤 ⚠️ Open Questions & Assumptions
@@ -157,8 +101,6 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
157
101
  > [!CAUTION]
158
102
  > **🛑 HUMAN must READ and CONFIRM this SECTION.**
159
103
  > 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
104
 
163
105
  - **Assumption:** [what the plan takes as given] → [what breaks if it's wrong]
164
106
  - **Open Question:** [decision needed] → [who / how to resolve]
@@ -170,156 +112,109 @@ One row per behaviour (copy the tier name from the key above verbatim into `Type
170
112
 
171
113
  - [ ] **Open Questions & Assumptions confirmed:** I have resolved or explicitly accepted every open question and assumption above.
172
114
 
173
- > [!CAUTION]
174
- > **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
175
-
176
115
  ---
177
116
 
178
117
  ## Alternative Approaches & Recommendations
179
118
 
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.
119
+ [Rejected paths and why; future phase recommendations; initially set to `PENDING`.]
183
120
 
184
121
  ## Out of Scope
185
122
 
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`.]
123
+ [Excluded items, each `Exempt`. None → `None`; initially set to `PENDING`.]
187
124
 
188
125
  <!-- prettier-ignore -->
189
126
  | Excluded item | Why `Exempt` | Where it belongs |
190
127
  | --- | --- | --- |
191
128
  | [feature/fix] | [why genuinely-additive] | [design non-goal / follow-up #N / future phase] |
192
129
 
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.
195
-
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
+ [Candidates overlapping this plan's surfaces. None → `None`; initially set to `PENDING`.]
199
133
 
200
134
  <!-- prettier-ignore -->
201
135
  | Candidate | Source | Overlaps | Recommendation |
202
136
  | --- | --- | --- | --- |
203
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] |
204
138
 
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.
207
-
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** — 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.
220
149
 
221
150
  _If none apply: "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:** 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`]
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:** 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.
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
174
  - [ ] **Acceptance Scenario confirmed:** Human confirmed `👤 Acceptance Scenario` section (checkbox is `[x]`).
254
175
  - [ ] **Breaking Changes confirmed:** Human confirmed `⚠️ Breaking Changes & Naming Review` section (checkbox is `[x]`).
255
176
  - [ ] **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.
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.
259
180
 
260
181
  ## Data Schema Integration
261
182
 
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.
183
+ [How this feature uses the existing schema and what changes; initially set to `PENDING`.]
265
184
 
266
185
  ### Data Schema Usage
267
186
 
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.,
187
+ [Existing `docs/data-schema.md` tables and fields read (Input) or written (Output). None → `None`; initially set to `PENDING`. e.g.,
269
188
 
270
189
  - **Input (Read):** `users.id`, `items.title`
271
190
  - **Output (Write):** `items.status`, `job_audits.log`]
272
- If no existing fields are used, explicitly state "None".
273
191
 
274
192
  ### Data Schema Changes
275
193
 
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.,
194
+ [New tables, new fields, or changed fields to record in `docs/data-schema.md`. None → `None`; initially set to `PENDING`. e.g.,
277
195
 
278
196
  - **ADD:** `items.new_field` (type: text)
279
197
  - **MODIFY:** `users.role` (added enum value)]
280
- If no schema changes are required, explicitly state "None".
281
198
 
282
199
  ## Reuse Inventory
283
200
 
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`.]
201
+ [One row per capability the plan introduces; initially set to `PENDING`.]
285
202
 
286
203
  <!-- 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.
204
+ | Capability | File | Search performed | Existing candidates | Decision | Justification |
205
+ | --- | --- | --- | --- | --- | --- |
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)] |
301
209
 
302
210
  ## Architecture & Component Changes
303
211
 
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.
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`.]
312
214
 
313
215
  ### Database Migrations
314
216
 
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.
217
+ [New tables / columns / access policies (e.g. RLS) and the migration that adds them; initially set to `PENDING`.]
323
218
 
324
219
  ### [Component Area 1]
325
220
 
@@ -327,13 +222,13 @@ Verify only when applicable.
327
222
 
328
223
  #### [MODIFY] `path/to/file.ext`
329
224
 
330
- - **Existence Check:** [Verify file exists first.]
331
- - [Detail logic, schema, or API contracts.]
225
+ - **Existence Check:** [file exists]
226
+ - [Logic, schema, or API contract changes.]
332
227
 
333
228
  #### [new] `path/to/file.ext`
334
229
 
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.]
230
+ - **Reuse Check:** [`Reuse Inventory` row + reason (a)/(b)/(c)]
231
+ - [Purpose, access policies (e.g. RLS), input validation (e.g. Zod), naming.]
337
232
 
338
233
  #### [DELETE] `path/to/file.ext`
339
234
 
@@ -341,27 +236,20 @@ Verify only when applicable.
341
236
 
342
237
  ### Cron Jobs & Scheduled Tasks
343
238
 
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`.]
239
+ [Scheduled tasks (e.g. Vercel cron, pg_cron, Inngest). None → `None`; initially set to `PENDING`.]
345
240
 
346
241
  ## Supersession Inventory
347
242
 
348
- [Existing artifacts the new code replaces — shared triggers/routes, redundant exports, etc. If plan adds without replacing, write "None"; initially set to `PENDING`.]
243
+ [Existing artifacts the new code replaces. None → `None`; initially set to `PENDING`.]
349
244
 
350
245
  <!-- prettier-ignore -->
351
246
  | Existing artifact | Replaced by | Decision | Justification |
352
247
  | --- | --- | --- | --- |
353
248
  | `path/to/old-thing` | `path/to/new-thing` | DELETE | [reason] |
354
249
 
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`.
361
-
362
250
  ## Documentation Updates
363
251
 
364
- > Docs this change touches only; delete rest. Core below; others via `.agents/docs.md`. Code-change treatment — rewrite prose, no lazy bullet appends.
252
+ [One row per doc this change touches; others via `.agents/docs.md`.]
365
253
 
366
254
  <!-- prettier-ignore -->
367
255
  | Doc | Change required |
@@ -375,8 +263,6 @@ Verify only when applicable.
375
263
  | `docs/testing.md` | [new test files / patterns] |
376
264
  | `docs/observability.md` | [new log names / spans] |
377
265
 
378
- _Delete rows with no change; add a row per other affected doc (resolve via `.agents/docs.md`)._
379
-
380
266
  ## Rollback Strategy
381
267
 
382
268
  <!-- prettier-ignore -->
@@ -390,92 +276,77 @@ _No DB changes: "Code-only — `git revert` sufficient."_
390
276
 
391
277
  ## Agent Execution Runbook
392
278
 
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.
279
+ [Chronological task checklist; initially set to `PENDING`.]
399
280
 
400
281
  **Implementation Tasks (Examples):**
401
282
 
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.
283
+ <!-- bkit:group 1 start -->
411
284
 
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].
285
+ ### GROUP 1: [e.g., Item status in the API]
415
286
 
416
- ### 🔒 Gate 2: Code Implementation Check
287
+ <!-- bkit:task 1 start -->
417
288
 
418
- **CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Testing & Documentation`.
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]
419
293
 
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.
294
+ <!-- bkit:task 1 end -->
423
295
 
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.
296
+ <!-- bkit:task 2 start -->
297
+
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]
300
+ - **READ:** `ItemStatus` in `packages/api/src/items/schema.ts`: [e.g., the allowed statuses]
301
+ - **DEPENDS ON:** 1
302
+ - **DONE WHEN:** [e.g., unit test covers each status transition; integration test passes]
303
+ - **TEST FIRST:**
304
+ - `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on [e.g., an unknown status being accepted]
305
+ - `packages/api/items.integration.test.ts` `persists the new status` fails on [e.g., no row being stored]
306
+
307
+ <!-- bkit:task 2 end -->
308
+
309
+ <!-- bkit:group 1 end -->
310
+
311
+ ### 🔒 Gate 2: Code Implementation Check
312
+
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.
432
316
 
433
317
  **Mandatory Tasks (Testing & Documentation):**
434
318
 
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.
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.
440
324
 
441
325
  ### 🔒 Gate 3: Testing & Documentation Check
442
326
 
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.
327
+ - [ ] **Docs updated:** every `Documentation Updates` row done; `.agents/docs.md` accurate.
328
+ - [ ] **Gate 3 - Verified:** every box above checked.
447
329
 
448
330
  ## Verification Plan
449
331
 
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
332
  ### Automated Tests
454
333
 
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.
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.]
464
340
 
465
341
  ### 🔒 Gate 4: Automated Verification Check
466
342
 
467
- **CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Manual Verification`.
468
-
469
- - [ ] **Gate 4 - Verified:** Every checkbox in Automated Tests independently verified and checked off. Explicit proof (test outputs, CLI results, API responses) gathered.
343
+ - [ ] **Gate 4 - Verified:** every Automated Tests box checked, with proof (test output, CLI result, API response).
470
344
 
471
345
  ### 👤 Manual Verification
472
346
 
473
347
  > [!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.
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.
478
349
 
479
- - [ ] **Step 1:** [Instructions for agent/user to verify feature end-to-end via CLI/DB.]
350
+ - [ ] **Step 1:** [How to verify the feature end-to-end via CLI / DB.]
480
351
 
481
352
  <!-- bkit:end -->