@cbartens/bkit 5.1.0 → 5.2.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 (194) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +90 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  136. package/.bkit/templates/.prettierignore +1 -1
  137. package/.bkit/templates/context/bkit-expo.md +22 -13
  138. package/.bkit/templates/context/bkit-github.md +20 -6
  139. package/.bkit/templates/context/bkit-inngest.md +10 -4
  140. package/.bkit/templates/context/bkit-maestro.md +5 -5
  141. package/.bkit/templates/context/bkit-playwright.md +3 -3
  142. package/.bkit/templates/context/bkit-sentry.md +6 -5
  143. package/.bkit/templates/context/bkit-stripe.md +31 -8
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  145. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  147. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  148. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  149. package/.bkit/templates/slop-scan.config.json +7 -2
  150. package/CHANGELOG.md +42 -0
  151. package/LICENSE.md +21 -161
  152. package/README.md +58 -28
  153. package/dist/checks/after/auth.js +28 -0
  154. package/dist/checks/after/github.js +4 -4
  155. package/dist/checks/after/index.js +29 -45
  156. package/dist/checks/after/managed.js +40 -1
  157. package/dist/checks/before/index.js +5 -4
  158. package/dist/checks/before/mcp.js +53 -53
  159. package/dist/checks/status-holes.js +1 -1
  160. package/dist/checks/tips/catalogue.js +297 -0
  161. package/dist/checks/tips/detect.js +130 -0
  162. package/dist/checks/tips/index.js +146 -0
  163. package/dist/cli.js +47 -9
  164. package/dist/commands/install/doctor.js +5 -1
  165. package/dist/commands/install/install.js +27 -7
  166. package/dist/commands/install/uninstall.js +31 -16
  167. package/dist/commands/install/upgrade.js +15 -32
  168. package/dist/commands/launch.js +27 -11
  169. package/dist/commands/tips.js +10 -0
  170. package/dist/commands/workflow/runs.js +52 -16
  171. package/dist/commands/workflow/runtime.js +8 -0
  172. package/dist/commands/workflow/steps.js +1 -0
  173. package/dist/commands/workflow/tests.js +541 -4
  174. package/dist/commands/workflow/workstreams.js +4 -4
  175. package/dist/install/cloud-env.js +3 -14
  176. package/dist/install/hosts.js +22 -0
  177. package/dist/install/managed-block.js +36 -0
  178. package/dist/install/manifest.js +45 -4
  179. package/dist/install/modules/antigravity.js +8 -7
  180. package/dist/install/modules/claude.js +6 -6
  181. package/dist/install/modules/cloud.js +2 -2
  182. package/dist/install/modules/codex.js +5 -5
  183. package/dist/install/modules/core.js +14 -5
  184. package/dist/install/modules/cursor.js +6 -6
  185. package/dist/install/modules/opencode.js +4 -4
  186. package/dist/install/payload-links.js +5 -5
  187. package/dist/install/placeholders.js +1 -1
  188. package/dist/install/version-file.js +12 -3
  189. package/dist/install/write.js +61 -2
  190. package/dist/shared/package-roots.js +8 -11
  191. package/package.json +4 -6
  192. package/.bkit/core/LICENSE.md +0 -149
  193. package/.bkit/shared/LICENSE.md +0 -22
  194. package/.bkit/templates/LICENSE.md +0 -22
@@ -12,6 +12,30 @@
12
12
  > - `bkit install` and `bkit upgrade` never write these files and never overwrite a copy.
13
13
  > - Adapt app roots, workspace package scope, rules JSON. Examples use `apps/web`, `apps/mobile`, `packages/api`, `@scope`.
14
14
 
15
+ ## What each template is for
16
+
17
+ Adoption order = `bkit tips` order. Sections below: install steps and traps.
18
+
19
+ <!-- prettier-ignore -->
20
+ | Template | What it's for | Skip it and |
21
+ | --- | --- | --- |
22
+ | direnv | Loads `.bkit/.env` tokens whenever the project opens. | Saved tokens never load; every sign-in fails while the file looks right. |
23
+ | Serena | Agents look code up like an editor ("where is this defined, what uses it?"). Read-only. | Agents grep and read whole files: more accidental changes, more correction rounds, higher token cost. |
24
+ | CI workflow + CI scripts | Runs every check on GitHub on every change; one capstone check gates merge; `/bkit-ship` waits for it. | "Shipped" means merged, not checked. |
25
+ | Git hooks (Husky) | Same checks locally on commit and push, in seconds. | Failures surface minutes later in CI, after the agent moved on. |
26
+ | Prettier ignore list | One formatting baseline; stops Prettier reformatting bkit's managed files. | Reviews fill with spacing noise; every bkit upgrade shows false changes. |
27
+ | slop-scan | Flags net-new junk code AI tends to write (filler, dead code, type escapes). | Junk passes skim review and piles up. |
28
+ | Vale | Prose lint for docs and agent instructions. | Padded, vague docs every agent re-reads on every run. |
29
+ | lint-staged | Formats only the staged files inside the commit hook. | Commit hook does nothing, or is slow enough to get skipped. |
30
+ | Cloud-agent workflow + SessionStart hook | CI result starts a cloud agent: ship on green, debug on red; hook installs the cloud toolchain. | Every next step needs a local session. |
31
+ | Context-fetch blocks | `/bkit-debug` reads real CI logs, runtime errors and web results. | Debug guesses from code; real errors stay hidden. |
32
+ | Secrets sync | One local file → every secret store; proves copies match without printing values. | Hand-copied secrets drift: "works for me, broken in production". |
33
+ | graphify | Code map (`docs/capabilities.md`) agents check before building something again. | Agents rediscover structure each run; ripple effects missed. |
34
+ | Dependabot / Renovate | Small grouped update PRs; pinned Actions; security fixes skip the queue. | Updates pile into one large risky upgrade. |
35
+ | Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
36
+ | Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
37
+ | Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
38
+
15
39
  ## Contract
16
40
 
17
41
  <!-- prettier-ignore -->
@@ -37,7 +61,6 @@
37
61
  | Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
38
62
  | Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
39
63
  | Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
40
- | Licence | `.bkit/templates/LICENSE.md` | — | read it; the copies in `.bkit/templates/` are MIT-0 |
41
64
 
42
65
  Placeholders. Copies keep them raw; replace each in your copy:
43
66
 
@@ -47,7 +70,7 @@ Placeholders. Copies keep them raw; replace each in your copy:
47
70
  | `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments) | your default branch | `origin/HEAD`, else `main` |
48
71
  | `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
49
72
  | `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
50
- | `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/path/to/repo/scripts/launchd/bkit-launchd-env.sh` |
73
+ | `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
51
74
  | `{{ENV_FILE}}` | `ai.bkit.launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
52
75
 
53
76
  - `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
@@ -64,18 +87,18 @@ Placeholders. Copies keep them raw; replace each in your copy:
64
87
  <!-- prettier-ignore -->
65
88
  | File | Fits | `context=` | Fetches | Secret / non-secret env | Domains | CLI (provision) |
66
89
  | --- | --- | --- | --- | --- | --- | --- |
67
- | `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs; `diff`: `git diff --stat` since the last green CI run on trunk | `GH_TOKEN` / `BASELINE_BRANCH`, `BASELINE_WORKFLOW` (`diff`) | — | `gh` (base tool) |
68
- | `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE` | — | `gh` (base tool) |
69
- | `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's full log, sliced to the result steps | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS` | — | `gh` (base tool) |
90
+ | `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs tail-bounded per failed job; `diff`: `git diff --stat` (capped) since the last green CI run on trunk | `GH_TOKEN` / `CI_LOG_TAIL`; `BASELINE_BRANCH`, `BASELINE_WORKFLOW`, `DIFF_STAT_N` (`diff`) | — | `gh` (base tool) |
91
+ | `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
92
+ | `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
70
93
  | `tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
71
- | `sentry.md` | Sentry | `runtime` | unresolved issues, last 24 h; trace / window recipes | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST` | `sentry.io` | — |
94
+ | `sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
72
95
  | `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV` | `vercel.com` | `vercel` (yes) |
73
96
  | `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` lines | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID` | `supabase.com` | — |
74
- | `stripe.md` | Stripe | `runtime` | failure / dispute / refund events | `STRIPE_SECRET_KEY` / — | `stripe.com` | — |
97
+ | `stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source | `STRIPE_SECRET_KEY` / `STRIPE_N`, `STRIPE_SINCE_S` | `stripe.com` | — |
75
98
  | `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends | `RESEND_API_KEY` / — | `resend.com` | — |
76
- | `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events | `INNGEST_SIGNING_KEY` / — | `inngest.com` | — |
99
+ | `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window | `INNGEST_SIGNING_KEY` / `INNGEST_N`, `SINCE_ISO`, `INNGEST_ENV` | `inngest.com` | — |
77
100
  | `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE` | `googleapis.com`, `google.com` | `gcloud` (yes) |
78
- | `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines; `e2e`: per-flow exceptions, JUnit, screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR` | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
101
+ | `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines (capped per build); `e2e`: failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
79
102
  | `serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
80
103
 
81
104
  MCP names listed: `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest`, `serena`. Every tool on a listed server runs without a prompt, writes included — list only servers you trust with that.
@@ -140,6 +163,7 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
140
163
  - `slop:delta` runs `bkit ci slop` (bkit devDep on `PATH` through the package script). CI passes the base sha as its one bare argument.
141
164
  - `lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), e.g. `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
142
165
  - Non-Node stack → point each gate at your own commands; keep the gate names.
166
+ - `bkit:test:file` (not seeded; `test-file-script-missing` until declared) runs ONE test file — bkit appends its repo-relative path — and writes a JUnit report to `$BKIT_TEST_REPORT`; `/bkit-build` reads it for test-first. Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`. Call the runner directly, not through a caching task runner.
143
167
 
144
168
  ## CI workflow — `bkit-ci.yml`
145
169
 
@@ -260,12 +284,15 @@ launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist
260
284
  launchctl getenv BKIT_OPENROUTER_API_KEY # bootstrap proof
261
285
  ```
262
286
 
263
- - `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the file, no re-bootstrap.
287
+ - `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the value, revoke it by deleting the line or emptying the value (`KEY=""`); no re-bootstrap.
288
+ - Loader loads `BKIT_*` keys only (others logged as skipped). An empty value runs `launchctl unsetenv`. Loaded key names are recorded in `.launchd-loaded-keys` next to the env file (mode 600; `BKIT_LAUNCHD_STATE` overrides the path); a recorded key missing from the env file is unset on the next run.
289
+ - One failing key is logged and skipped; the rest still load and the loader exits 1. A failed unset stays recorded and retries on the next run.
264
290
  - Log `~/Library/Logs/bkit-launchd.log` records key names only, never values. `BKIT_LAUNCHD_LOG` and `BKIT_LAUNCHD_ENV` override the log and env-file defaults.
265
291
  - Loader self-skips (log line + `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
266
292
  - launchd cannot exec a loader under `~/Documents`, `~/Desktop` or `~/Downloads`: macOS TCC denies it and `/tmp/bkit-launchd.log` reads `Operation not permitted`. Repo under one of those → keep the adopted copy in git but place the loader launchd runs at `~/.config/bkit/bkit-launchd-env.sh` (or another unprotected path) and point `{{SCRIPT_PATH}}` there.
267
293
  - Env-file rules: blank lines and `#` comments ignored; optional `export ` prefix; key must match `[A-Za-z0-9_]`; matching surrounding quotes stripped from the value.
268
- - `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch.
294
+ - `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch (set and unset alike).
295
+ - **Exposure:** `launchctl setenv` makes every loaded token visible to every app started in the login session, not only the app that needs it. Load only tokens you accept that for; prefer `bkit cursor` / `bkit opencode` (per-process env) where possible.
269
296
  - Remove: `launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.
270
297
 
271
298
  ## Cursor — `settings.json`, `environment.json`, `Dockerfile`
@@ -21,12 +21,12 @@ Canonical source: `.bkit/core/workflows/`. `bkit install` regenerates `.claude/c
21
21
 
