@cbartens/bkit 5.2.3 → 5.3.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 (254) hide show
  1. package/.bkit/README.md +29 -12
  2. package/.bkit/core/.agents/context.md +1 -1
  3. package/.bkit/core/.agents/docs.md +1 -1
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
  5. package/.bkit/core/.agents/rules.md +11 -0
  6. package/.bkit/core/.bkit/README.md +28 -11
  7. package/.bkit/core/.bkit/cloud.md +9 -8
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +15 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +345 -0
  12. package/.bkit/core/.bkit/prompts.md +88 -73
  13. package/.bkit/core/.bkit/providers.md +41 -22
  14. package/.bkit/core/.bkit/templates.md +125 -18
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +51 -45
  17. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
  18. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
  19. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
  20. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +9 -1
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +10 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +22 -10
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +29 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +11 -3
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +19 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -5
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +14 -5
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -1
  55. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  56. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  57. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  58. package/.bkit/core/engine/checks/after/github.ts +29 -120
  59. package/.bkit/core/engine/checks/after/index.ts +2 -2
  60. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  61. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  62. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  63. package/.bkit/core/engine/checks/before/index.ts +7 -43
  64. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  65. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  66. package/.bkit/core/engine/checks/status-holes.ts +4 -5
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +70 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  70. package/.bkit/core/engine/cli.ts +39 -16
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +17 -16
  73. package/.bkit/core/engine/commands/harvest.ts +12 -12
  74. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  75. package/.bkit/core/engine/commands/install/install.ts +62 -126
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +58 -53
  78. package/.bkit/core/engine/commands/lib.ts +35 -10
  79. package/.bkit/core/engine/commands/tips.ts +8 -5
  80. package/.bkit/core/engine/commands/workflow/branches.ts +65 -11
  81. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  82. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  83. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  84. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  85. package/.bkit/core/engine/commands/workflow/repo.ts +18 -4
  86. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  87. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  88. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  89. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  90. package/.bkit/core/engine/commands/workflow/workflows.ts +19 -17
  91. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  92. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  93. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  94. package/.bkit/core/engine/install/manifest.ts +14 -7
  95. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  96. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  97. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  98. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  99. package/.bkit/core/engine/install/modules/core.ts +91 -70
  100. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  101. package/.bkit/core/engine/install/modules/index.ts +7 -1
  102. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  103. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  104. package/.bkit/core/engine/install/placeholders.ts +3 -18
  105. package/.bkit/core/engine/install/write.ts +59 -12
  106. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  107. package/.bkit/core/engine/render/hosts.ts +47 -67
  108. package/.bkit/core/engine/render/models.ts +29 -11
  109. package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
  110. package/.bkit/core/engine/shared/branches.ts +13 -0
  111. package/.bkit/core/engine/shared/egress.ts +3 -3
  112. package/.bkit/core/engine/shared/json.ts +18 -1
  113. package/.bkit/core/engine/shared/package-json.ts +63 -0
  114. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  115. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  116. package/.bkit/core/engine/shared/settings.ts +36 -0
  117. package/.bkit/core/engine/shared/timeouts.ts +6 -0
  118. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  119. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  120. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  121. package/.bkit/core/prompts/bkit-audit-generate.md +65 -10
  122. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  123. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  124. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  125. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  126. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  127. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  128. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  130. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  132. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  133. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  134. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  135. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  136. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  137. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  138. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  139. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  140. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  141. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  142. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  143. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  144. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  145. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  146. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  148. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  149. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  150. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  151. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  152. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  153. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  154. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  155. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  156. package/.bkit/core/workflows/bkit-build.md +4 -4
  157. package/.bkit/core/workflows/bkit-debug.md +70 -34
  158. package/.bkit/core/workflows/bkit-design.md +3 -3
  159. package/.bkit/core/workflows/bkit-plan.md +12 -5
  160. package/.bkit/core/workflows/bkit-ship.md +6 -6
  161. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  162. package/.bkit/shared/.claude/settings.json +18 -0
  163. package/.bkit/shared/.cursor/mcp.json +2 -1
  164. package/.bkit/shared/.opencode/opencode.json +19 -1
  165. package/.bkit/shared/docs/deployments.md +20 -4
  166. package/.bkit/shared/docs/security.md +8 -6
  167. package/.bkit/shared/docs/testing.md +9 -5
  168. package/.bkit/templates/.cursor/Dockerfile +30 -16
  169. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  170. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  171. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  172. package/.bkit/templates/.github/renovate.json5 +91 -12
  173. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  174. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  175. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  176. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  177. package/.bkit/templates/.husky/pre-push +15 -3
  178. package/.bkit/templates/.oxlintrc.json +21 -0
  179. package/.bkit/templates/docs/capabilities.md +1 -1
  180. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  181. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  182. package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
  183. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  184. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  185. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  186. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  187. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  188. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  189. package/CHANGELOG.md +67 -3
  190. package/README.md +258 -129
  191. package/dist/checks/after/auth.js +10 -11
  192. package/dist/checks/after/ci-yml.js +11 -14
  193. package/dist/checks/after/github.js +32 -125
  194. package/dist/checks/after/index.js +3 -2
  195. package/dist/checks/after/managed.js +8 -24
  196. package/dist/checks/after/tools.js +3 -16
  197. package/dist/checks/before/context-fetch.js +1 -21
  198. package/dist/checks/before/index.js +6 -42
  199. package/dist/checks/before/mcp.js +14 -9
  200. package/dist/checks/before/repo.js +8 -11
  201. package/dist/checks/status-holes.js +5 -6
  202. package/dist/checks/tips/catalogue.js +60 -18
  203. package/dist/checks/tips/detect.js +41 -2
  204. package/dist/checks/tips/index.js +25 -5
  205. package/dist/cli.js +34 -14
  206. package/dist/commands/analysis.js +21 -5
  207. package/dist/commands/comply.js +20 -18
  208. package/dist/commands/harvest.js +12 -13
  209. package/dist/commands/install/doctor.js +55 -23
  210. package/dist/commands/install/install.js +62 -118
  211. package/dist/commands/install/uninstall.js +165 -31
  212. package/dist/commands/install/upgrade.js +55 -49
  213. package/dist/commands/lib.js +32 -10
  214. package/dist/commands/tips.js +6 -3
  215. package/dist/commands/workflow/branches.js +57 -13
  216. package/dist/commands/workflow/counters.js +17 -7
  217. package/dist/commands/workflow/fids.js +39 -0
  218. package/dist/commands/workflow/ledgers.js +3 -1
  219. package/dist/commands/workflow/prs.js +3 -3
  220. package/dist/commands/workflow/repo.js +16 -4
  221. package/dist/commands/workflow/roadmap.js +4 -4
  222. package/dist/commands/workflow/runs.js +5 -5
  223. package/dist/commands/workflow/steps.js +1 -0
  224. package/dist/commands/workflow/tests.js +16 -3
  225. package/dist/commands/workflow/workflows.js +19 -18
  226. package/dist/commands/workflow/workstreams.js +2 -1
  227. package/dist/commands/workflow/worktrees.js +4 -5
  228. package/dist/install/cloud-env.js +10 -23
  229. package/dist/install/manifest.js +14 -7
  230. package/dist/install/modules/antigravity.js +15 -26
  231. package/dist/install/modules/claude.js +17 -21
  232. package/dist/install/modules/cloud.js +6 -2
  233. package/dist/install/modules/codex.js +15 -29
  234. package/dist/install/modules/core.js +82 -63
  235. package/dist/install/modules/cursor.js +6 -9
  236. package/dist/install/modules/index.js +6 -1
  237. package/dist/install/modules/opencode.js +41 -72
  238. package/dist/install/network-allowlist.js +62 -0
  239. package/dist/install/placeholders.js +3 -16
  240. package/dist/install/write.js +55 -15
  241. package/dist/ledgers/telemetry.js +5 -4
  242. package/dist/render/hosts.js +30 -55
  243. package/dist/render/models.js +20 -9
  244. package/dist/shared/bkit-latest.js +150 -0
  245. package/dist/shared/branches.js +11 -0
  246. package/dist/shared/egress.js +0 -2
  247. package/dist/shared/json.js +14 -0
  248. package/dist/shared/package-json.js +61 -0
  249. package/dist/shared/package-roots.js +0 -8
  250. package/dist/shared/protected-paths.js +5 -122
  251. package/dist/shared/settings.js +18 -1
  252. package/dist/shared/timeouts.js +6 -0
  253. package/package.json +21 -17
  254. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -24,7 +24,7 @@ Canonical source: `.bkit/core/workflows/`. `bkit install` regenerates `.claude/c
24
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
- ├── bkit-debug.md # Workflow 4/5 — 10 steps; normal / soak modes
27
+ ├── bkit-debug.md # Workflow 4/5 — 11 steps; normal / soak modes, `[repro]`
28
28
  ├── bkit-ship.md # Workflow 5/5 — 15 steps; merge → archive → In Review (human closes)
29
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
  ```
@@ -49,7 +49,7 @@ Choose by the state of the work. Procedure stays in the command file and in § P
49
49
  | `/bkit-design` | The approach is still open — options, trade-offs, or questions nobody has answered. No design doc yet, or the one on disk no longer matches the decision. | The issue is already researched and settled. A design doc already says that and still holds — edit the doc. The change is obvious enough to plan or build. |