22
22
  ```
23
23
  .bkit/core/workflows/
24
- ├── bkit-design.md # Workflow 1/5 — 11 steps; hard stop after summary
24
+ ├── bkit-design.md # Workflow 1/5 — 12 steps; hard stop after summary
25
25
  ├── bkit-plan.md # Workflow 2/5 — 12 steps; hard stop after summary
26
26
  ├── bkit-build.md # Workflow 3/5 — 18 steps; CI takes over after PR
27
27
  ├── bkit-debug.md # Workflow 4/5 — 10 steps; normal / soak modes
28
28
  ├── bkit-ship.md # Workflow 5/5 — 15 steps; merge → archive → In Review (human closes)
29
- └── bkit-auto.md # Utility — phase-routed cloud dispatch (ship/debug by CI on a PR or post-merge `dev`; design/plan/build by dispatch)
29
+ └── bkit-auto.md # Utility — phase-routed cloud dispatch (ship/debug by CI on a PR or post-merge `dev`; plan/build by dispatch)
30
30
  ```
31
31
 
32
32
  <!-- prettier-ignore -->
@@ -51,7 +51,7 @@ Choose by the state of the work. Procedure stays in the command file and in § P
51
51
  | `/bkit-build` | What to build is clear (a plan, or a brief) and that code is not on a branch yet. | The change is already implemented on a branch. What to build is still undecided, or not broken into tasks. |
52
52
  | `/bkit-debug` | Tests or CI are actually failing, and the cause is not already known. | Nothing is red. The request is new work. The fix is already known and there is no failure to reproduce. |
53
53
  | `/bkit-ship` | A branch holds the finished change and it is ready to land on `dev`. | No branch. The branch has nothing `dev` lacks. The work is still a design, a plan, or unfinished code. |
54
- | `/bkit-auto` | A cloud or CI event should pick the phase: green PR → ship, red CI → debug, a dispatched issue → design / plan / build. | You already know the phase. Run that command. |
54
+ | `/bkit-auto` | A cloud or CI event should pick the phase: green PR → ship, red CI → debug, a dispatched issue → plan / build. | You already know the phase. Run that command. |
55
55
 
56
56
  ## Workflow Authoring Rules
57
57
 
@@ -119,7 +119,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
119
119
  - **`deferrals` / `failures` on `outcome` row = CUMULATIVE distinct `key` count, not lines:** same-`key` append (§ Updating a Row in `.bkit/jsonl.md`) → `wc -l` double-counts closed deferrals. Readers derive cycle from delta vs prior outcome row — `newFailuresThisRun` in `.bkit/core/engine/commands/analysis.ts`.
120
120
  - **CI-Dispatch poll:** `bkit runs dispatch` (`--budget-s` / `--interval-s`, default 60/10), shared by build's close-workflow and both debug close-workflow sites (PR-mode + LOCAL-mode). A poll outcome is `found` / `none` / `err`; a `sleep` that overruns its window is reported blocked instead of hanging. Self-heal cap 1; re-trigger suffix must match close-workflow suffix. `ciDispatch` verdict always on step-done record (additive field). No `CAN_SLEEP` / `RUNTIME_SLEEPS` capability row — sleeping is measured, not predicted. Blocked sleep → exit 81 → the orchestrator resolves the same poll in its turn loop (`bkit runs wait --pr= --once` per turn), then re-runs `dispatch` with `--poll-result` / `--attempts` / `--all-errored` / `--retriggered`.
121
121
  - **Open-PR pre-flight:** `bkit prs open` probes `--head` before creating: an open PR exits 3 (`--existing=fail`, the default) or is reused (`--existing=reuse`, design / plan PR close). A blind create on a branch with an open PR errors, retries, and lands in the Failure Path. Build Step 18 also probes (`bkit prs probe`) before its push.
122
- - **Roadmap row per phase close:** each close runs `bkit roadmap feature`, which appends its own `kind:"feature"` row then re-renders the `roadmap-status` block from the ledger. Re-rendering is safe because that block is a PURE PROJECTION of `.bkit/issues.jsonl` — so there is no foreign on-disk state to preserve and nothing to parse back. An unchanged section renders byte-identically, so the diff shows only the row that moved. design / plan write on the branch the close squashes (local) or on `feat/{FID}` pre-merge (PR); STRAY allowlist admits both. build / debug write on `feat/{FID}` (swept by `git add -A`), then mirror the same line to `dev` under the dev lock (`bkit roadmap feature --row=` with the row the first call printed) — 4th staging shape: ship merges their PR a cycle later, board would otherwise lag one. The mirror takes the dev lock with `--deadline=60`. Fail-open throughout — failed fold / busy lock / failed push logs and continues; feat-side row already written.
122
+ - **Roadmap row per phase close:** each close appends its own `kind:"feature"` row through `appendFeature`, then re-renders the `roadmap-status` block from the ledger. Re-rendering is safe because that block is a PURE PROJECTION of `.bkit/issues.jsonl` — so there is no foreign on-disk state to preserve and nothing to parse back. An unchanged section renders byte-identically, so the diff shows only the row that moved. design / plan: `bkit branches land` writes the row on the branch the close squashes (local) or on `feat/{FID}` pre-merge (PR); STRAY allowlist admits both. build / debug: `bkit roadmap mirror` writes it on `feat/{FID}` (swept by `git add -A`), then copies the same row to `dev` under the dev lock — 4th staging shape: ship merges their PR a cycle later, board would otherwise lag one. The mirror waits up to 60s for the dev lock and is fail-open — busy lock / failed checkout, pull or push logs and continues; feat-side row already written. ship: `bkit roadmap feature --strict` (Step 6, below) exits 1 when the `SHIPPED` row does not land, failing the step.
123
123
  - **Dev-side mirror guards on `$WT` = `$REPO_ROOT`, not `RUNTIME_*`:** the mirror's fence holds no `RUNTIME_*` value — the runtime was detected in an earlier block and shell state does not cross blocks. `$WT` = `$REPO_ROOT` = adopt mode, where a `dev` checkout swaps the branch out from under the run; capability table moves both flags together (`worktrees` iff `devpushes`), so the local fact is a faithful proxy.
124
124
  - **Phase close never reads the tracker:** a close re-renders the `roadmap-status` block from the ledger and stops. It issues no `list_issues` and writes no label on any issue but its own. A workflow running on one issue may mutate only that issue; a tracker read touches every open one.
125
125
  - **Ship Step 6 fold runs after the two subagents, stages nothing itself:** same fence runs `bkit roadmap feature --root="$WT" --step=ship-update-docs` (`$WT` = `{WORKTREE_PATH}`): appends the `SHIPPED` row, folds. Both paths ride the PR in Step 8's `--scope=pr` commit (§ `/bkit-ship` — Docs and bookkeeping ride the PR). `DOCS_VERDICT` requires the command to report the row appended with `status` = `SHIPPED` — a `BUILT` row from the build close must not green it.
@@ -130,7 +130,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
130
130
  - **Design / plan close on HARD STOP** — human review required before next phase.
131
131
  - **No archive step in ship:** artifacts at canonical `docs/plans/{YYYYMM}/` from design start — nothing to move at close.
132
132
  - **Debug three attempt counters = mode-matched pairs**.
133
- - **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds two as `{RUNTIME_DEVPUSHES}` / `{RUNTIME_WORKTREES}`). `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative DEFAULT, never probed — a `git push --dry-run` sends no ref-update, so a protected branch's pre-receive hook never fires and a false-positive would strand a cloud session on a `dev` checkout. `runtimeGithubCli` is the one live probe (`gh auth status`). An explicit falsy primitive (`CI=false`, `GITHUB_ACTIONS=false`) means ABSENCE, not ambiguity — treating it as ambiguous would cost a laptop its worktree model; only a non-truthy, non-falsy value goes `UNKNOWN`.
133
+ - **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds two as `{RUNTIME_DEVPUSHES}` / `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` / `CLOUD_CURSOR` / `UNKNOWN`: a runner and a triggered Cursor agent have no human to answer, and an unplaceable runtime gets the safe answer — skipping the Grill interview degrades it to assumed answers, while waiting for a human who is absent stalls the run. `LOCAL` and `CLOUD_CLAUDE` (an app session) are attended; `BKIT_RUNTIME` overrides either way. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative DEFAULT, never probed — a `git push --dry-run` sends no ref-update, so a protected branch's pre-receive hook never fires and a false-positive would strand a cloud session on a `dev` checkout. `runtimeGithubCli` is the one live probe (`gh auth status`). An explicit falsy primitive (`CI=false`, `GITHUB_ACTIONS=false`) means ABSENCE, not ambiguity — treating it as ambiguous would cost a laptop its worktree model; only a non-truthy, non-falsy value goes `UNKNOWN`.
134
134
  - **Local happy path is byte-identical across the three runtimes:** every runtime branch is additive. `RUNTIME_DEVPUSHES=true` (laptop, GH-Actions runner) runs the local block verbatim — local `merge --squash -X ours`, `docs({FID}): {phase} DONE bkit [skip ci]`, direct `dev` push, worktree teardown. Only `RUNTIME_DEVPUSHES != true` (claude.ai cloud, `unknown`) takes the PR-merge branch. Never replace a working local call site to serve a cloud runtime; branch around it.
135
135
  - **PR-mode design/plan closes MUST push before `bkit prs open`:** PR creation and `gh pr merge` act on the REMOTE, so a close commit that is only committed locally never enters the PR and never reaches `dev`. The `RUNTIME_DEVPUSHES=true` branch pushes `dev` directly and is unaffected; the `false` branch produces two local commits (`chore({FID}): close-workflow` carrying the `status.jsonl` rows and close telemetry, then `docs({FID}): {phase} roadmap update` carrying `.bkit/issues.jsonl` + `docs/roadmap.md`) and needs an explicit `bkit branches push --mode=feature` to publish them. Placed after the STRAY guard so nothing unvetted is published, and before `bkit prs open --existing=reuse`. Build/debug close pushes the feature branch already. Omitting it silently loses every design/plan close on the PR path.
136
136
  - **`bkit workflows close` runs in the worktree, before the squash, in both close modes:** the `workflow-done` row and the telemetry rows ride the `chore({FID}): close-workflow` commit on `feat/{FID}`, so the squash (local) or the PR (cloud) carries them to `dev`. `status.jsonl` and `.bkit/stats.jsonl` are `merge=union`, so the squash concatenates them with `dev`'s copies.
@@ -163,7 +163,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
163
163
  - **Ledger scans** (plan only, run under `none`): awk counts query-term hits per line (`>=2` distinct terms, or the sole term when one; case-insensitive substring), sorts by hit count desc then line number desc (append-only ledgers → line order is time order), keeps the top 40 per file and footers the total. `cut -f3-` rejoins fields 3..N with tabs, so a literal tab inside a JSONL line survives intact. Backstopped by the `ledger` clamp profile.
164
164
  - **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the three payloads (`addItem`, `listItems`, `updateItem`) from `bkit.githubProject`; `board` null + `boardSkipped` when opted out or not configured. `update_project_item` needs numeric `item_id`, not node id from `add_project_item` → intervening `projects_list` resolve. Status `value` = single-select option id (e.g. `47fc9ee4`), not name. Linear: no-op (state carries status).
165
165
  - **Blocked-by edges:** GitHub: `###### bkit:blocked-by start` / `end` pair in issue body. Linear: native `blockedBy` (append-only; unchanged edges = no-op).
166
- - **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Step 1 resolves an existing issue reference from the session prompt; no match → log `No issue ID in the session prompt.` and stop (not **Failure Path**). Design Step 10 posts `## Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
166
+ - **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Step 1 resolves an existing issue reference from the session prompt; no match → log `No issue ID in the session prompt.` and stop (not **Failure Path**). Design Step 11 posts `## Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
167
167
  - **issue-update-review** (phase-close): **update state only — never change label on close.** GitHub: no-op (phase label until ship `issue-update-merged`). Linear: `save_issue({ id, state: "In Review" })` — no `labels` (partial update would drop `bkit:auto`/`bkit:debug`).
168
168
  - **issue-update-merged** (ship terminal): bkit **never auto-closes / never sets Done**. Ship drops phase labels, adds `bkit:merged`, **In Review** — Linear `state: "In Review"`, GitHub **open** (board → review, not done). Human reviews merged change and closes manually. Merge != acceptance.
169
169
 
@@ -201,7 +201,7 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton
201
201
 
202
202
  **Step convention:** every step ends `### 🔒 Gate N — {Step Name}` checklist (verify before proceed) + new tracker comment with one fenced section (§ Comment Lifecycle).
203
203
 
204
- **Managed-version marker:** renderer injects `<!-- bkit:managed vX.Y.Z — PolyForm Noncommercial 1.0.0 / Small Business 1.0.0 (https://polyformproject.org/licenses/) — do not edit; run \`bkit upgrade\` to refresh -->`(blank line below) after frontmatter (claude), or below the first heading where the frontmatter was replaced by its `description` value as the first line (cursor/opencode). Stamped at`bkit install`/`upgrade`by`stampManagedVersion`— never add version to source workflow.`bkit check`flags`bkit-managed-stale`when marker drifts — hard blocker on`main`/`dev` (or PR into them); advisory on feature branches (inherited drift).
204
+ **Managed-version marker:** renderer injects `<!-- bkit:managed vX.Y.Z — do not edit; run \`bkit upgrade\` to refresh -->`(blank line below) after frontmatter (claude), or below the first heading where the frontmatter was replaced by its `description` value as the first line (cursor/opencode). Stamped at`bkit install`/`upgrade`by`stampManagedVersion`— never add version to source workflow.`bkit check`flags`bkit-managed-stale`when marker drifts — hard blocker on`main`/`dev` (or PR into them); advisory on feature branches (inherited drift).
205
205
 
206
206
  **Pre-worktree git scope:** Step 1 + Step 2 pre-worktree guard on originating branch (often `dev`). Stage the bookkeeping allow-list only (`bkit ledgers commit --only-if-dirty-tracked --scope=core`: FID log dir + ledgers — NEVER whole `docs/plans/` tree). never `git add -A` until `cd "$WORKTREE_PATH"` — sweeps unrelated user edits into workflow commit → rides feat → dev on merge. Post-worktree (Step 3+) `git add -A` fine; cwd = sandbox. `git worktree add` does not inherit dirty state.
207
207
 
@@ -653,8 +653,8 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
653
653
  <!-- prettier-ignore -->
654
654
  | Siblings | Used in step | Sibling-blind contract |
655
655
  | --- | --- | --- |
656
- | `@bkit-design-brainstorm-ideate-1` / `-2` / `-3` | `/bkit-design` Step 3 | Each agent's prompt forbids reading any sibling output. Triplet — pragmatic / optimal-tradeoff / risk-premortem lenses. |
657
- | `@bkit-design-review-1` / `-2` | `/bkit-design` Step 5 | Same; pair. |
656
+ | `@bkit-design-brainstorm-ideate-1` / `-2` / `-3` | `/bkit-design` Step 4 | Each agent's prompt forbids reading any sibling output. Triplet — pragmatic / optimal-tradeoff / risk-premortem lenses. |
657
+ | `@bkit-design-review-1` / `-2` | `/bkit-design` Step 6 | Same; pair. |
658
658
  | `@bkit-plan-review-1` / `-2` / `-3` | `/bkit-plan` Step 5 | Same; triplet — tightness / dependency-correctness / regression-risk lenses. |
659
659
  | `@bkit-plan-scope-check-1` / `-2` | `/bkit-plan` Step 7 | Same; pair. |
660
660
  | `@bkit-ship-update-docs` / `@bkit-ship-summary` | `/bkit-ship` Step 6 | `bkit-ship-summary` must not read `update-docs.md`. |
@@ -669,10 +669,10 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
669
669
  | `@bkit-build-plan-current` | PASS / CONCERNS / FAIL | PASS → Step 5. CONCERNS / FAIL → Step 5 too — advisory only: recorded on the `step-done` row, posted to the tracker with `Affected`, echoed as a console advisory, never blocking. The findings flow into Step 6: `@bkit-build-plan-execute` reads `build-plan-current.md` and treats it as fact about the codebase, the plan as intent. Build never revises the plan file — that belongs to `/bkit-plan`, whose own close re-stamps the anchor. Never invokes `@bkit-plan-update`. |
670
670
  | `@bkit-build-plan-verify` | PASS / CONCERNS / FAIL | PASS → boundary gate (between sub-plans; § Sub-plan boundary gate) → next sub-plan or Step 9; CONCERNS/FAIL / boundary FAIL → `@bkit-build-plan-gaps-remediate` loop (max `MAX_VERIFY_ATTEMPT` = 3 → Failure Path). |
671
671
  | `@bkit-build-challenge-reconcile` | PASS / CONCERNS / FAIL | PASS → Step 14; CONCERNS and `CHALLENGE_REMEDIATE_ATTEMPT` < 1 → Step 12 → Step 13 → Step 14; CONCERNS and `CHALLENGE_REMEDIATE_ATTEMPT` >= 1 → Step 14; FAIL and `CHALLENGE_REMEDIATE_ATTEMPT` < 1 → Step 12 → Step 13 → re-Step 10; FAIL and `CHALLENGE_REMEDIATE_ATTEMPT` >= 1 → Failure Path. Findings carry `class: mechanical | architectural`; `@bkit-build-challenge-remediate` classify-gate FAILs (no fixes) when any architectural finding is present, else fixes mechanical findings. One re-Challenge bite — bounded by `CHALLENGE_REMEDIATE_ATTEMPT` < 1. |
672
- | `@bkit-design-review-1` / `-2` | PASS / CONCERNS / FAIL | `REVIEW_VERDICT` = worst-of-two. PASS/CONCERNS → Step 6 spike (`SPIKE` = TRUE) else Step 7 apply-review; FAIL → Failure Path (design fundamentally not viable, human reframe required). `@bkit-design-review-1` additionally emits `Spike` (`TRUE` / `FALSE`) in its header — a routing flag, not a verdict; `SPIKE` gates Step 6 only and never contributes to `REVIEW_VERDICT`. |
673
- | `@bkit-design-spike` | PASS / CONCERNS / FAIL | Every value → Step 7 apply-review; the step informs, it does not gate. PASS = every claim held under an honest attempt; CONCERNS = nothing disproven but a claim was unsettleable this run (missing credential / service / host), design proceeds with the assumption unproven and `@bkit-design-summary` reports it under `Feasibility`; FAIL = a claim is disproven and `@bkit-design-update` revises the design against the evidence — not a Failure Path, a disproven assumption is the step succeeding. Only a malformed or empty artifact routes to the Failure Path. Per-claim `SETTLED` / `DISPROVEN` / `BLOCKED` stays in the artifact body — the header verdict is the routing signal, not the finding. |
674
- | `@bkit-design-update` | PASS / CONCERNS / FAIL | All paths continue to Step 8 design-organise; CRITICAL items applied, OPTIONAL applied on consensus, OUT-OF-SCOPE deferred. |
675
- | `@bkit-design-organise` | PASS / CONCERNS / FAIL | PASS/CONCERNS → Step 9 summary; FAIL → Failure Path (cycles detected, human review required). |
672
+ | `@bkit-design-review-1` / `-2` | PASS / CONCERNS / FAIL | `REVIEW_VERDICT` = worst-of-two. PASS/CONCERNS → Step 7 spike (`SPIKE` = TRUE) else Step 8 apply-review; FAIL → Failure Path (design fundamentally not viable, human reframe required). `@bkit-design-review-1` additionally emits `Spike` (`TRUE` / `FALSE`) in its header — a routing flag, not a verdict; `SPIKE` gates Step 7 only and never contributes to `REVIEW_VERDICT`. |
673
+ | `@bkit-design-spike` | PASS / CONCERNS / FAIL | Every value → Step 8 apply-review; the step informs, it does not gate. PASS = every claim held under an honest attempt; CONCERNS = nothing disproven but a claim was unsettleable this run (missing credential / service / host), design proceeds with the assumption unproven and `@bkit-design-summary` reports it under `Feasibility`; FAIL = a claim is disproven and `@bkit-design-update` revises the design against the evidence — not a Failure Path, a disproven assumption is the step succeeding. Only a malformed or empty artifact routes to the Failure Path. Per-claim `SETTLED` / `DISPROVEN` / `BLOCKED` stays in the artifact body — the header verdict is the routing signal, not the finding. |
674
+ | `@bkit-design-update` | PASS / CONCERNS / FAIL | All paths continue to Step 9 design-organise; CRITICAL items applied, OPTIONAL applied on consensus, OUT-OF-SCOPE deferred. |
675
+ | `@bkit-design-organise` | PASS / CONCERNS / FAIL | PASS/CONCERNS → Step 10 summary; FAIL → Failure Path (cycles detected, human review required). |
676
676
  | `@*-summary` (`design`, `plan`, `build`, `debug`, `ship`) | PASS / CONCERNS / FAIL | PASS or CONCERNS → close workflow / next step; FAIL → Failure Path. |
677
677
  | 2-way agents (`@bkit-build-plan-execute`, `@bkit-debug-abort-handover`, `@bkit-design-generate`, `@bkit-design-brainstorm-ideate-1/2/3`, `@bkit-plan-complexity-check`, `@bkit-plan-complexity-split`, `@bkit-ship-update-docs`, `@bkit-ship-conflict-resolve`, `@bkit-ship-deferred-sweep`) | PASS / FAIL | PASS → continue; FAIL → Failure Path. Atomic action — no middle state (cannot proceed → fail; no partial-progress CONCERNS). For `@bkit-ship-conflict-resolve`: PASS clears `docs/plans/{YYYYMM}/logs/{FID}/.rebase-failed` sentinel and Step 4 continues; FAIL leaves sentinel and routes to `@bkit-debug-abort-handover`. For `@bkit-ship-deferred-sweep`: PASS → Merge (Step 6); FAIL touches `docs/plans/{YYYYMM}/logs/{FID}/.deferred-blocked` and routes to `@bkit-debug-abort-handover` (merge never happens). FAIL only on >=1 of four blocking tests (behaviour / safety / false green / consumer break); a gap passing none joins the third track `Lazy (unjustified)`, orthogonal to the verdict — recorded in `docs/deferrals.jsonl` (`reason` = `unjustified`; new `key` unplanned, own `key` re-appended when adjudicated) and resurfaced, never merged against. |
678
678
 
@@ -690,7 +690,8 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
690
690
  | `MAX_MERGE_ATTEMPT` | 3 | `/bkit-ship` PR merge retries |
691
691
  | `MAX_REVALIDATE_ATTEMPT` | 3 | `/bkit-ship` poll-only Step 9 re-entries after a gate refusal (10/11/14/17) |
692
692
  | `MAX_DEV_DISPATCH_ATTEMPTS` | 3 | `bkit-cloud.yml` — distinct failed `dev` CI SHAs per FID that may each dispatch `/bkit-debug` |
693
- | Step timeout | 3600s | Any workflow or subagent run exceeding this → Failure Path |
693
+ | Grill rounds | 10 | `/bkit-design` Step 3 interview cap; literal in the step, not in `THRESHOLDS` |
694
+ | Step timeout | 3600s | Any workflow or subagent run exceeding this → Failure Path; `/bkit-design` Step 3 time waiting on human answers does not count |
694
695
  | Lock idle threshold | 1800s | Concurrent-run cut-off: holder `IN_PROGRESS` with last-step age <30min → Failure Path; any other holder reclaimed at once (`WORKFLOW_LOCK_IDLE_S`, `commands/workflow/locks.ts`) |
695
696
  | Dev lock stale threshold | 900s | `.bkit/.dev.lock` age at which a holder is presumed dead → reclaim and retry (`SHIP_DEV_LOCK_STALE_S`). Bounds the blast radius of a leaked dev lock to 15min |