50
50
  | `/bkit-plan` | The approach is settled and there is no plan an implementer can execute. | A plan already exists and still fits — amend that plan. The approach itself is still open. |
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
- | `/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. |
52
+ | `/bkit-debug` | Tests or CI are actually failing, and the cause is not already known. | Nothing is red and no `[repro]`. 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
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
 
@@ -143,7 +143,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
143
143
  - **`FID` slug assertions (`bkit-auto` Step 1, `bkit runs context`):** `bkit fids` holds the regexes (`runs context` checks a CI_DEV slug against the `any` allowlist and recovers a PR's FID with the same marker / branch parsing as `bkit fids parse`); they are allowlists (canonical `^[0-9]+-[a-z0-9-]+$` for GitHub issue-prefixed slugs, `^[a-z]+-[0-9]+-[a-z0-9-]+$` for Linear-prefixed slugs, safe `^[a-z0-9][a-z0-9-]*$` for the no-tracker + branch-derive fallback, tracker-agnostic `^([0-9]+|[a-z]+-[0-9]+)-[a-z0-9-]+$` for the CI_DEV slug arg, `--tracker=any`). They reject path traversal and shell metacharacters in the untrusted PR-body marker before `{FID}` reaches any filesystem path or downstream dispatch. `bkit fids parse` tries the marker first and falls back to the `feat/{FID}` branch only when the marker is missing or malformed, and the fallback must resolve `{ISSUE_ID}` too — from the `{FID}` slug (github: leading numeric segment; linear: first two dash-segments, uppercased), each behind its own allowlist. A fallback that recovers only `{FID}` is dead code on any tracker-wired repo: the Step 1 comment keys every tracker call on `{ISSUE_ID}` and Gate 1 asserts it non-empty, so the run reaches **Failure Path** whatever `{FID}` says. Under the no-tracker variant `{ISSUE_ID}` stays empty by design and the comment is skipped. The branch-derive accepts `feat/**` only — the cloud router's `workflow_run` surface is `feat/**` plus `dev`, and no bkit phase mints any other branch prefix.
144
144
  - **Step 1 FID check in every phase workflow:** design, plan, build, debug and ship run `bkit fids check` on the resolved `FID` at Step 1 — whichever sub-step resolved it (session prompt, branch, existing logs, mint) and under every tracker, `none` included (the safe allowlist). A bad `FID` then fails before any work, not at `bkit prs open`, which keeps its own check as a backstop.
145
145
  - **`bkit-auto` CI_DEV mode (`bkit runs context`):** a post-merge `dev` CI failure has no open PR to read, so `bkit-cloud.yml` passes the `{FID}` slug instead of a PR number and `runs context` discriminates on `{ARG}` shape (numeric → PR, else slug). The slug is untrusted at the same level as the PR-body marker — it arrives from a commit-message scope on `dev` and the cloud-side `ARG` guard permits `.` and `/` — so the `any` allowlist is asserted (exit 9) before `{FID}` reaches `docs/plans/{YYYYMM}/logs/{FID}/`, `.worktrees/{FID}`, or the `/bkit-debug {FID} {REF}` dispatch. `prNumber`, `prUrl` and `runId` are printed null rather than filled with a `(merged)` sentinel: the Step 1 comment drops its PR and run links in CI_DEV, and a sentinel would render a broken link. The open check (exit 7) and the CI-run lookup (exit 8) are on the CI path only.
146
- - **Auto-route marker derivation is fence-local (build Step 18, debug Step 10, ship Step 10):** every site re-reads the issue's labels through the tracker MCP and hands them as `{LABEL_FLAGS}` to the command that writes the commit — `bkit workflows close --label=` (build / debug close commit), `bkit runs dispatch --label=` (the gate's re-trigger commit), `bkit prs merge --label=` (ship's squash subject) — which appends ` bkit [auto route]` on an exact `bkit:auto` match; no `gh` call. Two dead shapes preceded it and must not return: `${LABELS:-}` (an MCP-derived template value that is never assigned as a shell variable, so it always expanded empty), and a `mktemp` path published via `$GITHUB_ENV` (the runner applies `$GITHUB_ENV` only BETWEEN Action steps, while every agent Bash tool call in a cloud dispatch runs inside the one `claude-code-action` step). The exact label match mirrors the kill switch in `bkit-cloud.yml`, the marker's only consumer, so `bkit:auto-paused` / `no-bkit:auto` cannot arm the route. No tracker (`none`) passes no labels and leaves the subject unchanged. The marker becomes permanent `dev` history; that is inherent to reading `head_commit.message` and is not cleaned up later. Any resulting cross-session `/bkit-debug` dispatch loop is capped by `MAX_DEV_DISPATCH_ATTEMPTS` (a workflow-level env in `bkit-cloud.yml`, held equal to `bkit counters max` by `counters.test.ts`).
146
+ - **Auto-route marker derivation is fence-local (build Step 18, debug Step 11, ship Step 10):** every site re-reads the issue's labels through the tracker MCP and hands them as `{LABEL_FLAGS}` to the command that writes the commit — `bkit workflows close --label=` (build / debug close commit), `bkit runs dispatch --label=` (the gate's re-trigger commit), `bkit prs merge --label=` (ship's squash subject) — which appends ` bkit [auto route]` on an exact `bkit:auto` match; no `gh` call. Two dead shapes preceded it and must not return: `${LABELS:-}` (an MCP-derived template value that is never assigned as a shell variable, so it always expanded empty), and a `mktemp` path published via `$GITHUB_ENV` (the runner applies `$GITHUB_ENV` only BETWEEN Action steps, while every agent Bash tool call in a cloud dispatch runs inside the one `claude-code-action` step). The exact label match mirrors the kill switch in `bkit-cloud.yml`, the marker's only consumer, so `bkit:auto-paused` / `no-bkit:auto` cannot arm the route. No tracker (`none`) passes no labels and leaves the subject unchanged. The marker becomes permanent `dev` history; that is inherent to reading `head_commit.message` and is not cleaned up later. Any resulting cross-session `/bkit-debug` dispatch loop is capped by `MAX_DEV_DISPATCH_ATTEMPTS` (a workflow-level env in `bkit-cloud.yml`, held equal to `bkit counters max` by `counters.test.ts`).
147
147
  - **Host skill mirrors are in the `--scope=full` bookkeeping pathspec:** `npx skills remove` deletes `.claude/skills` / `.cursor/skills` / `.opencode/skills` alongside `.agents/skills/<name>`, so the close staging must be able to carry those deletions. `bkit ledgers commit` builds its pathspec via `git ls-files -z --cached --others --exclude-standard`, so an unmatched glob is empty output (never fatal) and `--cached` still emits a tracked-but-deleted mirror, so the deletion stages cleanly — a claude-only consumer with no `.cursor` / `.opencode` mirror sweeps zero for those globs rather than aborting. Without them the prune commit holds only `.agents/skills` + `skills-lock.json` and the mirror deletions leak into the working tree, where the next unrelated staging sweeps them into a foreign commit.
148
148
  - **Ship Step 7 never prunes `bkit-*` skills:** they are bkit render output (Codex host workflow entry points), absent from `.agents/skills.md`. `bkit skills prune` keeps every `bkit-*` skill; without that guard every ship uninstalls them. A missing `.agents/skills.md` skips the prune with a warning (`skipped: "no-registry"`) rather than uninstall everything; a failed uninstall is warned and listed in `failed`. Both exit 0: pruning is housekeeping, so the ship carries on and still closes.
149
149
  - **Staging routes through `bkit ledgers commit`, never a shell pathspec:** a pathspec rebuilt inline per block with unquoted word-splitting and an `ls docs/plans/*/logs/*/*.jsonl docs/*.jsonl .bkit/*.jsonl` glob ABORTS under zsh when unmatched — silently dropping every ledger in a fresh consumer repo, and (worse) swallowing a failed `git add` into a false "nothing to commit" success, since nothing in these blocks sets `set -e`. `bkit ledgers commit` builds the pathspec with `git ls-files` — an unmatched glob is empty output, never an abort — and stages/commits it via `--pathspec-from-file --pathspec-file-nul` rather than a re-interpolated shell string. It refuses to reach `commit` when that list is empty (exit 6): `git commit --pathspec-from-file=<empty file>` does not commit nothing, it silently commits whatever is ALREADY staged in the index. Ship's markdown stages through it at the B2 conflict-resolve stage and the Step 8 bookkeeping commit, each stopping the step on failure (`.bkit/core/engine/audits/workflows/ship-invariants.test.ts`); the Failure Path flush and the Close flush run the same code inside `bkit workflows handover --flush` / `bkit workflows close --flush`. `commands/workflow/ledgers.test.ts` covers the command itself.
@@ -602,6 +602,8 @@ baseRef: origin/dev
602
602
 
603
603
  Plan docs add 2 fields, read from the design doc's own anchor: `designPath` (design this plan targets), `designBaseSha` (that doc's own `baseSha`).
604
604
 
605
+ Every stamp (design, plan, sub-plan, audit report) adds 2 more when `.bkit/version` exists: `bkitVersion` (its `pinnedVersion`) and `bkitLatest` (newest published release, empty when unknown; lookup per § Invocation). `bkitVersion` older → the stamp also writes one visible line under the block: `> **Outdated bkit:** generated with bkit X while Y was out … <!-- bkit:outdated -->`. Tool-owned like the block: every re-stamp drops it, rewrites it only while still outdated. Neither line is a capital-letter `Key:` line, so `readHeader` ignores both.
606
+
605
607
  **Orchestrator-owned:** generate subagents have no `Bash` → can't compute a SHA. Orchestrator records `baseSha` at Step 2 (`bkit worktrees setup` → `bkit runtime row --base-sha=` → `runtime-resolved.baseSha`), reads it back at Close Workflow (`bkit runtime assert`) and stamps the canonical with `bkit branches anchor-stamp` (idempotent; plan adds `--design=`); `bkit branches anchor-read` reads it. Hand-written block from either subagent → stripped, replaced, never trusted.
606
608
 
607
609
  **May be empty:** `baseSha` empty = `merge-base` unresolvable, not a failure. `designPath`/`designBaseSha` empty = no design, or design predates this mechanism. Pre-change docs carry no block — `bkit branches anchor-read` returns null fields, not an error.
@@ -699,6 +701,7 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
699
701
  | 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 |
700
702
  | Ship CI wait | 1800s / 30s | Step 9 completion poll budget / interval (`SHIP_CI_WAIT_TIMEOUT_S` / `SHIP_POLL_INTERVAL_S`) |
701
703
  | Ship presence probe | 6 x 10s | Step 9 run-at-head probe before any dispatch (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`) |
704
+ | Newest-bkit lookup | 5s / 86400s / 3600s | Registry query limit / answer reuse / failure reuse for the outdated-bkit check (`BKIT_LATEST_LOOKUP_TIMEOUT_S` / `BKIT_LATEST_CACHE_S` / `BKIT_LATEST_RETRY_S`) |
702
705
 
703
706
  `MAX_*` live in `THRESHOLDS` (`commands/workflow/counters.ts`; `bkit counters max`) and are referenced by name in retry checks (`bkit counters route --limit=`) — never a literal `3`. Waits live in `TIMEOUTS` (`.bkit/core/engine/shared/timeouts.ts`).
704
707
 
@@ -760,12 +763,12 @@ Step 10's `bkit prs merge --label=…` appends ` bkit [auto route]` to the squas
760
763
  **Placement (mode-dependent):**
761
764
 
762
765
  - `/bkit-build` Step 18: `bkit:auto` re-read before close-workflow commit. Present → subject `chore({FID}): close-workflow bkit [auto route]`. Close-workflow = feat-branch HEAD firing CI → gate checks `head_commit.message`.
763
- - `/bkit-debug` Step 10 PR-mode: same — marker on close-workflow (sub-step 2). Create-pr (sub-steps 4-5) does not run (`TRIGGER_PR=0`).
764
- - `/bkit-debug` Step 10 local-mode: `bkit:auto` re-read before the create-pr commit (sub-step 5). Marker on create-pr = CI-triggering HEAD local-mode.
766
+ - `/bkit-debug` Step 11 PR-mode: same — marker on close-workflow (sub-step 2). Create-pr (sub-steps 4-5) does not run (`TRIGGER_PR=0`).
767
+ - `/bkit-debug` Step 11 local-mode: `bkit:auto` re-read before the create-pr commit (sub-step 5). Marker on create-pr = CI-triggering HEAD local-mode.
765
768
  - `/bkit-ship` Step 4 (B1/B2, feat-branch HEAD): no placement — see "Ship does not carry the marker on the feat-branch HEAD" above. B1 (`bkit prs update-branch`) and B2 (`chore({FID}): conflict-resolve bkit [skip ci]`) both leave an unmarked HEAD by construction; there is no dev-sync merge to mark. Cloud gate in-job `bkit:auto` re-check = live kill switch.
766
769
  - `/bkit-ship` Step 10 (squash-merge subject, `dev`): labels re-read from the tracker MCP in the merge sub-step and passed to `bkit prs merge` as `{LABEL_FLAGS}` — never carried forward from Step 1's `{LABELS}`. `bkit:auto` present → ` bkit [auto route]` appended to the subject. This is the commit that fires the post-merge `dev` free-tier gate — the only marker `/bkit-ship` places.
767
770
 
768
- **Why re-read must precede commit:** kill-switch re-read at build Step 18 / debug Step 10 sub-step 8 runs after commit+push — cannot source marker on existing commit. Fresh `bkit:auto` read before commit construction = authoritative "at close time" signal.
771
+ **Why re-read must precede commit:** kill-switch re-read at build Step 18 / debug Step 11 sub-step 8 runs after commit+push — cannot source marker on existing commit. Fresh `bkit:auto` read before commit construction = authoritative "at close time" signal.
769
772
 
770
773
  **Coexistence with `bkit [verbose ci]`:** debug local-mode both on same subject: `chore({FID}): close-workflow bkit [verbose ci] bkit [auto route]`. HEAD-Subject Assertion: both legitimate. Gate reads `bkit [auto route]` via `contains(head_commit.message, 'bkit [auto route]')` — `bkit [verbose ci]` does not interfere.
771
774
 
@@ -791,13 +794,13 @@ GitHub Actions: `push.head_commit.message` vs `pull_request.title`. Template bki
791
794
  | `LOCAL` | Debug invoked on a `dev` / `main` failure, or a feature branch with no open PR | `push` event reads `head_commit.message` | **Commit message** | `bkit [verbose ci]` appended conditionally via `VERBOSE_SUFFIX=""; [ "$PUSH_MODE" = "LOCAL" ] && VERBOSE_SUFFIX=" bkit [verbose ci]"` immediately before the relevant commits in `bkit-debug.md` (Step 6 `fix`, Step 7 `soak`, Step 9 `summary`, Step 10 `close-workflow`, Step 10 `create-pr`). PR-mode runs skip the suffix (`pull_request` events ignore commit messages). Self-clearing per push — non-debug pushes return to default. |
792
795
  | `PR` | Debug invoked on a feature branch with an open PR (the dominant case) | `pull_request.synchronize` reads `pull_request.title` | **PR title** | Step 8 (Push Remediation) runs `gh pr edit --title` to idempotently append `bkit [verbose ci]` to the PR title (skip if already present) immediately before the push. Step 10 (Close Workflow) sub-step 1 strips it via `sed` + `gh pr edit` on a successful close. Failure Path / handover **do not strip** — the post-handover human investigator wants continued verbose CI. |
793
796
 
794
- Both paths idempotent — re-run skips when present; orphan markers cleaned by next debug Step 10 strip on successful close.
797
+ Both paths idempotent — re-run skips when present; orphan markers cleaned by next debug Step 11 strip on successful close.
795
798
 
796
- **Close PR-create decision:** the Step-1 `PUSH_MODE` does **not** gate PR creation — Step 10 probes live PR state (`bkit prs probe --head="{BRANCH}" --base=dev`), sets `TRIGGER_PR` from `{PR_OPEN}`, adopts a mid-run PR (`bkit prs open --existing=reuse`) rather than blind-creating into the Failure Path, then the gate asserts the dispatched `pull_request` run on every feature-branch close. `PUSH_MODE` = marker-surface hint only.
799
+ **Close PR-create decision:** the Step-1 `PUSH_MODE` does **not** gate PR creation — Step 11 probes live PR state (`bkit prs probe --head="{BRANCH}" --base=dev`), sets `TRIGGER_PR` from `{PR_OPEN}`, adopts a mid-run PR (`bkit prs open --existing=reuse`) rather than blind-creating into the Failure Path, then the gate asserts the dispatched `pull_request` run on every feature-branch close. `PUSH_MODE` = marker-surface hint only.
797
800
 
798
801
  **Invariant:** a successful debug/build close leaves a PR to `dev` (created or adopted) with a run the gate asserts; the Failure Path leaves the `[skip ci]` handover + abort-guard and dispatches no CI.
799
802
 
800
- **Cleanup invariant:** PR-title marker stripped on successful `/bkit-debug` close (Step 10, `PUSH_MODE = PR`). Failure Path / handover preserve intentionally — post-handover investigator wants continued verbose CI. Cleanup via: (a) next `/bkit-debug` close success, (b) manual strip, (c) PR merge — squash subject inherits `bkit [verbose ci]` → one post-merge dev CI verbose (harmless, recovery evidence).
803
+ **Cleanup invariant:** PR-title marker stripped on successful `/bkit-debug` close (Step 11, `PUSH_MODE = PR`). Failure Path / handover preserve intentionally — post-handover investigator wants continued verbose CI. Cleanup via: (a) next `/bkit-debug` close success, (b) manual strip, (c) PR merge — squash subject inherits `bkit [verbose ci]` → one post-merge dev CI verbose (harmless, recovery evidence).
801
804
 
802
805
  **Manual override:** append `bkit [verbose ci]` to any commit message or PR title — env block honours both. Debug auto-propagation removes manual need for dominant retry-evidence case.
803
806
 
@@ -822,12 +825,12 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
822
825
  | 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. |
823
826
  | 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. |
824
827
  | 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. |
825
- | 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. |
826
- | 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. |
828
+ | 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), the `**Parent design:**` line each workstream issue carries, plus the design link. `NEVER auto-trigger`. Never creates an issue, never comments on another issue, never sets blockers. |
829
+ | 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 what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
827
830
 
828
831
  **Hard stop in Step 12 caution block:** "Design requires human review. Do not invoke `/bkit-plan`."
829
832
 
830
- **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.
833
+ **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 (a workstream issue); absent → the design made on the same issue, which plan shares the FID with (`bkit fids find` resolves it); neither → standalone plan. `/bkit-build` Step 1 honours blocker edges a human has set.
831
834
 
832
835
  ### `/bkit-plan` — 12 steps
833
836
 
@@ -836,7 +839,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
836
839
  <!-- prettier-ignore -->
837
840
  | Step | Subagent(s) | Notes |
838
841
  | --- | --- | --- |
839
- | 1 — Start Workflow | — | Pre-flight: fetch `origin/dev`. Set label `Plan`, `In Progress`. Parse `**Parent design:**` from `DESCRIPTION` → set `PARENT_FID` when the issue body carries the marker; **else** leave empty (standalone plan run on issue input alone). Parse `docs/audits/{YYYYMM}/*.md` paths from `DESCRIPTION` and the session prompt → `AUDIT_PATHS` (absent → empty; a named path that is not a file → Failure Path). no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
842
+ | 1 — Start Workflow | — | Pre-flight: fetch `origin/dev`. Set label `Plan`, `In Progress`. Parse `**Parent design:**` from `DESCRIPTION` → set `PARENT_FID` when the issue body carries the marker; **else** `bkit fids design` → the feature's own `{FID}-design.md` when it exists (a design run on the same issue); **else** leave empty (standalone plan run on issue input alone; a change-shape issue, `.bkit/trackers.md` § Issue shapes, then supplies the Acceptance Scenario). Parse `docs/audits/{YYYYMM}/*.md` paths from `DESCRIPTION` and the session prompt → `AUDIT_PATHS` (absent → empty; a named path that is not a file → Failure Path). no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
840
843
  | 2 — Worktree Setup | — | `bkit worktrees setup` on `feat/{FID}` (dependencies installed; install failure → **Failure Path**); `plan-input-{RUN}.md` = session prompt + `ISSUE_TEXT` (`bkit issues text`). **If** `PARENT_FID` set → also concatenates `{PARENT_FID}-design.md` (missing file → Failure Path). **If** `AUDIT_PATHS` set → append each report in order (missing file → Failure Path). Standalone plans with neither skip both appends. Superseded plan is not appended here — it goes to Step 3 only. |
841
844
  | 3 — Generate Plan | `@bkit-plan-generate` | Reads `docs/templates/bkit-plan.md` (canonical plan template), `plan-input-{RUN}.md`, superseded `{YYYYMM}/{FID}-plan.md` (if any). Superseded plan = context only, never a constraint; supplied HERE only — not via `plan-input-{RUN}.md`, which the review triplet + summary also read. Audit reports in `plan-input-{RUN}.md`: **If** the input names which findings → the plan covers only those; the rest of each report is context only, not backlog. Writes `plan-generate.md` log + `docs/plans/{YYYYMM}/{FID}-plan.md`. |
842
845
  | 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. |
@@ -847,7 +850,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
847
850
  | 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. |
848
851
  | 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). |
849
852
  | 11 — Summary | `@bkit-plan-summary` | Commit `chore({FID}): summary bkit [skip ci]` → push. |
850
- | 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. |
853
+ | 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 what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
851
854
 
852
855
  **Hard stop in Step 12 caution block:** "Plan requires human review. Do not invoke `/bkit-build`."
853
856
 
@@ -879,37 +882,38 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
879
882
  | 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`. |
880
883
  | 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. |
881
884
  | 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). |
882
- | 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. |
885
+ | 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 what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
883
886
 
884
887
  **Failure Path includes handover** — when triggered by exhausted retry counts, invokes `@bkit-debug-abort-handover` and posts `Workflow Handover` comment.
885
888
 
886
- ### `/bkit-debug` — 10 steps
889
+ ### `/bkit-debug` — 11 steps
887
890
 
888
- **Goal:** diagnose and remediate failing test or CI run; push fix back to branch.
891
+ **Goal:** diagnose and remediate failing test or CI run; push fix back to branch; `[repro]` → failing test first when nothing fails yet.
889
892
 
890
- **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.
893
+ **Mode detection (Step 1):** `bkit prs probe` (any base): open PR → `PUSH_MODE` = PR, else LOCAL (exit 80 → `list_pull_requests`); Step 11 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-6 diagnose `Mode: SOAK`, not here. `REPRO` = `[repro]` in session prompt.
891
894
 
892
- **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.
895
+ **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-6 `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.
893
896
 
894
- **Loop:** Step 3 Run Tests (head; iter 1 = reproduce) → FAIL with budget → Step 4 Fetch Context → fix step (`NORMAL` → Diagnose 5 + Remediate 6; `SOAK` → Soak 7) → loop Step 3. PASS after fix → Push 8 → Summary 9 → Close 10; PASS no fix → can't-reproduce → Summary (CONCERNS). NORMAL exhaust → SOAK fresh budget; SOAK exhaust → Failure Path. Close asserts no `[DEBUG-OBSERVE]` survives debug diff (no-leak) before CI push.
897
+ **Loop:** Step 3 Run Tests (head; iter 1 = reproduce) → FAIL with budget → Step 4 Fetch Context → fix step (`NORMAL` → Diagnose 6 + Remediate 7; `SOAK` → Soak 8) → loop Step 3. PASS after fix → Push 9 → Summary 10 → Close 11; PASS no fix → can't-reproduce → Summary (CONCERNS); with `REPRO` → Fetch Context 4 → Reproduce 5: reproduced → test committed → loop Step 3 (records the red; a PASS there with no fix → Summary (CONCERNS)); not reproduced → test changes removed → Summary (CONCERNS). Soak loops only on a failing Run Tests, never a green suite. Reproduce run spends one `NORMAL_ATTEMPT`. NORMAL exhaust → SOAK fresh budget; SOAK exhaust → Failure Path. Close asserts no `[DEBUG-OBSERVE]` survives debug diff (no-leak) before CI push.
895
898
 
896
899
  **Live tier (Step 3):** appends declared `test:integration:live` / `test:e2e:live` / `test:live` unless `[live=off]`; recorded verbatim in `scope`. No live tier → CONCERNS + `testsLiveSkipped` at close — never silent pass. "Did live run?" = read `scope` after fact.
897
900
 
898
- **Context fetch (Step 4):** mode-agnostic, per loop iteration on FAIL. all evidence is block-driven — bkit hardcodes no CI host, workflow filename, branch name or e2e framework. `bkit context list-blocks` enumerates every `bash` block between `<!-- context-fetch:start [name] [context=<context>] -->` / `<!-- context-fetch:end -->` after `<!-- bkit:end -->` in `.agents/context.md` (consumer blocks only); each is customised into a script file and run by `bkit context run-block --idx=`, stdout written per context → `ci` → `context-ci-<name>-{DEBUG_ATTEMPT}.md`; `diff` → `context-diff-…`; `e2e` → `context-e2e-…`; `runtime` (default) → `context-runtime-…`; `web` → `context-web-…`. Blocks are self-contained (each discovers its own run; no shared variables, no ordering) and self-gate on CLI/token → stderr `[context-fetch:<name>] skipped — …` breadcrumb, `exit 0` — load-bearing for headless cloud. Local suite is not a block: Step 3's own run is captured to `context-tests-local-{DEBUG_ATTEMPT}.md` and never re-run here. Context coverage is narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` per context before fetching (`list-blocks`) and recorded as `contextsConfigured` on the `context-fetch` status row (`bkit context finalise`) — a thin artifact set because a context has no block must stay distinguishable from one that is thin because the sources were clean. Plus a tracker search for related issues → `context-related-{DEBUG_ATTEMPT}.md`. Any/all/none may exist; fail-soft throughout.
901
+ **Context fetch (Step 4):** mode-agnostic, per loop iteration on FAIL, plus once before Reproduce. all evidence is block-driven — bkit hardcodes no CI host, workflow filename, branch name or e2e framework. `bkit context list-blocks` enumerates every `bash` block between `<!-- context-fetch:start [name] [context=<context>] -->` / `<!-- context-fetch:end -->` after `<!-- bkit:end -->` in `.agents/context.md` (consumer blocks only); each is customised into a script file and run by `bkit context run-block --idx=`, stdout written per context → `ci` → `context-ci-<name>-{DEBUG_ATTEMPT}.md`; `diff` → `context-diff-…`; `e2e` → `context-e2e-…`; `runtime` (default) → `context-runtime-…`; `web` → `context-web-…`. Blocks are self-contained (each discovers its own run; no shared variables, no ordering) and self-gate on CLI/token → stderr `[context-fetch:<name>] skipped — …` breadcrumb, `exit 0` — load-bearing for headless cloud. Local suite is not a block: Step 3's own run is captured to `context-tests-local-{DEBUG_ATTEMPT}.md` and never re-run here. Context coverage is narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` per context before fetching (`list-blocks`) and recorded as `contextsConfigured` on the `context-fetch` status row (`bkit context finalise`) — a thin artifact set because a context has no block must stay distinguishable from one that is thin because the sources were clean. Plus a tracker search for related issues → `context-related-{DEBUG_ATTEMPT}.md`. Any/all/none may exist; fail-soft throughout.
899
902
 
900
903
  <!-- prettier-ignore -->
901
904
  | Step | Subagent(s) | Notes |
902
905
  | --- | --- | --- |
903
906
  | 1 — Start Workflow | — | Pre-flight: `bkit repo info --fetch`. `bkit issues labels --failed=off --debug=on`: adds `bkit:debug` additively (prior phase label persists) and clears `bkit:failed`; state `In Progress`. PR-mode: `PR_NUMBER` → `PUSH_MODE`. `DEBUG_ATTEMPT` + `DEBUG_MODE` per Mode detection above. no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
904
907
  | 2 — Worktree Setup | — | Branch handling differs from feat workflows: debug MINTS NOTHING. Resume `.worktrees/{FID}` → else adopt an already-existing `feat/{FID}` (local or origin) into a worktree → else adopt the session's current branch in place (`WORKTREE_PATH=$REPO_ROOT`, no `git worktree add`, no `-b`), which is also the path taken when the session is already sitting on `feat/{FID}` (git refuses one branch in two worktrees). Branch eligibility: any branch but `main` — else Failure Path. `bkit worktrees setup` (no `--branch`, no `-b`; `main` → exit 7). Writes `debug-input-{DEBUG_ATTEMPT}.md` (failure description only — no workflow state). Persists `debugAttempt` / `debugMode` / `pushMode` (`bkit status meta`; `--soak-entry` when the run starts in SOAK). |
905
- | 3 — Run Tests | — | **LOOP HEAD (both modes).** `NORMAL_ATTEMPT` = this row's `attempt` (`steps done --attempt=next`). `bkit tests run` runs the deepest `bkit:gate:*` the consumer declares — descending `static-unit-integration-e2e-live`, `static-unit-integration-e2e`, `static-unit`; `[live=off]` drops the live candidate (§ Local gate scripts). Iteration 1 = reproduce. Records `verdict` + `failures` + `scope` (the gate script name; ends `:live` only when the live gate ran); writes the status row but does not commit it — a `chore(...)` HEAD here would let a preview host's `^chore:` ignore rule cancel the preview and demote CI to a partial tier, skipping the suites the loop is proving; `parentSha` advances transitively through Steps 4-6. PASS + `NORMAL_ATTEMPT` > 1 → Step 8; PASS (unreproduced) → Step 9; FAIL + NORMAL + `NORMAL_ATTEMPT` <= `MAX_NORMAL_ATTEMPT` → Step 4; FAIL + NORMAL + exhausted → `bkit status meta --soak-entry --debug-mode=SOAK` (fresh `SOAK_ATTEMPT` budget) → Step 4; FAIL + SOAK + `SOAK_ATTEMPT` < `MAX_SOAK_ATTEMPT` → Step 4; else → Failure Path. |
906
- | 4 — Fetch Context | — | _(on FAIL with budget)_ Mode-agnostic. Every consumer `context-fetch` block (`bkit context list-blocks` → `run-block`, fenced + clamped) + a related-issues tracker search → per-context `context-*-{DEBUG_ATTEMPT}.md` written only when content exists; `bkit context finalise` → `FETCH_VERDICT`, `contextsConfigured`, `clamped`. Routes: SOAK → Step 7; else → Step 5. |
907
- | 5 — Failure Diagnose | `@bkit-debug-failure-diagnose` _(only if `DEBUG_MODE` = NORMAL)_ | `STRATEGY` STANDARD → PIVOT → FINAL by prior diagnose. Writes `debug-failure-diagnose-{NORMAL_ATTEMPT}.md`; when a live tier failed on a functional assertion, anchors on that real-boundary ground truth (treats infra/credential failures as environment, not feature-broken). Sets `Mode` (NORMAL | SOAK) — `SOAK` when the cause is not localisable (gated on `Verdict` != PASS); in `NORMAL` the orchestrator then fast-tracks to Step 7 (Soak) with a fresh SOAK budget (`--soak-entry`), else → Step 6. |
908
- | 6 — Failure Remediate | `@bkit-debug-failure-remediate` _(only if `DEBUG_MODE` = NORMAL)_ | Writes `debug-failure-remediate-{NORMAL_ATTEMPT}-log.md` + source files. Orchestrator commits `fix({FID}): {description}{VERBOSE_SUFFIX}` (`{description}` from the first `DONE — Step` line, truncated to 72 chars; `VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`); the fix commit is the HEAD the next Run Tests / Push pushes. → loop to Step 3. |
909
- | 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). |
910
- | 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. |
911
- | 9 — Summary | `@bkit-debug-summary` | Commit `chore({FID}): summary{VERBOSE_SUFFIX}` → push. `SUMMARY_VERDICT` = PASS/CONCERNS → Step 10; FAIL → Failure Path. |
912
- | 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. |
908
+ | 3 — Run Tests | — | **LOOP HEAD (both modes).** `NORMAL_ATTEMPT` = this row's `attempt` (`steps done --attempt=next`). `bkit tests run` runs the deepest `bkit:gate:*` the consumer declares — descending `static-unit-integration-e2e-live`, `static-unit-integration-e2e`, `static-unit`; `[live=off]` drops the live candidate (§ Local gate scripts). Iteration 1 = reproduce. Records `verdict` + `failures` + `scope` (the gate script name; ends `:live` only when the live gate ran); writes the status row but does not commit it — a `chore(...)` HEAD here would let a preview host's `^chore:` ignore rule cancel the preview and demote CI to a partial tier, skipping the suites the loop is proving; `parentSha` advances transitively through Steps 4-7. PASS routes on active-run rows, not the attempt count: a fix step ran (`debug-failure-remediate` / `debug-failure-soak`, one `counters route --of=<step>,<step>:count`) → Step 9; Failure Reproduce ran, no fix since (reproduce tests passed on the re-run — intermittent) → Step 10 (CONCERNS); neither + `REPRO` → Step 4; neither → Step 10; FAIL + NORMAL + `NORMAL_ATTEMPT` <= `MAX_NORMAL_ATTEMPT` → Step 4; FAIL + NORMAL + exhausted → `bkit status meta --soak-entry --debug-mode=SOAK` (fresh `SOAK_ATTEMPT` budget) → Step 4; FAIL + SOAK + `SOAK_ATTEMPT` < `MAX_SOAK_ATTEMPT` → Step 4; else → Failure Path. |
909
+ | 4 — Fetch Context | — | _(on FAIL with budget, or before Reproduce)_ Mode-agnostic. Every consumer `context-fetch` block (`bkit context list-blocks` → `run-block`, fenced + clamped) + a related-issues tracker search → per-context `context-*-{DEBUG_ATTEMPT}.md` written only when content exists; `bkit context finalise` → `FETCH_VERDICT`, `contextsConfigured`, `clamped`. Routes: PASS → Step 5; SOAK → Step 8; else → Step 6. |
910
+ | 5 — Failure Reproduce | `@bkit-debug-failure-reproduce` _(only if `REPRO` and first Run Tests PASS)_ | Writes `debug-failure-reproduce-{NORMAL_ATTEMPT}.md` + tests failing on the reported symptoms (`Mode: SOAK` → they repeat the scenario until they fail reliably); no implementation changes. `steps finish` commits `test({FID}): reproduce reported failure`, holds `Reproduced`. `YES` → Step 3 (its FAIL row = the red; its PASS row with no fix since → Step 10); `NO` → test changes removed → Step 10. |
911
+ | 6 — Failure Diagnose | `@bkit-debug-failure-diagnose` _(only if `DEBUG_MODE` = NORMAL)_ | `STRATEGY` STANDARD → PIVOT → FINAL by prior diagnose. Writes `debug-failure-diagnose-{NORMAL_ATTEMPT}.md`; when a live tier failed on a functional assertion, anchors on that real-boundary ground truth (treats infra/credential failures as environment, not feature-broken). Sets `Mode` (NORMAL | SOAK) — `SOAK` when the cause is not localisable (gated on `Verdict` != PASS); in `NORMAL` the orchestrator then fast-tracks to Step 8 (Soak) with a fresh SOAK budget (`--soak-entry`), else → Step 7. |
912
+ | 7 — Failure Remediate | `@bkit-debug-failure-remediate` _(only if `DEBUG_MODE` = NORMAL)_ | Writes `debug-failure-remediate-{NORMAL_ATTEMPT}-log.md` + source files. Orchestrator commits `fix({FID}): {description}{VERBOSE_SUFFIX}` (`{description}` from the first `DONE — Step` line, truncated to 72 chars; `VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`); the fix commit is the HEAD the next Run Tests / Push pushes. → loop to Step 3. |
913
+ | 8 — 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). |
914
+ | 9 — Push Remediation | — | _(PASS after a fix)_ Status file-only (no intermediate commit so Step 7/8's `fix(...)` stays HEAD at push). PR-mode: append `bkit [verbose ci]` to PR title if absent. Push. → Step 10. |
915
+ | 10 — Summary | `@bkit-debug-summary` | Commit `chore({FID}): summary{VERBOSE_SUFFIX}` → push. `SUMMARY_VERDICT` = PASS/CONCERNS → Step 11; FAIL → Failure Path. |
916
+ | 11 — 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 what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
913
917
 
914
918
  **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.
915
919
 
@@ -963,16 +967,16 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
963
967
  | 9 — Re-validate | — | Resolve `VALIDATED_HEAD` (carry-forward above). Wait only when `VALIDATED_HEAD` != `ENTRY_HEAD` **or** `REVALIDATE_REASON` = `gate-refusal`: `bkit runs wait --head=<VALIDATED_HEAD> --until=present --dispatch-if-absent` (6 polls; `gh workflow run {bkit.ciWorkflow}` only on no-run, then `VALIDATED_HEAD` = PR head) → `ship-revalidate-dispatch` row → head-anchored `--until=completed` (`SHIP_CI_WAIT_TIMEOUT_S`; budget exhausted → `ship-revalidate-timeout` row → Failure Path) → Step 10. |
964
968
  | 10 — Merge Gate + Merge PR | — | `bkit runs gate --pr= --validated=<VALIDATED_HEAD> --branch= --file= --snapshot={OUTBOX}/pre-merge-snapshot.jsonl --record={STATUS}` — the ONLY merge precondition: the snapshot (PR head, `VALIDATED_HEAD`, dev SHA, ancestor, capstone run, mergeable) is written before it decides, a skip token in the PR title refuses (18), a refusal is recorded as `ship-gate-refusal`. `bkit prs merge --match-head=<gate mergeHead> --delete-branch {LABEL_FLAGS} --expect-merged` (empty body). `state` = MERGED → Step 13. Non-zero gate: 10/11/14/17 → bounded Step 9 (poll only); else Failure Path. Non-merged: `bkit counters route --limit=MAX_MERGE_ATTEMPT` → Step 11 or Failure Path. |
965
969
  | 11 — Failure Diagnose | `@bkit-debug-failure-diagnose` _(only if not merged)_ | Writes `ship-failure-diagnose-{MERGE_ATTEMPT}.md`. |
966
- | 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. |
970
+ | 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: its handover sends code-level failures back to build, since a source-file retry loop would re-merge identical remote content. |
967
971
  | 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). |
968
972
  | 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). |
969
- | 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**. |
973
+ | 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 what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. **HARD STOP**. |
970
974
 
971
975
  **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.
972
976
 
973
977
  ### Audits
974
978
 
975
- No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`. **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Writes only the report and the template's consumer-owned `Project Instructions` below `bkit:end`, refined each run. `/bkit-plan` reads a design doc, one or more of those reports, or both.
979
+ No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`. **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Writes only the report and the template's consumer-owned `Project Instructions` below `bkit:end`, refined each run. Final return appends what `bkit tips --workflow=audit` prints (one tip, no star line) as `## bkit Tips`, then offers a plain-English explanation on request. `/bkit-plan` reads a design doc, one or more of those reports, or both.
976
980
 
977
981
  ### `/bkit-auto` — phase-routed dispatch
978
982
 
@@ -1104,13 +1108,13 @@ PR / CI reads and writes go through `bkit` commands (exit 80 → the mapped MCP
1104
1108
  | `OWNER_REPO` (Step 1 of every phase) | `bkit repo info` (`gh`, else the origin remote) |
1105
1109
  | Dispatch-permission preflight (ship Step 1) | `bkit repo preflight --owner-repo` (advisory: warns and continues, exit 0) |
1106
1110
  | PR lookup, PR-mode detection | `bkit prs probe [--head= --base= --state= --number=]` |
1107
- | PR creation (build Step 18, debug Step 10 LOCAL, design / plan PR close, ship Step 2 when no PR exists) | `bkit prs open` (base pinned `dev`, marker in body) |
1111
+ | PR creation (build Step 18, debug Step 11 LOCAL, design / plan PR close, ship Step 2 when no PR exists) | `bkit prs open` (base pinned `dev`, marker in body) |
1108
1112
  | CI presence / completion, CI-Dispatch Gate | `bkit runs wait`, `bkit runs dispatch` |
1109
1113
  | Ship merge gate, squash-commit CI | `bkit runs gate` |
1110
1114
  | Squash merge (ship Step 10; design / plan PR close) | `bkit prs merge` / `bkit branches land` → `gh pr merge {PR} --squash [--match-head-commit <head>] --subject "…" --body ""` — empty body strips feature `bkit [skip ci]` |
1111
1115
  | Path B refresh (ship Step 4 B1) | `bkit prs update-branch` |
1112
1116
  | PR check-rollup assert (ship Step 2) | `bkit prs checks --number` |
1113
- | `bkit [verbose ci]` PR-title marker (debug Steps 8 / 10) | `gh pr edit --title` |
1117
+ | `bkit [verbose ci]` PR-title marker (debug Steps 9 / 11) | `gh pr edit --title` |
1114
1118
 
1115
1119
  Code PRs never merge locally; `/bkit-ship` merges with `bkit prs merge` (`gh pr merge` underneath).
1116
1120
 
@@ -1143,14 +1147,14 @@ Precedence: `bkit [force build]` on head commit wins.
1143
1147
  | `chore({FID}): pre-worktree uncommitted changes` (design / plan / build Step 2, `bkit ledgers commit --only-if-dirty-tracked`) | `bkit [skip ci]` |
1144
1148
  | `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` |
1145
1149
  | `chore({FID}): summary bkit [skip ci]` (design Step 10 summary, plan Step 11 summary) | `bkit [skip ci]` |
1146
- | `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. |
1150
+ | `fix({FID}): {description}` (debug Step 7 failure-remediate) | none — Step 9 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. |
1147
1151
  | `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. |
1148
1152
  | `docs({FID}): ship DONE` (ship Step 15 close-workflow on `dev`, or its `ship-close/{FID}` PR squash subject) | `bkit [skip ci]` |
1149
1153
  | `docs({FID}): {phase} aborted` (build / debug Failure Path handover) | `bkit [skip ci]` |
1150
1154
  | `chore({FID}): ship FAILED` (ship Failure Path — the single flush; carries the handover and the reconciled branch-side artifacts, so ship emits no `aborted` commit) | `bkit [skip ci]` |
1151
1155
  | `chore({FID}): close-workflow` (build Step 18 — opted-in: `bkit [auto route]` suffix when issue carried `bkit:auto` at close time) | none on base commit; opted-in adds `bkit [auto route]` (loud, not a suppressor) — final HEAD on push, fires `pull_request` synchronize + CI auto-route gate |
1152
- | `chore({FID}): close-workflow` (debug Step 10 PR-mode — opted-in) | none / `bkit [auto route]` (PR-mode, conditional) — same as build |
1153
- | `chore({FID}): create-pr` (debug Step 10 local-mode — opted-in) | none / `bkit [auto route]` (local-mode, conditional) — CI-triggering HEAD in local-mode |
1156
+ | `chore({FID}): close-workflow` (debug Step 11 PR-mode — opted-in) | none / `bkit [auto route]` (PR-mode, conditional) — same as build |
1157
+ | `chore({FID}): create-pr` (debug Step 11 local-mode — opted-in) | none / `bkit [auto route]` (local-mode, conditional) — CI-triggering HEAD in local-mode |
1154
1158
  | `chore({FID}): conflict-resolve` (ship Step 4 B2 — ONLY step that force-pushes `{SHIP_BRANCH}`) | `bkit [skip ci]` — never `bkit [auto route]`. Deliberate: ship dispatches CI itself at Step 9 on observed head movement and polls to completion, so the push must not also fire a push-triggered run. Ship Step 4 B1 (`bkit prs update-branch`) likewise leaves an unmarked HEAD — GitHub authors that merge commit and bkit cannot set its message. A local `origin/dev` merge pushed back onto `feat/{FID}` is never reintroduced here — it mutates the validated PR head. |
1155
1159
  | `{title} (#{PR_NUMBER})` squash-merge commit (ship Step 10 `bkit prs merge`, GitHub-authored, lands on `dev`) | none / `bkit [auto route]` (opted-in: `bkit:auto` re-read from the tracker immediately before merge, passed as `--label=`) — the CI-triggering HEAD that admits `bkit-cloud.yml`'s post-merge `dev` free-tier gate. Distinct from the B1/B2 rows above: GitHub authors this commit at merge time rather than pushing a local merge onto a validated head. |
1156
1160
 
@@ -1163,8 +1167,8 @@ Outcome-verification gate: after final loud push, confirms bkit CI check dispatc
1163
1167
  **Invoked by orchestrators** (not git hook — invariant contextual; bkit intentionally pushes `[skip ci]` HEADs intermediately). The HEAD-message clause is `bkit branches push --require-ci` (exit 6 on a CI-suppressing token in the HEAD message, body included); the PR-title clause is `bkit prs open` (exit 4 on a token in `--title`); the poll is `bkit runs dispatch`:
1164
1168
 
1165
1169
  - **Build Step 18:** close-workflow commit → `bkit branches push --mode=feature --require-ci` (no PR yet, no CI) → `bkit prs open` (the PR creation fires CI) → `bkit runs dispatch --pr=`.
1166
- - **Debug Step 10 PR-mode:** close-workflow push (sub-step 2, `--require-ci`) = CI trigger; gate in sub-step 6.
1167
- - **Debug Step 10 LOCAL-mode:** create-pr push (sub-step 6, `--require-ci`) = CI trigger, its block re-deriving `AUTO_ROUTE_SUFFIX`; gate in sub-step 7.
1170
+ - **Debug Step 11 PR-mode:** close-workflow push (sub-step 2, `--require-ci`) = CI trigger; gate in sub-step 6.
1171
+ - **Debug Step 11 LOCAL-mode:** create-pr push (sub-step 6, `--require-ci`) = CI trigger, its block re-deriving `AUTO_ROUTE_SUFFIX`; gate in sub-step 7.
1168
1172
  - **Ship:** OUT of scope. Step 15 reads the squash commit's CI with `bkit runs gate --head=<SQUASH_SHA>` and records `ship-merge-ci`. CI-Dispatch at ship would mask "essential tests skipped" signal ship backstops.
1169
1173
  - **Ship Step 9 duplicate-dispatch probe (not the gate):** `bkit runs wait --head=<VALIDATED_HEAD> --branch= --until=present --dispatch-if-absent` probes for a CI-workflow run at that head, presence only (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`), and runs `gh workflow run {bkit.ciWorkflow}` only on no-run. The head move it follows (Path B `bkit prs update-branch`) already fires `pull_request` at the same SHA, and the template `bkit-ci.yml` groups `pull_request` by PR number but `workflow_dispatch` by ref — different groups, so neither cancels the other and both runs complete. The probe carries no outcome vocabulary and is never a pass condition (no `self-healed`/`no-ci` path exists at ship): the head-anchored completion poll (`--until=completed`) and `bkit runs gate` at Gate 10 still own the verdict, so the "masks essential tests skipped" objection does not apply. Probe `err` → dispatch. Row `ship-revalidate-dispatch` records `probe` / `dispatched` / `attempts`. The 60s budget is load-bearing: a `pull_request` run surfacing after it reproduces the duplicate this probe removes. Auto-fired runs typically appear ~10-20s after the push, but auto-fire is intermittent, so the probe MUST keep failing safe to dispatch rather than reading a slow or absent run as "no CI".
1170
1174
  - **Ship Gate 10 + squash `--body ""`:** merge — squash subject = dev HEAD.
@@ -1211,7 +1215,7 @@ Outcome-verification gate: after final loud push, confirms bkit CI check dispatc
1211
1215
  Every site derives `AUTO_ROUTE_SUFFIX` **in the same bash fence that consumes it** from the labels the workflow re-read through the tracker MCP: `bkit issues labels {LABEL_FLAGS}` prints `autoRouteSuffix` (`" bkit [auto route]"` on an exact `bkit:auto`, else empty), and the fence passes it as `bkit runs dispatch --auto-route-suffix=`. Never carry the suffix itself across a fence or step: no shell state (nor a `mktemp` path published via `$GITHUB_ENV`) survives a Bash-tool-call boundary.
1212
1216
 
1213
1217
  - **Build Step 18:** derived in the dispatch block itself.
1214
- - **Debug Step 10:** derived in the close / create-pr commit block (sub-steps 2 / 5) for the commit subject, and again in the gate block (sub-step 6) for the dispatch.
1218
+ - **Debug Step 11:** derived in the close / create-pr commit block (sub-steps 2 / 5) for the commit subject, and again in the gate block (sub-step 6) for the dispatch.
1215
1219
 
1216
1220
  **Re-trigger commit:** `chore({FID}): re-trigger{AUTO_ROUTE_SUFFIX}`, created and pushed by `bkit runs dispatch` — opted-in issues carry `bkit [auto route]`. § `bkit [auto route]` Marker Propagation applies.
1217
1221
 
@@ -1296,7 +1300,9 @@ Mechanical step work runs as `bkit <noun> <verb> --flag=value` (also `--flag val
1296
1300
  "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
1297
1301
  ```
1298
1302
 
1299
- and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`); every later block runs `"{BKIT}" <noun> <verb> …`, the orchestrator substituting the path. It is the main checkout's binary, so it works before and without a worktree `node_modules` (adopt mode never installs). The bkit repo links itself as a dev dependency so the same path exists there. A value a later step needs is held from the command's JSON by key (`hold worktreePath as {WORKTREE_PATH}`) — never re-derived by hand; model-held values reach a command as flag values (`--fid={FID}`), never through shell variables. Every command refuses (exit 2) a flag value still carrying a literal `{UPPER}` placeholder — the orchestrator passed it through unsubstituted.
1303
+ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`); every later block runs `"{BKIT}" <noun> <verb> …`, the orchestrator substituting the path. It is the main checkout's binary, so it works before and without a worktree `node_modules` (adopt mode never installs). The bkit repo links itself as a dev dependency so the same path exists there. A value a later step needs is held from the command's JSON by key (`hold worktreePath as {WORKTREE_PATH}`) — never re-derived by hand; model-held values reach a command as flag values (`--fid={FID}`), never through shell variables. Every command refuses (exit 2) a flag value still carrying a literal `{UPPER}` placeholder — the orchestrator passed it through unsubstituted.
1304
+
1305
+ **Outdated bkit:** `repo info` also reports `bkitVersion` (`.bkit/version` `pinnedVersion`), `bkitLatest` (newest published `@cbartens/bkit`), `bkitOutdated` (numeric compare; a prerelease is older than its release) and `bkitAdvisory` (one line naming the upgrade command; null unless outdated). Step 1 of every phase workflow emits a non-null `{BKIT_ADVISORY}` as `[bkit-{workflow}] …` and continues — never a stop, never a gate item. Lookup: `pnpm view`, at most once a day; answer cached in `<git common dir>/bkit-latest-version.json` (shared by worktrees, never committed); a failed lookup cached 1 hour. No answer, no pin, or `BKIT_NO_UPDATE_CHECK` set (not `0`) → `bkitLatest` / `bkitOutdated` / `bkitAdvisory` null. Same check stamps every anchored doc (§ Anchor Block).
1300
1306
 
1301
1307
  **Step endings:** a step that writes a `step-done` row ends in one `bkit steps finish` call: it reads each `--agent`'s verdict header from the `--artifact` in the same position (worst verdict wins, `Failures` summed, the prompt's declared header fields required, `Strategy` recorded on the row), derives the attempt (`--attempt=next`, `--attempt-of=<step>:<next|current|count>`; `<attempt>` in a path or message becomes it), runs the gate's mechanical checks before writing, writes the row, commits (`--message`, `<done>` = the log's first `DONE` line), and prints the step's tracker `comment` (`--number` / `--title`). Exit 5 / 6 print `reask` = `{agent, artifact}` for the header-only re-ask. A gate whose step ends in `steps finish` relies on that call's checks; a gate with no finish (Step 1, closes, Step 3 / 9 of ship) runs `bkit steps gate`.
1302
1308
 
@@ -1305,7 +1311,7 @@ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxR
1305
1311
  <!-- prettier-ignore -->
1306
1312
  | Noun | Verbs | Covers |
1307
1313
  | --- | --- | --- |
1308
- | `repo` | `info`, `preflight` | Step 1 owner/repo, branch, behind-`dev` notice, `{BKIT}` / `{REPO_ROOT}` / `{OUTBOX_ROOT}`; advisory dispatch-permission preflight |
1314
+ | `repo` | `info`, `preflight` | Step 1 owner/repo, branch, behind-`dev` notice, outdated-bkit advisory, `{BKIT}` / `{REPO_ROOT}` / `{OUTBOX_ROOT}`; advisory dispatch-permission preflight |
1309
1315
  | `fids` | `check`, `parse`, `find` | FID format asserts; marker / branch FID recovery; the feature already logged for an issue (`find --issue`: exit 0 one, 1 none, 4 several) |
1310
1316
  | `runtime` | `detect`, `row`, `assert` | runtime capability table + `runtime-resolved` row |
1311
1317
  | `locks` | `acquire`, `release` | per-feature `.lock` and `.bkit/.dev.lock` |
@@ -1317,7 +1323,7 @@ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxR
1317
1323
  | `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 |
1318
1324
  | `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) |
1319
1325
  | `status` | `path`, `fold`, `route`, `meta`, `row` | status location, fold, routing state (`route --expect=field=value`), `workflow-meta` rows, typed audit rows the fold skips |
1320
- | `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) |
1326
+ | `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; `--of=<step>,<step>:count` sums several steps) |
1321
1327
  | `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 |
1322
1328
  | `ledgers` | `commit`, `union`, `only-bookkeeping` | path-scoped bookkeeping staging, ledger union, carry-forward check |
1323
1329
  | `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`) |
@@ -1436,7 +1442,7 @@ Build Step 7 runs the Step 14 gate after every sub-plan but the last, once `@bki
1436
1442
 
1437
1443
  ### Test-first
1438
1444
 
1439
- 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.
1445
+ Every plan task carries `**Test first:**` (with no plan file, the build input's `- [ ] **Task N:**` lines count as the plan: `tests green --brief=`) — 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.
1440
1446
 
1441
1447
  <!-- prettier-ignore -->
1442
1448
  | Moment | Who | What is checked |
@@ -1450,7 +1456,7 @@ Every plan task carries `**Test first:**` — one or more `;`-separated tests, e
1450
1456
  - **Hash in the row, snapshot beside the log:** both ride the plan-execute commit and survive push and resume; nothing pins a git object.
1451
1457
  - **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.
1452
1458
  - **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.
1453
- - **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.
1459
+ - **Not enforced, never silent:** no plan file and no `**Task N:**` lines with `Test first:` in the build input, 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.
1454
1460
 
1455
1461
  ### Tracker issue-create return guard
1456
1462
 
@@ -54,7 +54,7 @@ function bkitGuardrails(payload) {
54
54
  if (!c) return null;
55
55
 
56
56
  const notes = [];
57
- if (usesFetch(c) && !curlWgetHostAllowed(c)) {
57
+ if (usesFetch(c) && !curlWgetHostAllowed(c, hookDirs(payload))) {
58
58
  notes.push(
59
59
  "bkit guardrails: outbound fetch to a host that is not on this repo's network allowlist " +
60
60
  "(.agents/context.md § allowed-domains, plus bkit's shipped tooling hosts). Not blocked — " +
@@ -55,10 +55,13 @@ function deny(reason) {
55
55
  return { verdict: "deny", reason };
56
56
  }
57
57
 
58
- /** @param {string} cmd */
59
- function decideShell(cmd) {
58
+ /**
59
+ * @param {string} cmd
60
+ * @param {string[]} dirs where to look for the network allowlist (`hookDirs`)
61
+ */
62
+ function decideShell(cmd, dirs) {
60
63
  const c = String(cmd || "").trim();
61
- const v = classifyShell(c);
64
+ const v = classifyShell(c, dirs);
62
65
  if (!v) return allow();
63
66
  switch (v.tier) {
64
67
  case "deny":
@@ -100,7 +103,7 @@ function bkitGuardrails(payload) {
100
103
  // Codex passes the command as a string, or as an argv array for some shells.
101
104
  const cmd = Array.isArray(input.command) ? input.command.join(" ") : input.command;
102
105
  if (typeof cmd !== "string") return null;
103
- const decision = decideShell(cmd);
106
+ const decision = decideShell(cmd, hookDirs(payload));
104
107
  return decision.verdict === "allow" ? null : decision;
105
108
  }
106
109
 
@@ -56,10 +56,13 @@ function deny(userMessage, agentMessage) {
56
56
  };
57
57
  }
58
58
 
59
- /** @param {string} cmd */
60
- function decideShell(cmd) {
59
+ /**
60
+ * @param {string} cmd
61
+ * @param {string[]} dirs where to look for the network allowlist (`hookDirs`)
62
+ */
63
+ function decideShell(cmd, dirs) {
61
64
  const c = cmd.trim();
62
- const v = classifyShell(c);
65
+ const v = classifyShell(c, dirs);
63
66
  if (!v) return allow();
64
67
  switch (v.tier) {
65
68
  case "deny":
@@ -108,13 +111,13 @@ function decideRead(filePath) {
108
111
  * opinion on this call (the caller decides what a no-opinion result means).
109
112
  */
110
113
  function bkitGuardrails(payload) {
111
- // beforeShellExecution: { command }
114
+ // beforeShellExecution: { command, cwd, workspace_roots }
112
115
  if (
113
116
  typeof payload.command === "string" &&
114
117
  payload.tool_name == null &&
115
118
  payload.tool_input == null
116
119
  ) {
117
- return decideShell(payload.command);
120
+ return decideShell(payload.command, hookDirs(payload));
118
121
  }
119
122
 
120
123
  // preToolUse Read/TabRead: { tool_name, tool_input: { path|file_path|target_file|... } }
@@ -72,7 +72,7 @@ Target failure: **a gate that stays green while the unchecked surface is where t
72
72
 
73
73
  Always verify.
74
74
 
75
- - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. never retry or reword a blocked call to get past it.
75
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
76
76
  - [ ] **Gate Source:** Steps 2, 4, 13 — automated-gate files readable. Fallback: no gate while UI exists = finding; later steps run without snapshot.
77
77
  - [ ] **Checker:** Steps 5, 6 — full rule set, e.g. axe-core, pa11y, Accessibility Insights. Fallback: manual steps only; automated rows `Not Checked`.
78
78
  - [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -253,6 +253,13 @@ PENDING
253
253
 
254
254
  PENDING
255
255
 
256
+ ### Suggested Issues
257
+
258
+ <!-- prettier-ignore -->
259
+ | # | Title | Findings | Severity | Next Step | Reason |
260
+ | --- | --- | --- | --- | --- | --- |
261
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
262
+
256
263
  ### Process Improvements
257
264
 
258
265
  PENDING
@@ -266,6 +273,7 @@ PENDING
266
273
  - [ ] **Sessions:** states the date of the last assistive-technology session and when the next is due.
267
274
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
268
275
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
276
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
269
277
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
270
278
 
271
279
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -46,7 +46,7 @@ bkit ships three folders. Path inside a folder = path it lands at in the repo.
46
46
  **Anchor Standards:** record bkit version and date read. Newer version → `Standards` step reads what changed.
47
47
 
48
48
  - bkit, at the installed version: `.bkit/templates.md` (Contract, placeholders, Context-fetch blocks), `.bkit/README.md` § File ownership and § Ongoing CLI, `.bkit/install.md`; release notes since pinned version.
49
- - Config reference of each tool behind an adopted template (e.g. Husky, lint-staged, Vale, Prettier, Renovate, Dependabot, GitHub Actions workflow syntax, direnv); record version read.
49
+ - Config reference of each tool behind an adopted template (e.g. Husky, lint-staged, Vale, Prettier, Renovate, Dependabot, Trivy, GitHub Actions workflow syntax, direnv); record version read.
50
50
 
51
51
  ### Scope
52
52
 
@@ -82,7 +82,7 @@ bkit ships three folders. Path inside a folder = path it lands at in the repo.
82
82
 
83
83
  Always verify.
84
84
 
85
- - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. never retry or reword a blocked call to get past it.
85
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
86
86
  - [ ] **Checkout:** Steps 2–11 — repo with `.bkit/version`. Fallback: none; absent → `N/A` and STOP.
87
87
  - [ ] **Package:** Step 2 — installed package root (e.g. `node_modules/@cbartens/bkit/.bkit/`, resolved via the package manager). Fallback: unpack the pinned version (e.g. `npm pack @cbartens/bkit@<pinnedVersion>` into a throwaway dir); else inventory from `.bkit/templates/` + `canonicalHashes` only, `core/` + `shared/` unwritten files `Not Checked`.
88
88
  - [ ] **bkit CLI:** Steps 4, 5 — `bkit check`, `bkit doctor` (or `pnpm bkit …`). Fallback: hash written files against `canonicalHashes` by hand; advisories `Not Checked`.
@@ -204,6 +204,13 @@ PENDING
204
204
 
205
205
  PENDING
206
206
 
207
+ ### Suggested Issues
208
+
209
+ <!-- prettier-ignore -->
210
+ | # | Title | Findings | Severity | Next Step | Reason |
211
+ | --- | --- | --- | --- | --- | --- |
212
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
213
+
207
214
  ### Process Improvements
208
215
 
209
216
  PENDING
@@ -217,6 +224,7 @@ PENDING
217
224
  - [ ] **Series:** `Adoption` diffed against previous report's, or marked baseline.
218
225
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway package unpack removed.
219
226
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
227
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
220
228
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
221
229
 
222
230
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -81,7 +81,7 @@ Each agent host reads its own permissions, hooks, tool servers, model picks; nob
81
81
 
82
82
  Always verify.
83
83
 
84
- - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. never retry or reword a blocked call to get past it.
84
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
85
85
  - [ ] **Checkout:** Steps 2–10 — repo-level agent config. Fallback: none; no checkout → `N/A` and STOP.
86
86
  - [ ] **Effective Config:** Steps 2, 4, 6 — host's merged-config view where offered (e.g. `claude mcp list`, a host's permissions or MCP panel). Fallback: files + documented precedence by hand; effective state = hypothesis.
87
87
  - [ ] **Web:** Steps 7, 11 — anchor standards, host references, live model catalogues. Fallback: versions recorded as unread; model pins `Not Checked`.
@@ -211,6 +211,13 @@ PENDING
211
211
 
212
212
  PENDING
213
213
 
214
+ ### Suggested Issues
215
+
216
+ <!-- prettier-ignore -->
217
+ | # | Title | Findings | Severity | Next Step | Reason |
218
+ | --- | --- | --- | --- | --- | --- |
219
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
220
+
214
221
  ### Process Improvements
215
222
 
216
223
  PENDING
@@ -224,6 +231,7 @@ PENDING
224
231
  - [ ] **Series:** `Parity` and tool-server hashes diffed against previous report's, or marked baseline.
225
232
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
226
233
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
234
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
227
235
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
228
236
 
229
237
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.