696
697
  | Dev lock wait budget | 600s | How long a dev critical section waits for the lock before Failure Path with the holder line (`SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S`). Ship's Failure Path and the build / debug dev-side roadmap mirror pass `--deadline=60` and skip their dev ops rather than hard-failing |
@@ -802,7 +803,7 @@ Both paths idempotent — re-run skips when present; orphan markers cleaned by n
802
803
 
803
804
  Each subsection documents command behaviour — steps, subagents, artifacts, verdict routing, close. Agent capability/effort → `.bkit/prompts.md`.
804
805
 
805
- ### `/bkit-design` — 11 steps
806
+ ### `/bkit-design` — 12 steps
806
807
 
807
808
  **Goal:** design doc only. No plan, no code. Always hard-stops after summary for human review (do not invoke `/bkit-plan`).
808
809
 
@@ -811,19 +812,20 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
811
812
  | --- | --- | --- | --- | --- |
812
813
  | 1 — Start Workflow | — | tracker issue | `.lock`, tracker comment | Fetch `origin/dev`. Resolve `{ISSUE_ID}` from the session prompt (no match → stop; never create), set label `bkit:design`, state `In Progress`. no commits on `dev` — `status.jsonl` init + `start-workflow` step entry deferred to Step 2 inside the worktree. |
813
814
  | 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev`, resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
814
- | 3 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1` ‖ `-2` ‖ `-3` (parallel triplet) | `design-input-{RUN}.md` | `design-brainstorm-ideate-1.md`, `-2.md`, `-3.md` | Pragmatic / optimal-tradeoff / risk-premortem lenses; effort-tier diversity (`high`/`medium`/`high`); sibling-blind. `BRAINSTORM_VERDICT` = worst of three. |
815
- | 4 — Generate Design | `@bkit-design-generate` | all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied HERE only — not to the sibling-blind ideate triplet. |
816
- | 5 — Design Review | `@bkit-design-review-1` ‖ `@bkit-design-review-2` (parallel) | `design-v1-draft.md`, `design-input-{RUN}.md` | `design-review-1.md`, `design-review-2.md` (opinion-only logs) | Effort-tier diversity (high vs medium); sibling-blind. `REVIEW_VERDICT` = worst of two. FAIL → Failure Path. `SPIKE` = `Spike` header from `design-review-1.md` only. |
817
- | 6 — Spike | `@bkit-design-spike` _(only if `SPIKE` = TRUE)_ | `design-v1-draft.md`, `design-review-1.md` | `design-spike.md` (opinion-only log), throwaway probes under `logs/{FID}/spike/` | Settles review-named unknowns by running code, before the design locks. `SPIKE_VERDICT` ∈ {PASS, CONCERNS, FAIL} — every value continues to Step 7; the step informs, never gates. Probe files confined to `docs/plans/` (the close squash's stray guard would otherwise abort the phase five steps later). |
818
- | 7 — Apply Review | `@bkit-design-update` | `design-v1-draft.md`, both reviews, `design-spike.md` (if present) | `design-v2-reviewed.md` (versioned draft) | CRITICAL items always applied; OPTIONAL applied on consensus; OUT-OF-SCOPE deferred. Spike evidence outranks review opinion — a FAIL claim revises the design element resting on it. |
819
- | 8 — Design Organise | `@bkit-design-organise` | `design-v2-reviewed.md` | `design-v3-organised.md` (versioned draft) | Decompose design into dependency-annotated workstreams (`WS-N`). `ORGANISE_VERDICT` = FAIL (cycles) → Failure Path. |
820
- | 9 — Summary | `@bkit-design-summary` | highest design-v* + glob design-* | `design-summary.md` | Commit `chore({FID}): summary bkit [skip ci]` → push. `SUMMARY_VERDICT` = FAIL → Failure Path. Glob picks up `design-spike.md` — `Feasibility` leads with a spike FAIL. |
821
- | 10 — Suggest Workstreams | — | `design-v3-organised.md` | parent-issue comment, `status.jsonl` | `bkit workstreams comment` reads `## Suggested Workstreams` (none parsed → exit 3 → Failure Path) and builds one advisory comment for the parent issue: one line per `WS-N` (`Requires` included) plus the design link. `NEVER auto-trigger`. Never creates an issue, never comments on another issue, never sets blockers. |
822
- | 11 — Close Workflow | — | — | `{YYYYMM}/{FID}-design.md` (copy of v3), `{YYYYMM}/archive/` (superseded, re-run only) | `bkit workflows promote` (anchor stamped from the runtime-resolved base commit, any changed canonical archived, v3 copied to the canonical bucket) → `bkit workflows close --record-step --outbox --message=` (compliance grade, close row, telemetry, `chore({FID}): close-workflow` commit in the worktree) → `cd {REPO_ROOT}` → `bkit branches land`. Local (runtime pushes dev, dev lock): checkout `dev` → stray-artifact check → squash `feat/{FID}` → non-doc and canonical-blob checks → roadmap row → `docs({FID}): design DONE` commit (`--squash-of`) → push `dev` → remove the workflow-created worktree and its branch. PR mode: roadmap commit → push → open or reuse the PR → squash-merge it (exit 80 hands either stage to MCP; re-run with `--pr` / `--merged-sha`). Both: landed-body scan, transport cross-check, `close-transport` row, lock release → `bkit workflows links --ref={CANONICAL_REF} --outbox` prints the close comment. Set state `In Review`; phase label `Design` persists. Final return displays `design-summary.md` verbatim, then offers a plain-English explanation on request. |
815
+ | 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Stops on an empty frontier plus human confirmation, a human stop, or 10 rounds. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. An earlier run's `Settled` entries stay settled. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. Not offered by `bkit-cloud.yml` `workflow_dispatch`; a copy-and-own `bkit-cloud.yml` still offering `design` runs it headless. |
816
+ | 4 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1` ‖ `-2` ‖ `-3` (parallel triplet) | `design-input-{RUN}.md` | `design-brainstorm-ideate-1.md`, `-2.md`, `-3.md` | Pragmatic / optimal-tradeoff / risk-premortem lenses; effort-tier diversity (`high`/`medium`/`high`); sibling-blind. `BRAINSTORM_VERDICT` = worst of three. |
817
+ | 5 — Generate Design | `@bkit-design-generate` | `design-input-{RUN}.md` (carries the `Grill decisions` section), all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied HERE only — not to the sibling-blind ideate triplet. |
818
+ | 6 — Design Review | `@bkit-design-review-1` ‖ `@bkit-design-review-2` (parallel) | `design-v1-draft.md`, `design-input-{RUN}.md` | `design-review-1.md`, `design-review-2.md` (opinion-only logs) | Effort-tier diversity (high vs medium); sibling-blind. `REVIEW_VERDICT` = worst of two. FAIL → Failure Path. `SPIKE` = `Spike` header from `design-review-1.md` only. |
819
+ | 7 — Spike | `@bkit-design-spike` _(only if `SPIKE` = TRUE)_ | `design-v1-draft.md`, `design-review-1.md` | `design-spike.md` (opinion-only log), throwaway probes under `logs/{FID}/spike/` | Settles review-named unknowns by running code, before the design locks. `SPIKE_VERDICT` ∈ {PASS, CONCERNS, FAIL} — every value continues to Step 8; the step informs, never gates. Probe files confined to `docs/plans/` (the close squash's stray guard would otherwise abort the phase five steps later). |
820
+ | 8 — Apply Review | `@bkit-design-update` | `design-v1-draft.md`, both reviews, `design-spike.md` (if present) | `design-v2-reviewed.md` (versioned draft) | CRITICAL items always applied; OPTIONAL applied on consensus; OUT-OF-SCOPE deferred. Spike evidence outranks review opinion — a FAIL claim revises the design element resting on it. |
821
+ | 9 — Design Organise | `@bkit-design-organise` | `design-v2-reviewed.md` | `design-v3-organised.md` (versioned draft) | Decompose design into dependency-annotated workstreams (`WS-N`). `ORGANISE_VERDICT` = FAIL (cycles) → Failure Path. |
822
+ | 10 — Summary | `@bkit-design-summary` | highest design-v* + glob design-* | `design-summary.md` | Commit `chore({FID}): summary bkit [skip ci]` → push. `SUMMARY_VERDICT` = FAIL → Failure Path. Glob picks up `design-spike.md` — `Feasibility` leads with a spike FAIL. |
823
+ | 11 — Suggest Workstreams | — | `design-v3-organised.md` | parent-issue comment, `status.jsonl` | `bkit workstreams comment` reads `## Suggested Workstreams` (none parsed → exit 3 → Failure Path) and builds one advisory comment for the parent issue: one line per `WS-N` (`Requires` included) plus the design link. `NEVER auto-trigger`. Never creates an issue, never comments on another issue, never sets blockers. |
824
+ | 12 — Close Workflow | — | — | `{YYYYMM}/{FID}-design.md` (copy of v3), `{YYYYMM}/archive/` (superseded, re-run only) | `bkit workflows promote` (anchor stamped from the runtime-resolved base commit, any changed canonical archived, v3 copied to the canonical bucket) → `bkit workflows close --record-step --outbox --message=` (compliance grade, close row, telemetry, `chore({FID}): close-workflow` commit in the worktree) → `cd {REPO_ROOT}` → `bkit branches land`. Local (runtime pushes dev, dev lock): checkout `dev` → stray-artifact check → squash `feat/{FID}` → non-doc and canonical-blob checks → roadmap row → `docs({FID}): design DONE` commit (`--squash-of`) → push `dev` → remove the workflow-created worktree and its branch. PR mode: roadmap commit → push → open or reuse the PR → squash-merge it (exit 80 hands either stage to MCP; re-run with `--pr` / `--merged-sha`). Both: landed-body scan, transport cross-check, `close-transport` row, lock release → `bkit workflows links --ref={CANONICAL_REF} --outbox` prints the close comment. Set state `In Review`; phase label `Design` persists. Final return displays `design-summary.md` verbatim, appends the one tip `bkit tips --workflow=<name>` prints as `## Setup Tips`, then offers a plain-English explanation on request. |
823
825
 
824
- **Hard stop in Step 11 caution block:** "Design requires human review. Do not invoke `/bkit-plan`."
826
+ **Hard stop in Step 12 caution block:** "Design requires human review. Do not invoke `/bkit-plan`."
825
827
 
826
- **Step 10 contract:** the organised design's `## Suggested Workstreams` is the suggestion. Step 10 copies that list onto the parent issue as an advisory comment (`NEVER auto-trigger`). It does not file issues. `/bkit-plan` Step 1 parses `**Parent design:**` when a human has put that marker on an issue body; absent → standalone plan. `/bkit-build` Step 1 honours blocker edges a human has set. Design and plan never share FID.
828
+ **Step 11 contract:** the organised design's `## Suggested Workstreams` is the suggestion. Step 11 copies that list onto the parent issue as an advisory comment (`NEVER auto-trigger`). It does not file issues. `/bkit-plan` Step 1 parses `**Parent design:**` when a human has put that marker on an issue body; absent → standalone plan. `/bkit-build` Step 1 honours blocker edges a human has set. Design and plan never share FID.
827
829
 
828
830
  ### `/bkit-plan` — 12 steps
829
831
 
@@ -838,12 +840,12 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
838
840
  | 4 — Fetch Context | — | Related-issues tracker search (keyed on the generated plan's surfaces) + `bkit context ledger-scan` over `docs/{deferrals,failures}.jsonl` → `related-issues.md` (tracker-gated), `related-deferrals.md`, `related-failures.md` (each `None.` when empty). Advisory context for review; never gates, never auto-expands scope. |
839
841
  | 5 — Review Plan | `@bkit-plan-review-1` ‖ `-2` ‖ `-3` (parallel triplet) | Reads plan + the three `related-*.md` context files. Tightness / dependency-correctness / regression-risk lenses. All three write critique logs. Missing or vague `**Done when:**` on any task → CRITICAL. |
840
842
  | 6 — Apply Review | `@bkit-plan-update` | In-place edits to `{FID}-plan.md`; writes `plan-apply-review.md` log. Preserves every task's `**Done when:**` line (may tighten, never remove/weaken). |
841
- | 7 — Check Scope | `@bkit-plan-scope-check-1` ‖ `@bkit-plan-scope-check-2` (parallel) | Scope completeness audit. `**Done when:**` is the literal criteria slot; missing on any task → FAIL. |
843
+ | 7 — Check Scope | `@bkit-plan-scope-check-1` ‖ `@bkit-plan-scope-check-2` (parallel) | Scope completeness audit. `**Done when:**` is the literal criteria slot; missing on any task → FAIL. `**Test first:**` missing, malformed or unjustified `n/a` → CRITICAL. |
842
844
  | 8 — Apply Scope | `@bkit-plan-update` | In-place edits; scope expansions → append `docs/deferrals.jsonl`. |
843
845
  | 9 — Check `Complexity` | `@bkit-plan-complexity-check` | `COMPLEXITY_VERDICT` ∈ {SINGLE, SPLIT}, read and recorded on the `plan-complexity-check` row as `verdict` by `steps finish --agent=bkit-plan-complexity-check` (the agent's own verdict set); exit 5 / 6 re-asks the agent. |
844
846
  | 10 — Split Plan | `@bkit-plan-complexity-split` _(only if `split`)_ | Writes `{FID}-plan-N.md` sub-plans + `plan-split.md` log; self-verifies losslessness (`SPLIT_VERDICT` ∈ {PASS, FAIL}; FAIL → Failure Path). |
845
847
  | 11 — Summary | `@bkit-plan-summary` | Commit `chore({FID}): summary bkit [skip ci]` → push. |
846
- | 12 — Close Workflow | — | Archive any existing canonical → copy v4 → sync to `dev`, remove worktree, delete branches (same as `/bkit-design` Step 11, except `workflows promote` moves the whole `{FID}-plan*.md` set to the archive under one timestamp, copies the split's children as `{FID}-plan-{k}.md` with working names rewritten, and stamps `designPath` / `designBaseSha` into the anchor). Set state `In Review`; phase label `Plan` persists. Final return displays `plan-summary.md` verbatim, then offers a plain-English explanation on request. |
848
+ | 12 — Close Workflow | — | Archive any existing canonical → copy v4 → sync to `dev`, remove worktree, delete branches (same as `/bkit-design` Step 12, except `workflows promote` moves the whole `{FID}-plan*.md` set to the archive under one timestamp, copies the split's children as `{FID}-plan-{k}.md` with working names rewritten, and stamps `designPath` / `designBaseSha` into the anchor). Set state `In Review`; phase label `Plan` persists. Final return displays `plan-summary.md` verbatim, appends the one tip `bkit tips --workflow=<name>` prints as `## Setup Tips`, then offers a plain-English explanation on request. |
847
849
 
848
850
  **Hard stop in Step 12 caution block:** "Plan requires human review. Do not invoke `/bkit-build`."
849
851
 
@@ -863,8 +865,8 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
863
865
  | 3 — Branch Sync | — | `bkit branches sync --merge-docs`: fetch `origin/dev`; when commits touching `docs/` are behind, merge it — ledger conflicts union, other `docs/` conflicts take `dev`, a conflict outside `docs/` aborts the merge (exit 11 → Failure Path). |
864
866
  | 4 — Plan Current | `@bkit-build-plan-current` _(skipped when the mechanical trigger clears)_ | Orchestrator trigger `bkit branches anchor-read --field=baseSha --against=origin/dev` reads the plan's `bkit:anchor` (§ Anchor Block) and exits 12 — skipping the whole step, no agent, no `step-done` row, same shape as Step 5's `[skills=false]` skip — on any of: no plan, no anchor, `baseSha` unreachable in this clone, nothing landed on `origin/dev` since it. Else it prints `value` (= `BASE_SHA`) and the agent derives its own changed-path list from it, intersects that against the paths the plan's tasks depend on, and reads per-path diffs for the intersection only. `Executable` tasks are not findings; `Reword` / `Broken` are. Judges the PLAN against the codebase — the design doc is not an input, and `designPath` / `designBaseSha` have no consumer here. `CURRENT_VERDICT` is advisory on every value — PASS / CONCERNS / FAIL all → Step 5; CONCERNS / FAIL are recorded, comment-posted with `Affected`, and echoed as a console advisory, never blocking. Findings carry into Step 6 as a Read for `@bkit-build-plan-execute`; build never revises the plan, a re-run of `/bkit-plan` does. |
865
867
  | 5 — Skills | `@bkit-build-install-skills` _(skip if input contains `[skills=false]`)_ | If new skills installed → commit `chore({FID}): install skills bkit [skip ci]`. |
866
- | 6 — Execute Plan | `@bkit-build-plan-execute` | Per sub-plan N: `build-plan-execute-N-log.md`. Single-attempt; writes stub-first then incremental `DONE` / `BLOCKED` log entries via `Bash echo >>`; writes source. Does not modify the sub-plan markdown — checkbox ticking is verify's job (per-task `Edit`-tick phase after impl is done is a known timeout vector; verify absorbs recovery). On timeout (`EXECUTE_VERDICT = PENDING`), no in-Step retry — the verify→remediate loop (Step 7 → Step 8, bounded by `MAX_VERIFY_ATTEMPT` = 3) absorbs the recovery via `bkit-build-plan-gaps-remediate`. `EXECUTE_VERDICT`: PASS → Step 7. Other → Failure Path. |
867
- | 7 — Verify Plan | `@bkit-build-plan-verify` | Per sub-plan N, attempt-numbered: `build-plan-verify-N-{VERIFY_ATTEMPT}.md`. Reads glob of execute attempts' `DONE —` lines + each task's `**Done when:**` line to cross-reference against `git diff`; ticks plan `[ ]`→`[x]` only when task's `**Done when:**` criterion is satisfied in the codebase (never on `DONE —` claim alone). Missing `**Done when:**` on any task → FAIL (template structure broken — remediation cannot recover, routes via Failure Path). `VERIFY_VERDICT` ∈ {PASS, CONCERNS, FAIL}. PASS **and** N < `SUB_COUNT` → boundary gate (§ Sub-plan boundary gate) → `build-subplan-gate-N-{VERIFY_ATTEMPT}.md` + row; `BOUNDARY_VERDICT` ∈ {PASS, FAIL, SKIPPED}. PASS + boundary != FAIL → next N or Step 9. CONCERNS / FAIL / boundary FAIL → Step 8. Reads prior verify and remediate logs to know what was already verified. |
868
+ | 6 — Execute Plan | `@bkit-build-plan-execute` | Per sub-plan N: `build-plan-execute-N-log.md`. Single-attempt; writes stub-first then incremental `DONE` / `BLOCKED` log entries via `Bash echo >>`; writes source. Per task naming `Test first` tests: tests + stubs first, then the red command from Context (`bkit tests red`, § Test-first) once per test before the task's code. Does not modify the sub-plan markdown — checkbox ticking is verify's job (per-task `Edit`-tick phase after impl is done is a known timeout vector; verify absorbs recovery). On timeout (`EXECUTE_VERDICT = PENDING`), no in-Step retry — the verify→remediate loop (Step 7 → Step 8, bounded by `MAX_VERIFY_ATTEMPT` = 3) absorbs the recovery via `bkit-build-plan-gaps-remediate`. `EXECUTE_VERDICT`: PASS → Step 7. Other → Failure Path. |
869
+ | 7 — Verify Plan | `@bkit-build-plan-verify` | `bkit tests green` first (§ Test-first) → `build-tests-green-N-{VERIFY_ATTEMPT}.md`, read by verify and remediate; verify also reads `build-plan-current.md` (already-landed tasks); exit >= 2 → Failure Path. Per sub-plan N, attempt-numbered: `build-plan-verify-N-{VERIFY_ATTEMPT}.md`. Reads glob of execute attempts' `DONE —` lines + each task's `**Done when:**` line to cross-reference against `git diff`; ticks plan `[ ]`→`[x]` only when task's `**Done when:**` criterion is satisfied in the codebase (never on `DONE —` claim alone). Missing `**Done when:**` on any task → FAIL (template structure broken — remediation cannot recover, routes via Failure Path). `VERIFY_VERDICT` ∈ {PASS, CONCERNS, FAIL}. PASS **and** N < `SUB_COUNT` → boundary gate (§ Sub-plan boundary gate) → `build-subplan-gate-N-{VERIFY_ATTEMPT}.md` + row; `BOUNDARY_VERDICT` ∈ {PASS, FAIL, SKIPPED}. PASS + boundary != FAIL → next N or Step 9. CONCERNS / FAIL / boundary FAIL → Step 8. Reads prior verify and remediate logs to know what was already verified. |
868
870
  | 8 — Remediate Gaps | `@bkit-build-plan-gaps-remediate` _(only if Step 7 CONCERNS or FAIL, or boundary gate FAIL)_ | Attempt-numbered: `build-plan-gaps-remediate-N-{VERIFY_ATTEMPT}-log.md`. Stub-first artifact + flat append-only log (`DONE —` per gap fixed; `BLOCKED —` per blocked gap, appended via `Bash echo >>`); reads glob of own prior attempts to skip already-fixed gaps. Re-run Step 7 (its next row is the next `VERIFY_ATTEMPT`). > `MAX_VERIFY_ATTEMPT` → Failure Path. |
869
871
  | 9 — Holistic Verification | `@bkit-build-plan-verify` (holistic mode) _(only if `SUB_COUNT` >= 2)_ | Cross-sub-plan integration check; writes `build-plan-verify-holistic.md`. `HOLISTIC_VERDICT` FAIL → Failure Path. |
870
872
  | 10 — Challenge Build (parallel) | `@bkit-build-challenge-1`, `@bkit-build-challenge-2` (parallel) | Launch parallel pair. Each reviewer gets same diff; `CHALLENGE_REMEDIATE_ATTEMPT` = count of `build-challenge-remediate` rows (0 on first entry; persists across re-runs). Large-diff guard applied. Outputs: `build-challenge-1.md`, `build-challenge-2.md`. Both must be non-empty → Failure Path on partial (reconciler does not run on partial input). → Step 11. |
@@ -875,7 +877,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
875
877
  | 15 — Diagnose Failure | `@bkit-debug-failure-diagnose` _(only if Step 14 FAIL)_ | Reads the committed Step 14 test log `docs/plans/{YYYYMM}/logs/{FID}/run-tests-{TEST_ATTEMPT}.md`. Writes `build-failure-diagnose-{TEST_ATTEMPT}.md`. |
876
878
  | 16 — Remediate Failure | `@bkit-debug-failure-remediate` _(only if Step 14 FAIL)_ | Writes `build-failure-remediate-{TEST_ATTEMPT}-log.md`. Stub-first artifact + flat append-only log (`DONE —` per fix step; `BLOCKED —` per blocked step, appended via `Bash echo >>`). No skip-done — each attempt is diagnosis-driven and may pick a different strategy. Re-run Step 14 (its next row is the next `TEST_ATTEMPT`). > `MAX_TEST_ATTEMPT` → Failure Path. |
877
879
  | 17 — Summary | `@bkit-build-summary` | Commit `chore({FID}): summary` → open-PR probe → push (`-u origin {BRANCH}`). PR already open (resumed build) → push would fire CI + cloud auto-router on a branch build is still writing → probe stops run first (same probe as Step 18). `bkit-cloud.yml` backstop: no-op while build runs (`.bkit/cloud.md` § Branch-aware routing). |
878
- | 18 — Close Workflow & Create PR | — | `bkit:auto` re-read before close-workflow commit; open-PR probe; if any changed path sits under a `migrations/` or `migrate/` directory (case-insensitive, any depth — covers Supabase, Prisma, Drizzle, Rails) and HEAD lacks `bkit [force build]` → amend or empty commit with `bkit [force build]` → push. `bkit prs open` (base pinned `dev`; body = the `bkit:issue` / `bkit:fid` marker + plan path; retries the create once; reads the base back → exit 6 when it is not `dev`, guarding repos whose default base is `main`); exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head`. Then CI-Dispatch Gate (`bkit runs dispatch`). Set state `In Review`; phase label `Build` persists. Worktree persists for follow-up `/bkit-debug` or `/bkit-ship`. Final return displays `build-summary.md` verbatim, then offers a plain-English explanation on request. |
880
+ | 18 — Close Workflow & Create PR | — | `bkit:auto` re-read before close-workflow commit; open-PR probe; if any changed path sits under a `migrations/` or `migrate/` directory (case-insensitive, any depth — covers Supabase, Prisma, Drizzle, Rails) and HEAD lacks `bkit [force build]` → amend or empty commit with `bkit [force build]` → push. `bkit prs open` (base pinned `dev`; body = the `bkit:issue` / `bkit:fid` marker + plan path; retries the create once; reads the base back → exit 6 when it is not `dev`, guarding repos whose default base is `main`); exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head`. Then CI-Dispatch Gate (`bkit runs dispatch`). Set state `In Review`; phase label `Build` persists. Worktree persists for follow-up `/bkit-debug` or `/bkit-ship`. Final return displays `build-summary.md` verbatim, appends the one tip `bkit tips --workflow=<name>` prints as `## Setup Tips`, then offers a plain-English explanation on request. |
879
881
 
880
882
  **Failure Path includes handover** — when triggered by exhausted retry counts, invokes `@bkit-debug-abort-handover` and posts `Workflow Handover` comment.
881
883
 
@@ -883,7 +885,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
883
885
 
884
886
  **Goal:** diagnose and remediate failing test or CI run; push fix back to branch.
885
887
 
886
- **Mode detection (Step 1):** `bkit prs probe --base=dev`: open PR → `PUSH_MODE` = PR, else LOCAL (exit 80 → `list_pull_requests`); `DEBUG_ATTEMPT` = `bkit counters run` (which debug run this is; a resume keeps its number); then `DEBUG_MODE` (NORMAL | SOAK) from objective signals, first match wins: `[soak]` in session prompt → SOAK; `debug-failure-soak` rows already in the active run → SOAK (resume — mid-run switch sticky); `DEBUG_ATTEMPT` >= `MAX_DEBUG_ATTEMPT` (`bkit counters route` exit 1) → SOAK; else NORMAL. Non-localisable-cause → SOAK judged Step-5 diagnose `Mode: SOAK`, not here.
888
+ **Mode detection (Step 1):** `bkit prs probe` (any base): open PR → `PUSH_MODE` = PR, else LOCAL (exit 80 → `list_pull_requests`); Step 10 re-probes and re-records it, so labels and the ` bkit [verbose ci]` suffix on the close follow a PR opened or closed mid-run; `DEBUG_ATTEMPT` = `bkit counters run` (which debug run this is; a resume keeps its number); then `DEBUG_MODE` (NORMAL | SOAK) from objective signals, first match wins: `[soak]` in session prompt → SOAK; `debug-failure-soak` rows already in the active run → SOAK (resume — mid-run switch sticky); `DEBUG_ATTEMPT` >= `MAX_DEBUG_ATTEMPT` (`bkit counters route` exit 1) → SOAK; else NORMAL. Non-localisable-cause → SOAK judged Step-5 diagnose `Mode: SOAK`, not here.
887
889
 
888
890
  **Ladder + cutover:** `NORMAL` (diagnose + remediate) and `SOAK` (accumulating-context instrument-or-fix). No observe mode — `[DEBUG-OBSERVE]` only in soak agent loop. SOAK entry: invocation start (`DEBUG_ATTEMPT` >= `MAX_DEBUG_ATTEMPT` or `[soak]`); mid-run Step-5 `Mode: SOAK` (`Verdict` != PASS); `NORMAL` exhausts `MAX_NORMAL_ATTEMPT` (STANDARD → PIVOT → FINAL) — final SOAK escalation before handover. Every SOAK entry records `soakEntryAt` (`bkit status meta --soak-entry`), so `SOAK_ATTEMPT` counts only soak rows after it (fresh `MAX_SOAK_ATTEMPT` budget, independent of spent `NORMAL_ATTEMPT`; worst case NORMAL 3 + SOAK 3). SOAK terminal (one-way). Soak loops whatever Run Tests fails on (live or mocked). Diagnose RECOMMENDS; orchestrator DECIDES.
889
891
 
@@ -905,7 +907,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
905
907
  | 7 — Failure Remediate Soak | `@bkit-debug-failure-soak` _(only if `DEBUG_MODE` = SOAK)_ | `SOAK_ATTEMPT` = soak rows since `soakEntryAt` + 1 (`counters derive --since=soakEntryAt`). One accumulating context (reads its prior `debug-failure-soak-*-log.md`) applies the single next instrument-or-fix step against the failing boundary (the real model/DB/stream behind a live tier when one ran, else the failing tier the run surfaced); adds `[DEBUG-OBSERVE]` scaffolding and strips every marker before any declared fix (no-leak); commits `fix({FID}): soak {description}`. → loop to Step 3. Bounded by `SOAK_ATTEMPT` (`MAX_SOAK_ATTEMPT`, counted from each SOAK entry). |
906
908
  | 8 — Push Remediation | — | _(PASS after a fix)_ Status file-only (no intermediate commit so Step 6/7's `fix(...)` stays HEAD at push). PR-mode: append `bkit [verbose ci]` to PR title if absent. Push. → Step 9. |
907
909
  | 9 — Summary | `@bkit-debug-summary` | Commit `chore({FID}): summary{VERBOSE_SUFFIX}` → push. `SUMMARY_VERDICT` = PASS/CONCERNS → Step 10; FAIL → Failure Path. |
908
- | 10 — Close Workflow | — | No-leak assertion: fails the run if any added `[DEBUG-OBSERVE]` line survives the debug diff (`git diff origin/dev..HEAD`, excluding `docs/plans/`) before the CI-triggering push — diff-scoped, not a tree-wide `git grep`, so the bkit-managed prompt/command files that quote the literal marker never false-trip (the soak agent's own `git grep '[DEBUG-OBSERVE]'` self-check in `bkit-debug-failure-soak.md` is the first layer). Else Failure Path. PR-mode: strip `bkit [verbose ci]` from PR title. Commit `chore({FID}): close-workflow{VERBOSE_SUFFIX}` → push + (LOCAL, no PR) `chore({FID}): create-pr{VERBOSE_SUFFIX}` (`VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`). Auto-route marker `bkit [auto route]` on the CI-triggering HEAD when `bkit:auto`. Records `testsLiveSkipped` when no live tier ran (no `test:...:live` task in `scope`). Set state `In Review`; phase label `Debug` persists. Worktree persists. The handover path runs via Failure Path. Final return displays `debug-summary.md` verbatim, then offers a plain-English explanation on request. |
910
+ | 10 — Close Workflow | — | A live `prs probe --head` (any base; skipped on `dev` / `main`) sets `{PR_OPEN}` and re-records `PUSH_MODE` (`bkit status meta --push-mode`); labels, the subject suffix, the title strip and `TRIGGER_PR` all key on it, not on the Step-1 value. No-leak assertion: fails the run if any added `[DEBUG-OBSERVE]` line survives the debug diff (`git diff origin/dev..HEAD`, excluding `docs/plans/`) before the CI-triggering push — diff-scoped, not a tree-wide `git grep`, so the bkit-managed prompt/command files that quote the literal marker never false-trip (the soak agent's own `git grep '[DEBUG-OBSERVE]'` self-check in `bkit-debug-failure-soak.md` is the first layer). Else Failure Path. PR open: strip `bkit [verbose ci]` from PR title. Commit `chore({FID}): close-workflow{VERBOSE_SUFFIX}` → push + (LOCAL, no PR) `chore({FID}): create-pr{VERBOSE_SUFFIX}` (`VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`). Auto-route marker `bkit [auto route]` on the CI-triggering HEAD when `bkit:auto`. Records `testsLiveSkipped` when no live tier ran (no `test:...:live` task in `scope`). Set state `In Review`; phase label `Debug` persists. Worktree persists. The handover path runs via Failure Path. Final return displays `debug-summary.md` verbatim, appends the one tip `bkit tips --workflow=<name>` prints as `## Setup Tips`, then offers a plain-English explanation on request. |
909
911
 
910
912
  **Failure Path** includes conditional handover via `@bkit-debug-abort-handover` when max-retry exhausted → `debug-handover.md`. PR-mode `bkit [verbose ci]` **preserved** (not stripped) — investigator wants ongoing verbose CI; § `bkit [verbose ci]` Marker Propagation cleanup invariant.
911
913
 
@@ -962,7 +964,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
962
964
  | 12 — Failure Remediate | `@bkit-debug-failure-remediate` _(only if not merged)_ | Writes `ship-failure-remediate-{MERGE_ATTEMPT}-log.md`. `Strategy` ladder (`STANDARD → PIVOT → FINAL`). PASS → Step 10 (re-merge). FAIL → Failure Path. |
963
965
  | 13 — Switch to Dev | — | `bkit branches switch --dev-pushes= --worktrees=`: under the dev lock, `git checkout dev`, fetch + fast-forward, rebase-and-push local `dev` commits that are all skip-CI (any CI-running local commit → exit 82, needs a human), install dependencies (failure → exit 16 → **Failure Path**). `RUNTIME_DEVPUSHES=false`: skipped (merge already landed server-side). |
964
966
  | 14 — Worktree Cleanup | — | `bkit worktrees remove --branch={SHIP_BRANCH}` removes only a worktree a workflow created (`.worktree-owned` marker in the outbox; absent = "not mine"), prunes, then deletes the local and remote branch and prunes tracking refs. A worktree still holding the branch (an unmarked one) blocks both deletes and is named in `branchBlockedBy` — a local delete would fail while the remote delete went through. `dev` / `main` refused (exit 2). |
965
- | 15 — Close Workflow | — | `bkit runs gate --squash-of=<PR> --capstone-only --record={STATUS}` → records `ship-merge-ci`, then refuses unless the capstone passed at the squash commit. The capstone job's result alone decides: the run's conclusion and other jobs (deploys, notifications) never fail the close of a merged PR. `bkit workflows close --flush --pr-number= --squash-sha= --outbox= --token=` grades compliance, records `ship-close-workflow`, writes telemetry, and makes the single path-scoped `[skip ci]` close commit under the dev lock: with `--dev-pushes` → `dev` checkout + push `dev`; else a close worktree off `origin/dev` → push `dev`, refused → `ship-close/{FID}` PR; the workflow lock is released before the push. Add `bkit:merged` label, drop `bkit:failed`. Final return displays `ship-summary.md` verbatim, then offers a plain-English explanation on request. **HARD STOP**. |
967
+ | 15 — Close Workflow | — | `bkit runs gate --squash-of=<PR> --capstone-only --record={STATUS}` → records `ship-merge-ci`, then refuses unless the capstone passed at the squash commit. The capstone job's result alone decides: the run's conclusion and other jobs (deploys, notifications) never fail the close of a merged PR. `bkit workflows close --flush --pr-number= --squash-sha= --outbox= --token=` grades compliance, records `ship-close-workflow`, writes telemetry, and makes the single path-scoped `[skip ci]` close commit under the dev lock: with `--dev-pushes` → `dev` checkout + push `dev`; else a close worktree off `origin/dev` → push `dev`, refused → `ship-close/{FID}` PR; the workflow lock is released before the push. Add `bkit:merged` label, drop `bkit:failed`. Final return displays `ship-summary.md` verbatim, appends the one tip `bkit tips --workflow=<name>` prints as `## Setup Tips`, then offers a plain-English explanation on request. **HARD STOP**. |
966
968
 
967
969
  **Failure Path** resolves `BOOK_ROOT` (not `--git-common-dir`), runs `bkit workflows fail` (aborts a rebase, appends `workflow-failed`, releases the lock, clears `.deferred-blocked`), and includes conditional handover via `@bkit-debug-abort-handover` writing `ship-handover.md` when max-retry exhausted.
968
970
 
@@ -972,13 +974,13 @@ No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is
972
974
 
973
975
  ### `/bkit-auto` — phase-routed dispatch
974
976
 
975
- **Goal:** phase-routed cloud dispatcher. `{PHASE}` + `{ARG}` from args → matching phase skill. Two top-level steps only — the stale-run guard and the `bkit:auto` opt-in gate run cloud-side in `bkit-cloud.yml`'s ctx step, not in this file. **`MODE` = CI** (`ship`/`debug`, `{ARG}` = PR number): Step 1 resolves from the PR, Step 2 dispatches; **`MODE` = CI_DEV** (`debug`, `{ARG}` = FID slug — post-merge `dev` CI failure, no open PR): Step 1 sub-step 5 resolves `{FID}` / `{ISSUE_ID}` / `BRANCH` / `HEAD_SHA` from the slug and routes straight to the comment + dispatch; **`MODE` = brief** (`design`/`plan`/`build`, `{ARG}` = issue): Step 1 → Step 2 — human `workflow_dispatch` = opt-in; dispatched skill owns brief + `status.jsonl` / worktree / FID. No worktree, no tracker state beyond single comment line.
977
+ **Goal:** phase-routed cloud dispatcher. `{PHASE}` + `{ARG}` from args → matching phase skill. Two top-level steps only — the stale-run guard and the `bkit:auto` opt-in gate run cloud-side in `bkit-cloud.yml`'s ctx step, not in this file. **`MODE` = CI** (`ship`/`debug`, `{ARG}` = PR number): Step 1 resolves from the PR, Step 2 dispatches; **`MODE` = CI_DEV** (`debug`, `{ARG}` = FID slug — post-merge `dev` CI failure, no open PR): Step 1 sub-step 5 resolves `{FID}` / `{ISSUE_ID}` / `BRANCH` / `HEAD_SHA` from the slug and routes straight to the comment + dispatch; **`MODE` = brief** (`design`/`plan`/`build`, `{ARG}` = issue): Step 1 → Step 2 — human `workflow_dispatch` = opt-in (`bkit-cloud.yml` offers `plan` / `build` only; `design` runs locally); dispatched skill owns brief + `status.jsonl` / worktree / FID. No worktree, no tracker state beyond single comment line.
976
978
 
977
979
  <!-- prettier-ignore -->
978
980
  | Step | Notes |
979
981
  | --- | --- |
980
982
  | 1 — Start Workflow | `bkit repo info --allow-detached` (holds `{BKIT}`, `{OUTBOX_ROOT}`), then one `bkit runs context --phase={PHASE} --arg={ARG}`: classifies `{PHASE}` → `MODE` (CI-status aliases `success`/`pass` → `ship`, `failure`/`fail` → `debug` let the Cursor dashboard paste `/bkit-auto $CI_STATUS $PR_NUMBER` literally; unknown → exit 3). `MODE` = CI: `gh pr view {ARG}` → branch / head / state (open required, exit 7) / URL; the CI run at that head (exit 8 when none); `{FID}` + `{ISSUE_ID}` from the PR-body marker, else the `feat/{FID}` branch (exit 9 when neither parses); `gh` missing → exit 80 → **Failure Path**. `MODE` = CI_DEV: `{ARG}` is the `{FID}` slug itself (allowlist first), `{ISSUE_ID}` = its leading issue segment, `BRANCH` = `dev`, `HEAD_SHA` = `origin/dev`; no PR, no run link. `MODE` = brief: `{ISSUE_ID}` = `{ARG}`. Gate 1 = `bkit steps gate --placeholder=` for the mode's values. The dispatched skill owns FID / `status.jsonl` / worktree. Create fresh tracker comment header. **Stateless — no `status.jsonl`, no `dev` commit.** |
981
- | 2 — Dispatch | Derive `{REF}` — the issue reference in a shape the dispatched workflow's own Step 4 parses (`#N` for GitHub, `ABC-123` for Linear). Route `{PHASE}` → `/bkit-ship {FID} {REF}` / `/bkit-debug {FID} {REF}` / `/bkit-design {REF}` / `/bkit-plan {REF}` / `/bkit-build {REF}`. Invoke via `Skill` (Claude) / `Task` (Cursor); dispatched skill owns its session from there. The regression-gate-verification gate that catches Vercel-ignore / partial-tier demotion lives in `/bkit-ship` Step 2 — Regression Guard (universal — also applies to manual `/bkit-ship` invocations that bypass the workflow). |
983
+ | 2 — Dispatch | Derive `{REF}` — the issue reference in a shape the dispatched workflow's own Step 1 parses (`#N` for GitHub, `ABC-123` for Linear). Route `{PHASE}` → `/bkit-ship {FID} {REF}` / `/bkit-debug {FID} {REF}` / `/bkit-design {REF}` / `/bkit-plan {REF}` / `/bkit-build {REF}`. Invoke via `Skill` (Claude) / `Task` (Cursor); dispatched skill owns its session from there. The regression-gate-verification gate that catches Vercel-ignore / partial-tier demotion lives in `/bkit-ship` Step 2 — Regression Guard (universal — also applies to manual `/bkit-ship` invocations that bypass the workflow). |
982
984
 
983
985
  **CI-class skip conditions:** one tracker no-op line, exit 0. Only real failures (missing args, tracker unreachable, malformed state) → Failure Path. Loop bound: `/bkit-debug` enforces `MAX_DEBUG_ATTEMPT` = 3 internally; cloud never counts attempts.
984
986
 
@@ -1138,7 +1140,7 @@ Precedence: `bkit [force build]` on head commit wins.
1138
1140
  | --- | --- |
1139
1141
  | `chore({FID}): pre-worktree uncommitted changes` (design / plan / build Step 2, `bkit ledgers commit --only-if-dirty-tracked`) | `bkit [skip ci]` |
1140
1142
  | `chore({FID}): {step-slug}` for per-step in-worktree commits (e.g. `worktree-setup`, `branch-sync`, `install-skills`, `plan-execute sub-plan N`, `plan-verify sub-plan N attempt M`, `failure-diagnose attempt N`, `build-challenge attempt N`, `build-challenge-reconcile attempt N`, `build-challenge-remediate attempt N`, `build-challenge-tests`, `summary`, `create-pr`, ship `merge-pr attempt N`, ship `prune-skills`, ship `update-docs-summary`) | none — in-worktree, never visible to CI on `dev` |
1141
- | `chore({FID}): summary bkit [skip ci]` (design Step 9 summary, plan Step 11 summary) | `bkit [skip ci]` |
1143
+ | `chore({FID}): summary bkit [skip ci]` (design Step 10 summary, plan Step 11 summary) | `bkit [skip ci]` |
1142
1144
  | `fix({FID}): {description}` (debug Step 6 failure-remediate) | none — Step 8 pushes this commit directly so `fix(...)` becomes the CI-triggering HEAD (dodges `^chore:`-prefix Vercel-ignore rules and partial-tier demotion). `{description}` derived from first `DONE — Step` line in `debug-failure-remediate-{NORMAL_ATTEMPT}-log.md`. Debug Step 8 adds no intermediate `chore(...)` commit before push. |
1143
1145
  | `docs({FID}): ship bookkeeping` (ship Step 8, on `{SHIP_BRANCH}` before the merge) | `bkit [skip ci]` — CI is carried forward from `CODE_HEAD` (§ `/bkit-ship` — Validated-head carry-forward), so the push must not fire a run. |
1144
1146
  | `docs({FID}): ship DONE` (ship Step 15 close-workflow on `dev`, or its `ship-close/{FID}` PR squash subject) | `bkit [skip ci]` |
@@ -1245,7 +1247,7 @@ Without `acceptEdits` / wildcard allow surface, every `Bash`, `Edit`, `Write`, M
1245
1247
  | `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `git reset --hard:*`, `git clean -fd(x):*`, `git filter-branch:*`, `git checkout -- .:*`, `git restore .:*`, `git stash drop:*`, `git rebase -i:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`, `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops and secret reads. The `.env` rows are globs, not an enumeration of known filenames — an enumeration silently drops `.env.ci` / `.env.preview` / anything a consumer invents into `defaultMode`. The recursive `./**/` forms cover monorepo `apps/*` and `packages/*`. |
1246
1248
  | `deny` | `Bash(rm -rf /\* | ~/\* | $HOME/\*)`, `Bash(chmod -R 777 /:*)`, `Bash(git push --force)`, `Bash(git push --force \*)`, `Bash(git push -f)`, `Bash(git push -f \*)`, `Read(./\*\*/\*.pem)`, `Read(./\*\*/\*.p12)`, `Read(./\*\*/id_rsa)` | Hard-block catastrophic deletes, force-push and private-key reads. The force-push rows are split into exact + trailing-arg forms rather than the `--force:*` prefix idiom, because a prefix match also swallows `--force-with-lease` and would deny the allowed form. |
1247
1249
 
1248
- Shell `curl` / `wget` are **not** on the Claude `ask` list — they run under `Bash(*)`, with `deny`, the auto-mode classifier, and the advisory `.claude/hooks/bkit-guardrails.cjs` (PreToolUse, matcher `Bash`) as the backstops. Claude rules match a command prefix, not a URL host, so per-domain allows are inexpressible and the only options are blanket-ask or blanket-allow; blanket-ask forces a prompt on **every** shell fetch in **every** mode (a content-scoped `ask` is evaluated before the classifier and beats a matching `allow`), which a cloud session has nobody to answer. `WebFetch(domain:…)` governs the `WebFetch` **tool** only, never `curl` in `Bash`. Cursor gates by parsed URL host (`bkit-guardrails.cjs`), OpenCode via `curl *{domain}*` allows layered after a `curl *` ask. All four run an **allowlisted-host** fetch unprompted; on an **undeclared** host Cursor and OpenCode ask, Claude and Codex emit an advisory instead (Claude to avoid re-adding the prompt, Codex because it cannot prompt).
1250
+ Shell `curl` / `wget` are **not** on the Claude `ask` list — they run under `Bash(*)`, with `deny`, the auto-mode classifier, and the advisory `.claude/hooks/bkit-guardrails.cjs` (PreToolUse, matcher `Bash`) as the backstops. Claude rules match a command prefix, not a URL host, so per-domain allows are inexpressible and the only options are blanket-ask or blanket-allow; blanket-ask forces a prompt on **every** shell fetch in **every** mode (a content-scoped `ask` is evaluated before the classifier and beats a matching `allow`), which a cloud session has nobody to answer. `WebFetch(domain:…)` governs the `WebFetch` **tool** only, never `curl` in `Bash`. Cursor gates by parsed URL host (`bkit-guardrails.cjs`), OpenCode via `curl https://{host}/*` allows layered after a `curl *` ask (command-string glob: trailing flags or extra URLs still match, so it narrows rather than blocks). All four run an **allowlisted-host** fetch unprompted; on an **undeclared** host Cursor and OpenCode ask, Claude and Codex emit an advisory instead (Claude to avoid re-adding the prompt, Codex because it cannot prompt).
1249
1251
 
1250
1252
  **Shell-as-edit-channel.** `.agents/rules.md` requires edit/write tools for file contents so pre-edit gates see them; `sed -i` and redirects into source files route around every one. `bkit-guardrails.cjs` on Claude, Cursor and Codex flags both — **advisory, never blocking**, because the rule has sanctioned exceptions (generated files, bulk mechanical rewrites) and bkit's own plan workflow relies on one. Redirects into `/dev/null`, `$GITHUB_ENV`, `/tmp`, and `*.log` are deliberately silent. OpenCode has no script hook, so it is uncovered.
1251
1253
 
@@ -1311,14 +1313,14 @@ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxR
1311
1313
  | `prs` | `open`, `probe`, `merge`, `update-branch`, `checks`, `verbose-ci`, `scan-body`, `cross-check`, `transport-row` | PR create / lookup, squash merge (empty body, `--match-head`, auto-route suffix from `--label`), server-side base refresh, check-rollup classification (green when present and none failed/pending), debug's verbose-CI title, close-transport audit (`transport-row --scan --cross-check`) |
1312
1314
  | `issues` | `text`, `labels`, `comment` | `ISSUE_TEXT` join + cut, label arithmetic + board payload, comment bodies (MCP posts them) |
1313
1315
  | `runs` | `wait`, `dispatch`, `gate`, `revalidate`, `context`, `mirror`, `declared` | CI polls, CI-Dispatch Gate (`--file` / `--step` record its row, `--label` the re-trigger suffix), ship merge gate (`--pr` / `--squash-of` heads, `--snapshot`, `--record`), ship Step 9 re-validate, auto Step 1 context, release-PR mirror, CI-workflow presence |
1314
- | `tests` | `run` | deepest-declared `bkit:gate:*` run + saved log + verdict |
1316
+ | `tests` | `run`, `red`, `green` | deepest-declared `bkit:gate:*` run + saved log + verdict; build test-first: a task's red via `bkit:test:file` (row + test snapshot), a sub-plan's audit report (§ Test-first) |
1315
1317
  | `status` | `path`, `fold`, `route`, `meta`, `row` | status location, fold, routing state (`route --expect=field=value`), `workflow-meta` rows, typed audit rows the fold skips |
1316
1318
  | `counters` | `derive`, `rows`, `run`, `route`, `max` | attempt counters (step rows or typed audit rows), run number, `MAX_*` routing (`route --of=<step>:<pos>` derives the value) |
1317
1319
  | `steps` | `done`, `finish`, `verdict`, `gate`, `stub` | `step-done` row + commit; the one-call step ending (§ Step endings); verdict header read; mechanical gate items (placeholders, FID, lock, artifacts, the row's `attempt` / `strategy` / `scope`); seeding a versioned artifact with a PENDING header |
1318
1320
  | `ledgers` | `commit`, `union`, `only-bookkeeping` | path-scoped bookkeeping staging, ledger union, carry-forward check |
1319
1321
  | `context` | `clamp`, `clamp-log`, `ledger-scan`, `list-blocks`, `run-block`, `finalise` | artifact clamping, plan ledger scan, debug `context-fetch`, `bkit-cloud-bootstrap.sh` provision recipes (`list-blocks` → `provision`) |
1320
1322
  | `roadmap` | `fold`, `feature`, `mirror` | `docs/roadmap.md` re-render; append a phase's `kind:"feature"` row then re-render (`--strict`: exit 1 when it did not land); build / debug close: the row in the worktree, then on dev under the dev lock |
1321
- | `workstreams` | `parse`, `comment` | design Step 10 advisory comment |
1323
+ | `workstreams` | `parse`, `comment` | design Step 11 advisory comment |
1322
1324
  | `skills` | `prune` | ship Step 7 skill prune |
1323
1325
  | `ci` | `slop`, `prose`, `skip-token` | `slop:delta` gate (CI and `.husky/pre-push`; takes the base sha as `--base=` or its one bare argument), `lint:prose` gate (Vale over `--glob=` files), `.husky/pre-push` skip-CI token check |
1324
1326
  | `setup` | `protect-main` | `main` branch protection requiring `bkit.capstoneJob` |
@@ -1398,6 +1400,8 @@ Each gate is the previous gate plus its own tier, so the name and the value desc
1398
1400
 
1399
1401
  Dependency inspection is read-only, not a gate: `bkit:deps:outdated` and `bkit:deps:audit` exist so prompts stop hardcoding `pnpm outdated` / `pnpm audit`.
1400
1402
 
1403
+ `bkit:test:file` is not a gate either: it runs ONE test file — bkit appends the repo-relative path as its argument — and writes a JUnit report to the path in `$BKIT_TEST_REPORT`. `/bkit-build` reads that report for test-first (§ Test-first). Not seeded (no default runs one file on every stack); install's `test-file-script-missing` advisory hands over the line until it is declared. Call the runner directly: a task runner that caches results or runs dependent packages first breaks the one-file contract.
1404
+
1401
1405
  Agents and humans run the same scripts, so a green agent gate and a green `git push` mean the same thing. `bkit-ci.yml` deliberately stays off them: it needs per-step reporting, affected-package conditionals, and the heavier tiers the local gate excludes, so it calls `pnpm typecheck` / `pnpm test` / … directly.
1402
1406
 
1403
1407
  `lint:slop` is in no gate — `slop-scan scan` is report-only and never fails; `slop:delta` (`bkit ci slop`) is the enforcing gate. `bkit check` (mirror drift) sits in `.husky/pre-push` outside the gates: it validates the bkit install, not consumer source. `lint:prose` (`bkit ci prose`) scans a whole-repo file set, so it gates at pre-push, not pre-commit.
@@ -1428,6 +1432,24 @@ Build Step 7 runs the Step 14 gate after every sub-plan but the last, once `@bki
1428
1432
  - **Same gate as Step 14:** includes integration, plus the coverage floor where the consumer chains one into `bkit:gate:static-unit`. Without it, a sub-plan breaking what a later one assumes surfaces only at Step 14 — one large unattributed diff, budget partly spent.
1429
1433
  - **Strict, no exceptions:** a boundary is where a build can stop (verify budget exhausted, session lost, `/bkit-ship` resume) → it must hold a validated tree. No expected-red declaration. Red boundaries are ordering defects (signature change split from callers, deletion before replacement, tests deferred to a later task): `@bkit-plan-complexity-split` orders the partition to keep every boundary green, merging sub-plans when it cannot. Add an exception mechanism only once a real case shows a legitimate red boundary.
1430
1434
 
1435
+ ### Test-first
1436
+
1437
+ Every plan task carries `**Test first:**` — one or more `;`-separated tests, each a test file + test name, or `n/a — {reason}` (no behaviour change, or E2E / `@live` tier only; plan scope-check rejects an unjustified `n/a`). Build proves each named test failed before its task's code existed.
1438
+
1439
+ <!-- prettier-ignore -->
1440
+ | Moment | Who | What is checked |
1441
+ | --- | --- | --- |
1442
+ | Red (Step 6, per planned test) | `@bkit-build-plan-execute` runs `bkit tests red`, log `build-task-red-N-{task}-{test position}.md` | the named test ran and failed in the `bkit:test:file` JUnit report on a non-zero exit. Otherwise exit 1, nothing recorded, `refused` = `no-report` / `not-run` / `passed` / `skipped` / `exit-mismatch`. Records a `build-task-red` row (`task`, `test`, `testName`, `testBlob`, `failure`; `--commit=none`) plus the runner log and a `.snapshot` copy of the test file. An earlier red for the same task + test + name with an unchanged test file stands: exit 0, `already: true`, nothing runs. |
1443
+ | Green (Step 7, before verify) | orchestrator runs `bkit tests green` | per planned test: a red row matching task + test file + test name (a task red for an unplanned test → `red-mismatch`, naming whether that recorded test passes now); test file unchanged since its snapshot (diff in report when not); the named test passes now. Writes `build-tests-green-N-{VERIFY_ATTEMPT}.md` (`Enforced` / `Gaps` header). |
1444
+ | Judgement (Step 7) | `@bkit-build-plan-verify` | `not-green` → fixable; `test-changed` → judged from the diff (added tests / formatting → no gap); `red-mismatch` → planned test renamed or moved and passing now → no gap, nor for its `not-green`; `no-red` on a task the plan-currency report marks `Broken` (already landed) and execute logs `DONE — already landed` → no gap; other `no-red`, `no-test-first`, `test-first-malformed`, `red-evidence-missing` → not fixable. |
1445
+
1446
+ - **The report, never the exit code:** a misspelled path, a syntax error, and an import of unwritten code all exit non-zero like a real failure; a test-name filter matching nothing exits 0 with the test skipped. Only the named test's own outcome counts. A runner reporting a load error as one case named after the file never matches the test name.
1447
+ - **Stub first:** tests failing only because the code they import does not exist never show their assertions failing, so the agent writes stubs and each red is an assertion.
1448
+ - **Hash in the row, snapshot beside the log:** both ride the plan-execute commit and survive push and resume; nothing pins a git object.
1449
+ - **Resume-safe:** execute never ticks tasks, so a resumed build re-runs execute from the first task; each earlier red stands because its test file is unchanged. Refused as `passed` → the task's code already exists → `BLOCKED`, never code undone to force a red.
1450
+ - **Already landed:** a task plan-currency marks `Broken` because its work already landed gets no red (execute logs `DONE — already landed`); verify reads the plan-currency report and maps that `no-red` to no gap.
1451
+ - **Not enforced, never silent:** no plan file (brief build), a plan with no `Test first:` lines, or no `bkit:test:file` → `tests green` exits 0 with `Enforced: false` and the reason; verify notes it. `tests red` exit 3 (script undeclared) → execute logs `red not enforced` and continues.
1452
+
1431
1453
  ### Tracker issue-create return guard
1432
1454
 
1433
1455
  When tracker call creates issue, MUST return non-empty `id`. Empty/null → Failure Path `Tracker issue create returned no id`.
@@ -1485,7 +1507,7 @@ Pipeline writes structured ledgers at `docs/` root. Each has strict sole-writer
1485
1507
  | `docs/knowledge.jsonl` | `key` | `@bkit-build-plan-gaps-remediate`, `@bkit-build-challenge-remediate`, `@bkit-debug-failure-remediate` | After verified fix |
1486
1508
  | `docs/decisions.jsonl` | `key` | `@bkit-debug-failure-remediate` (forced arch) | At decision time — the design phase reads ADRs, never authors them |
1487
1509
  | `.bkit/issues.jsonl` | `key` (the FID) | design / plan / build / debug closes; ship Step 6 (worktree, rides the PR) | Every close / ship Step 6 |
1488
- | `docs/deferrals.jsonl` | `key` | `@bkit-design-generate` (out-of-scope features), `@bkit-plan-generate` (out-of-scope ideas), `@bkit-plan-update` (scope expansions from `/bkit-plan` Step 8), `@bkit-debug-abort-handover` (handover context), `@bkit-ship-deferred-sweep` (adjudication — same-`key` `reason` = `unjustified`) | `/bkit-design` Step 4, `/bkit-plan` Steps 3 & 8, `/bkit-ship` Step 5, Failure Path handover |
1510
+ | `docs/deferrals.jsonl` | `key` | `@bkit-design-generate` (out-of-scope features), `@bkit-plan-generate` (out-of-scope ideas), `@bkit-plan-update` (scope expansions from `/bkit-plan` Step 8), `@bkit-debug-abort-handover` (handover context), `@bkit-ship-deferred-sweep` (adjudication — same-`key` `reason` = `unjustified`) | `/bkit-design` Step 5, `/bkit-plan` Steps 3 & 8, `/bkit-ship` Step 5, Failure Path handover |
1489
1511
 
1490
1512
  All other agents document blockers/out-of-scope in own log file (Plan Execution / Challenge Remediation / etc — each subagent H1 for canonical output name) — workflow reads at step boundaries, decides tracker mirror.
1491
1513
 
@@ -14,9 +14,10 @@
14
14
  // - FAIL OPEN: a single top-level catch swallows every error (the process exits
15
15
  // 0 with whatever was already emitted). Normal control paths use existence
16
16
  // guards, never try/catch; that catch is the only error sink.
17
- // - SUBAGENTS INCLUDED: a subagent edit is an edit. Dedup is per (session, file)
18
- // and a subagent carries its own session id, so it gets its own checklist.
19
- // - DEDUP: warns once per (session, file); state lives in the OS temp dir keyed
17
+ // - SUBAGENTS INCLUDED: a subagent edit is an edit. Dedup is per (session, agent,
18
+ // file): a subagent shares its parent's session_id and carries its own agent_id,
19
+ // so it gets its own checklist.
20
+ // - DEDUP: warns once per (session, agent, file); state lives in the OS temp dir keyed
20
21
  // by session_id and is GC'd after 24h. Never writes into the consumer repo.
21
22
  //
22
23
  // MODES (BKIT_GATEGUARD env var):