@cbartens/bkit 5.2.4 → 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 (221) hide show
  1. package/.bkit/README.md +26 -11
  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 +25 -10
  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 +12 -6
  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 +106 -17
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +44 -43
  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-adoption.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -10
  22. package/.bkit/core/docs/templates/bkit-audit-llm.md +20 -14
  23. package/.bkit/core/docs/templates/bkit-audit-prompts.md +2 -2
  24. package/.bkit/core/docs/templates/bkit-audit-red-team.md +10 -8
  25. package/.bkit/core/docs/templates/bkit-audit-security.md +3 -3
  26. package/.bkit/core/docs/templates/bkit-audit-testing.md +4 -3
  27. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  28. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  29. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  30. package/.bkit/core/engine/checks/after/github.ts +29 -120
  31. package/.bkit/core/engine/checks/after/index.ts +2 -2
  32. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  33. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  34. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  35. package/.bkit/core/engine/checks/before/index.ts +7 -43
  36. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  37. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  38. package/.bkit/core/engine/checks/status-holes.ts +4 -5
  39. package/.bkit/core/engine/checks/tips/catalogue.ts +60 -24
  40. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  41. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  42. package/.bkit/core/engine/cli.ts +39 -16
  43. package/.bkit/core/engine/commands/analysis.ts +36 -26
  44. package/.bkit/core/engine/commands/comply.ts +17 -16
  45. package/.bkit/core/engine/commands/harvest.ts +12 -12
  46. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  47. package/.bkit/core/engine/commands/install/install.ts +62 -126
  48. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  49. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  50. package/.bkit/core/engine/commands/lib.ts +35 -10
  51. package/.bkit/core/engine/commands/tips.ts +8 -5
  52. package/.bkit/core/engine/commands/workflow/branches.ts +4 -4
  53. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  54. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  55. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  56. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  57. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  58. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  59. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  60. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  61. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  62. package/.bkit/core/engine/commands/workflow/workflows.ts +15 -14
  63. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  64. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  65. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  66. package/.bkit/core/engine/install/manifest.ts +14 -7
  67. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  68. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  69. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  70. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  71. package/.bkit/core/engine/install/modules/core.ts +91 -70
  72. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  73. package/.bkit/core/engine/install/modules/index.ts +7 -1
  74. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  75. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  76. package/.bkit/core/engine/install/placeholders.ts +3 -18
  77. package/.bkit/core/engine/install/write.ts +59 -12
  78. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  79. package/.bkit/core/engine/render/hosts.ts +47 -67
  80. package/.bkit/core/engine/render/models.ts +29 -11
  81. package/.bkit/core/engine/shared/branches.ts +13 -0
  82. package/.bkit/core/engine/shared/egress.ts +3 -3
  83. package/.bkit/core/engine/shared/json.ts +18 -1
  84. package/.bkit/core/engine/shared/package-json.ts +63 -0
  85. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  86. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  87. package/.bkit/core/engine/shared/settings.ts +36 -0
  88. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  89. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  90. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  91. package/.bkit/core/prompts/bkit-audit-generate.md +60 -7
  92. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  93. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  94. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  95. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  96. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  100. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  102. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  103. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  104. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  105. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  106. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  107. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  108. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  109. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  110. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  111. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  112. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  113. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  114. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  115. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  116. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  117. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  118. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  119. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  120. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  121. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  122. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  123. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  124. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  125. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  126. package/.bkit/core/workflows/bkit-build.md +3 -3
  127. package/.bkit/core/workflows/bkit-debug.md +69 -33
  128. package/.bkit/core/workflows/bkit-design.md +2 -2
  129. package/.bkit/core/workflows/bkit-plan.md +11 -4
  130. package/.bkit/core/workflows/bkit-ship.md +5 -5
  131. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  132. package/.bkit/shared/.claude/settings.json +18 -0
  133. package/.bkit/shared/.cursor/mcp.json +2 -1
  134. package/.bkit/shared/.opencode/opencode.json +19 -1
  135. package/.bkit/shared/docs/deployments.md +20 -4
  136. package/.bkit/shared/docs/security.md +8 -6
  137. package/.bkit/shared/docs/testing.md +9 -5
  138. package/.bkit/templates/.cursor/Dockerfile +30 -16
  139. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  140. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  141. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  142. package/.bkit/templates/.github/renovate.json5 +91 -12
  143. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  144. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  145. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  146. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  147. package/.bkit/templates/.husky/pre-push +8 -3
  148. package/.bkit/templates/.oxlintrc.json +21 -0
  149. package/.bkit/templates/docs/capabilities.md +1 -1
  150. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  151. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  152. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  153. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  154. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  155. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  156. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  157. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  158. package/CHANGELOG.md +50 -3
  159. package/README.md +258 -129
  160. package/dist/checks/after/auth.js +10 -11
  161. package/dist/checks/after/ci-yml.js +11 -14
  162. package/dist/checks/after/github.js +32 -125
  163. package/dist/checks/after/index.js +3 -2
  164. package/dist/checks/after/managed.js +8 -24
  165. package/dist/checks/after/tools.js +3 -16
  166. package/dist/checks/before/context-fetch.js +1 -21
  167. package/dist/checks/before/index.js +6 -42
  168. package/dist/checks/before/mcp.js +14 -9
  169. package/dist/checks/before/repo.js +8 -11
  170. package/dist/checks/status-holes.js +5 -6
  171. package/dist/checks/tips/catalogue.js +51 -18
  172. package/dist/checks/tips/detect.js +41 -2
  173. package/dist/checks/tips/index.js +25 -5
  174. package/dist/cli.js +34 -14
  175. package/dist/commands/analysis.js +21 -5
  176. package/dist/commands/comply.js +20 -18
  177. package/dist/commands/harvest.js +12 -13
  178. package/dist/commands/install/doctor.js +55 -23
  179. package/dist/commands/install/install.js +62 -118
  180. package/dist/commands/install/uninstall.js +165 -31
  181. package/dist/commands/install/upgrade.js +46 -39
  182. package/dist/commands/lib.js +32 -10
  183. package/dist/commands/tips.js +6 -3
  184. package/dist/commands/workflow/branches.js +3 -5
  185. package/dist/commands/workflow/counters.js +17 -7
  186. package/dist/commands/workflow/fids.js +39 -0
  187. package/dist/commands/workflow/ledgers.js +3 -1
  188. package/dist/commands/workflow/prs.js +3 -3
  189. package/dist/commands/workflow/repo.js +2 -2
  190. package/dist/commands/workflow/roadmap.js +4 -4
  191. package/dist/commands/workflow/runs.js +5 -5
  192. package/dist/commands/workflow/steps.js +1 -0
  193. package/dist/commands/workflow/tests.js +16 -3
  194. package/dist/commands/workflow/workflows.js +15 -15
  195. package/dist/commands/workflow/workstreams.js +2 -1
  196. package/dist/commands/workflow/worktrees.js +4 -5
  197. package/dist/install/cloud-env.js +10 -23
  198. package/dist/install/manifest.js +14 -7
  199. package/dist/install/modules/antigravity.js +15 -26
  200. package/dist/install/modules/claude.js +17 -21
  201. package/dist/install/modules/cloud.js +6 -2
  202. package/dist/install/modules/codex.js +15 -29
  203. package/dist/install/modules/core.js +82 -63
  204. package/dist/install/modules/cursor.js +6 -9
  205. package/dist/install/modules/index.js +6 -1
  206. package/dist/install/modules/opencode.js +41 -72
  207. package/dist/install/network-allowlist.js +62 -0
  208. package/dist/install/placeholders.js +3 -16
  209. package/dist/install/write.js +55 -15
  210. package/dist/ledgers/telemetry.js +5 -4
  211. package/dist/render/hosts.js +30 -55
  212. package/dist/render/models.js +20 -9
  213. package/dist/shared/branches.js +11 -0
  214. package/dist/shared/egress.js +0 -2
  215. package/dist/shared/json.js +14 -0
  216. package/dist/shared/package-json.js +61 -0
  217. package/dist/shared/package-roots.js +0 -8
  218. package/dist/shared/protected-paths.js +5 -122
  219. package/dist/shared/settings.js +18 -1
  220. package/package.json +21 -17
  221. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -85,7 +85,7 @@ R_REACH="graph-reachability.json"
85
85
 
86
86
  usage() {
87
87
  cat <<'EOF'
88
- Usage: pnpm graph[:clean|:update|:rollup|:graphml|:tree|:scoped]
88
+ Usage: pnpm graph[:clean|:update|:rollup|:refresh|:check|:graphml|:tree|:scoped]
89
89
 
90
90
  graph Full repo: extract + cluster. ~2 min, 0 tokens.
91
91
  graph:clean Same, but deletes the output dir first. REQUIRED after any
@@ -93,11 +93,14 @@ Usage: pnpm graph[:clean|:update|:rollup|:graphml|:tree|:scoped]
93
93
  NOT the module-resolution cache, so a graph built after an
94
94
  alias edit will silently keep the old, unresolved edges.
95
95
  graph:update Re-extract changed files only, then recluster.
96
- graph:check Release gate: rebuild from THIS tree and fail if the tracked
97
- register docs/capabilities.md is not what a rebuild produces.
98
- Writes nothing tracked. Run it from a clean dev checkout
99
- before opening the dev -> main PR (docs/deployments.md
100
- § Workflow: Dev → Main).
96
+ graph:check Rebuild from THIS tree; fail if the tracked register
97
+ docs/capabilities.md differs from the rebuild. Writes nothing
98
+ tracked. Reads uncommitted edits — `check-at` does not.
99
+ graph:refresh Rebuild the register in a clean checkout of HEAD, copy it
100
+ over docs/capabilities.md. Fixes a red gate; commit it.
101
+ check-at <rev> `check` in a throwaway checkout of <rev>. Pre-push runs it
102
+ for every push to dev; CI runs `check` on every push to dev.
103
+ spec Print the pinned graphify release (pip spec).
101
104
  graph:rollup Collapse the symbol graph into a package view (~24 nodes, the
102
105
  architecture) and a module view (~133 nodes, the subsystems),
103
106
  as interactive HTML. Edge weight is the number of underlying
@@ -164,11 +167,31 @@ require_graph() {
164
167
  [ -f "$OUT/graph.json" ] || { echo "[graph] no $OUT/graph.json — run 'pnpm graph' first" >&2; exit 1; }
165
168
  }
166
169
 
170
+ # The ONE graphify release that builds and judges the register — here, in the pre-push gate
171
+ # and in CI (installs `$(bash scripts/graphify/bkit-graphify.sh spec)`). Another release draws
172
+ # different edges → drift no one else can reproduce. PyPI `graphifyy`, CLI `graphify`.
173
+ # renovate: datasource=pypi depName=graphifyy
174
+ GRAPHIFY_SPEC="graphifyy[sql]==0.9.50"
175
+ if [ "${1:-}" = "spec" ]; then
176
+ printf '%s\n' "$GRAPHIFY_SPEC"
177
+ exit 0
178
+ fi
179
+
167
180
  if ! command -v graphify >/dev/null 2>&1; then
168
- echo "[graph] graphify not found. Install: brew install uv && uv tool install \"graphifyy[sql]\"" >&2
181
+ echo "[graph] graphify not found. Install: brew install uv && uv tool install '$GRAPHIFY_SPEC'" >&2
169
182
  echo "[graph] If it is installed, ~/.local/bin is not on PATH — run: uv tool update-shell" >&2
170
183
  exit 1
171
184
  fi
185
+ case "${1:-build}" in
186
+ check | check-at | rollup | register | refresh)
187
+ have=$(graphify --version 2>/dev/null | awk '{print $2}')
188
+ if [ "$have" != "${GRAPHIFY_SPEC##*==}" ]; then
189
+ echo "[graph] graphify ${have:-?} is installed; the register is built with ${GRAPHIFY_SPEC##*==}." >&2
190
+ echo "[graph] Install that release: uv tool install --force '$GRAPHIFY_SPEC'" >&2
191
+ exit 1
192
+ fi
193
+ ;;
194
+ esac
172
195
 
173
196
  # cluster-only writes GRAPH_REPORT.md next to graph.json with no flag to
174
197
  # redirect it, so move it into $REPORTS afterwards under $R_REPORT.
@@ -187,8 +210,7 @@ cluster() {
187
210
 
188
211
  # Put back the imports graphify cannot resolve — a `.js` specifier never reaches
189
212
  # a `.tsx` file, and workspace subpaths through an `exports` map resolve to
190
- # nothing. ~540 edges here, 16% of relative imports. Upstream Graphify-Labs/
191
- # graphify#3486 and #3487, open on v8.
213
+ # nothing. Upstream Graphify-Labs/graphify#3486 and #3487, open on v8.
192
214
  #
193
215
  # Runs BEFORE cluster, so communities, the god-node ranking and the cycle list in
194
216
  # graph-report.md are computed from the repaired graph. Runs on every command that
@@ -254,6 +276,26 @@ strip_stamps() {
254
276
  -e 's/(Generated by bkit-graphify-rollup\.py from )[0-9a-f]+/\1<sha>/' "$1"
255
277
  }
256
278
 
279
+ # Run this script's subcommands in a throwaway checkout of ONE commit: graphify reads the
280
+ # working tree, so the build belongs to that commit, not to uncommitted edits here. Root
281
+ # node_modules is linked in for the route scan. $1 = commit; rest = subcommands, in order.
282
+ # $AT_DIR = the checkout.
283
+ at_commit() {
284
+ local rev="$1" sha tmp sub
285
+ shift
286
+ sha=$(git rev-parse --verify --quiet "$rev^{commit}") || { echo "[graph] not a commit: $rev" >&2; exit 2; }
287
+ tmp=$(mktemp -d "${TMPDIR:-/tmp}/graph-at-XXXXXX")
288
+ AT_DIR="$tmp/checkout"
289
+ # shellcheck disable=SC2064 # expand now: $tmp is local and gone by the time EXIT fires
290
+ trap "git worktree remove --force '$AT_DIR' >/dev/null 2>&1; rm -rf '$tmp'" EXIT
291
+ git -c core.hooksPath=/dev/null worktree add --detach --quiet "$AT_DIR" "$sha"
292
+ ln -s "$(git rev-parse --show-toplevel)/node_modules" "$AT_DIR/node_modules"
293
+ for sub in "$@"; do
294
+ (cd "$AT_DIR" && env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE \
295
+ GRAPHIFY_OUT=docs/graphify-out bash scripts/graphify/bkit-graphify.sh "$sub")
296
+ done
297
+ }
298
+
257
299
  case "${1:-build}" in
258
300
  build) run_local extract . --code-only && repair && cluster ;;
259
301
  clean) rm -rf "$OUT" && run_local extract . --code-only && repair && cluster ;;
@@ -298,16 +340,16 @@ case "${1:-build}" in
298
340
  ;;
299
341
  update) run_local update . && repair && cluster ;;
300
342
  check)
301
- # RELEASE GATE, not a hook. Rebuild the graph from this tree, regenerate the
302
- # register into a throwaway copy, and fail if it differs from the tracked
303
- # file. Nothing tracked is written, so a red here is a red you fix with
304
- # `pnpm graph:update && pnpm graph:rollup` plus a commit.
343
+ # Gate on every push to dev: pre-push runs it via `check-at` in a clean
344
+ # checkout of the pushed commit; CI runs it in its own clean checkout.
345
+ # Rebuild graph from this tree → regenerate register into a throwaway copy
346
+ # → fail if it differs from the tracked file. Writes nothing tracked; fix a
347
+ # red with `pnpm graph:refresh` plus a commit.
305
348
  #
306
- # Run it from a CLEAN checkout. graphify reads the working tree, not the
307
- # commit, so uncommitted edits surface here as drift that nobody else can
308
- # reproduce. After a tsconfig `paths` change run `pnpm graph:clean` first:
309
- # `update` keeps the stale module-resolution cache and the drift this
310
- # reports would then be the cache, not the register.
349
+ # By hand it reads the working tree, not the commit: uncommitted edits show
350
+ # as drift nobody else can reproduce. After a tsconfig `paths` change run
351
+ # `pnpm graph:clean` first: `update` keeps the stale module-resolution
352
+ # cache, and the drift reported would be the cache, not the register.
311
353
  if [ -n "$(git status --porcelain -- '*.ts' '*.tsx' 2>/dev/null)" ]; then
312
354
  echo "[graph] WARNING: uncommitted .ts/.tsx edits — graphify reads the WORKING TREE," >&2
313
355
  echo "[graph] so any diff below may be your own unstaged work, not committed drift." >&2
@@ -326,10 +368,28 @@ case "${1:-build}" in
326
368
  echo "[graph] $CAPABILITIES_DOC matches a rebuild at $(git rev-parse --short HEAD)."
327
369
  else
328
370
  echo "[graph] DRIFT: $CAPABILITIES_DOC is not what this tree produces (diff above)." >&2
329
- echo "[graph] Fix: pnpm graph:update && pnpm graph:rollup && git add $CAPABILITIES_DOC" >&2
371
+ echo "[graph] Fix: pnpm graph:refresh && git add $CAPABILITIES_DOC && git commit" >&2
330
372
  exit 1
331
373
  fi
332
374
  ;;
375
+ register)
376
+ # Tracked register only: `rollup` minus its HTML views (minutes of rendering `refresh`
377
+ # does not need). Needs a built graph.
378
+ capabilities "$CAPABILITIES_DOC"
379
+ ;;
380
+ check-at)
381
+ # `check` in a clean checkout of one commit (default HEAD); pre-push runs it for every
382
+ # push to dev.
383
+ at_commit "${2:-HEAD}" check
384
+ ;;
385
+ refresh)
386
+ # Rebuild the register in a clean checkout of HEAD → copy over the tracked file here.
387
+ # Fixes a `check` / `check-at` red without baking in uncommitted edits, as
388
+ # `graph:update && graph:rollup` would. Commit the result.
389
+ at_commit HEAD build register
390
+ cp "$AT_DIR/$CAPABILITIES_DOC" "$CAPABILITIES_DOC"
391
+ echo "[graph] $CAPABILITIES_DOC rebuilt from $(git rev-parse --short HEAD) — commit it"
392
+ ;;
333
393
  scoped)
334
394
  target="${2:-apps/web/src}"
335
395
  [ -d "$target" ] || { echo "[graph] no such directory: $target" >&2; exit 1; }
package/CHANGELOG.md CHANGED
@@ -8,6 +8,53 @@ Format: `## [version] — YYYY-MM-DD`
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [5.3.0] — 2026-10-19
12
+
13
+ ### Breaking Changes
14
+
15
+ - **BREAKING — Node 24 or newer is required.** `engines.node` rises from `>=20` to `>=24`, the version bkit's own CI and release already run on. A repo on Node 20 or 22 can no longer install or run this bkit; move to Node 24 first. This ships in a minor release: a `^5` range or a minor auto-merge picks it up, so pin `5.2.x` until the repo is on Node 24.
16
+
17
+ ### Added
18
+
19
+ - **Oxlint test-lint template.** New copy-and-own `.oxlintrc.json` fails lint on a test that cannot fail, in JS / TS repos: `vitest/expect-expect` (no assertion), `vitest/no-conditional-in-test` (branch inside a test), `vitest/no-conditional-expect` (`expect` that may never run), `vitest/valid-expect` (`maxArgs: 2`), type-aware `typescript/no-floating-promises` (unawaited promise). All other checks off. Covers `*.test.*` and `*.spec.*` only; skips `.bkit/templates/` and `scripts/ci/**/*.test.mjs`. Suggested `lint` script (`.bkit/templates.md` § Gate tool scripts) is now `oxlint -c .oxlintrc.json --type-aware --deny-warnings`; before, a repo without an ESLint config got a skip line that went green having checked nothing. bkit never edits your `package.json` → an existing `lint` value stays until you change it. Not ESLint: typescript-eslint's type-aware rules need TypeScript `<6.1`. `bkit tips` suggests it (tip `test-lint`) when `package.json` lists `vitest` or `jest` and the repo has no Oxlint config, no `oxlint` dependency and no ESLint config naming a test plugin; `bkit check` does not warn. `.bkit/templates.md` § Oxlint. #612
20
+ - **Trivy scan template.** New copy-and-own `.github/workflows/bkit-trivy.yml` fails CI on a HIGH or CRITICAL finding in any lockfile (npm, pnpm, yarn, pip, poetry, uv, Go, Cargo, Maven, …), in Dockerfile / Terraform / Kubernetes / Helm settings, and in secrets committed to tracked files, on push, pull request and daily. It runs the official Trivy image pinned by tag and digest, never `trivy-action` / `setup-trivy` by tag. It scans dev dependencies (Trivy's default skips them, so a dev-tooling lockfile scanned zero packages), skips `.bkit/templates/`, and leaves `pnpm-lock.yaml` to `Check Dependency Audit` once that gate is adopted. Accept a finding in `.trivyignore.yaml` with a reason and an expiry. `bkit tips` suggests it (tip `trivy`) when a repo has GitHub workflows and none runs Trivy; `bkit check` does not warn. `bkit-audit-security`, `bkit-audit-dependencies` and `docs/security.md` name it as a scanner. `.bkit/templates.md` § Trivy. #547
21
+ - **Issue form templates and one issue shape for every workflow.** New copy-and-own `.github/ISSUE_TEMPLATE/` with one form per way work starts: `bkit-idea.yml` (how it should work is open → `/bkit-design #N`), `bkit-change.yml` (well-defined change → `/bkit-plan #N`, or `/bkit-build #N` / `lite:build` with no plan; carries the plan in short: narrative, success criteria, edge cases, a test matrix, tasks with `Done when` + `Test first`) and `bkit-bug.yml` (a test or CI run already fails → `/bkit-debug #N`; nothing fails yet → `/bkit-build #N`). Each form ends with References showing the exact lines workflows read: `**Parent design:**`, `**Audit reports:**`, the blocked-by block. Stack-neutral; applies `enhancement` / `bug` only where the repo has them, never `bkit:*` labels. The shapes, their syntax and every line a workflow reads from an issue body are in the new `.bkit/trackers.md` § Issue shapes. `/bkit-plan` with no design and no audit report now takes a change issue as its source: narrative, success criteria, edge cases, test rows and tasks carry over verbatim. Issues agents draft follow the same shapes: `@bkit-audit-generate`'s `Recommended Next Step` asks for an `**Audit reports:**` line with each row's finding IDs, the design workflow's `Suggested Workstreams` comment gives the `**Parent design:**` line each workstream issue needs, and with 2+ workstreams `@bkit-design-summary` asks whether to file one issue each and points `/bkit-plan` at the first one, not the design's own issue, `@bkit-utility-update-roadmap` recommends filing an issue first for items that have none, and `.agents/rules.md` `Tracker issue creation` points at the shapes. `bkit tips` suggests the forms (tip `issue-forms`) for the GitHub tracker when `.github/ISSUE_TEMPLATE/` is absent. `.bkit/templates.md` § Issue forms. #339
22
+ - **`/bkit-debug [repro]` turns a bug report into a failing test first.** Debug used to stop at the summary when its first test run passed, so a bug nothing failed on yet got no fix. With `[repro]`, a first run that passes now fetches context (logs, CI, related issues) and hands it to a new subagent, `@bkit-debug-failure-reproduce`, in its own step (Step 5, Failure Reproduce). It writes one test failing on the reported symptom, never a fix, committed as `test({FID}): reproduce …`. Debug then re-runs the tests, which records that test failing, and the usual fix loop takes over. With `[soak]` too, the test repeats the scenario until an intermittent bug fails reliably, and the soak loop does the fixing. If no test can be made to fail on the symptom, the subagent removes its test changes and the summary ends `CONCERNS`, naming the evidence a rerun needs. Without `[repro]`, debug behaves as before. Steps 5–10 are now 6–11. The bug form, `.bkit/trackers.md`, `.bkit/templates.md` and both READMEs now send "nothing fails yet" to `/bkit-debug #N [repro]` instead of `/bkit-build`. #625
23
+
24
+ ### Changed
25
+
26
+ - **graphify: a push to dev is blocked when `docs/capabilities.md` is out of date.** The pasted pre-push block (`scripts/graphify/bkit-graph-pre-push.sh`) only printed a note, so a stale register reached dev and only CI's `Check Capability Register` caught it. Now push to dev → new `bkit-graphify.sh check-at <commit>` in a throwaway checkout of the pushed commit → blocked on mismatch; uncommitted edits (another session's included) cannot change the answer. graphify not installed → loud "NOT checked" warning, push goes on (CI still checks). Other branches keep the warn-only note, minus its `[skip ci]` advice. New `pnpm graph:refresh` rebuilds the register from a clean checkout of HEAD: the fix for a red gate. graphify release pinned once, `GRAPHIFY_SPEC` in `bkit-graphify.sh` (`spec` prints it): `check`, `check-at`, `rollup`, `register`, `refresh` refuse any other installed release; the CI step installs the same spec; the Renovate example scans `scripts/graphify/bkit-graphify.sh` for it. The pre-push template's ref loop sets `PUSH_DEV_SHA` for the block. Copy-and-own files `bkit upgrade` does not touch → re-copy `scripts/graphify/bkit-graphify.sh`, `bkit-graph-pre-push.sh`, the stdin loop from `.bkit/templates/.husky/pre-push` and the `Check Capability Register` step; add the `graph:refresh` script. `.bkit/templates.md` § graphify.
27
+ - **Shipped `docs/testing.md` rules: a missing tool fails loudly, and lint covers test files.** A test needing a binary, CLI or interpreter resolves it via one shared helper that throws when absent, never an early `return` that passes having asserted nothing. A test that self-skips on an absent tool must not skip on CI: install the tool on that lane, or fail when `CI` is set. § Static: lint covers test files (no assertion, conditional inside a test, conditional `expect`, unawaited promise); Oxlint template = optional JS / TS start. `bkit upgrade` refreshes the managed block. #609 #610 #612
28
+ - **The testing audit looks for test linters and for absence guards outliving their writer.** `docs/templates/bkit-audit-testing.md` Step 8 names Oxlint's `vitest` and `typescript` plugins (`typescript/no-floating-promises` with `--type-aware`) beside the ESLint ones, also counts `vitest/no-conditional-expect`, and notes typescript-eslint's type-aware rules need a TypeScript version it supports. Step 7 gains a shape: a guard asserting a file, path or name is not written, shipped or listed when no source writes it any more and no migration removes it → passes whatever leaks. Secret guards and removal checks for a still-running migration stay. #612
29
+ - **The pipeline reference has its own file, `.bkit/pipeline.md`.** Every subagent in execution order, the pipeline map, the CI scaffold and the table of all 35 audit templates moved out of `.bkit/comparison.md`, which now holds only the comparisons: with other AI development frameworks first, then with _Agentic Design Patterns_. The pipeline tables no longer state a model or effort per subagent; `.bkit/prompts.md` § Models is the one place for those. Headings that other docs link to carry fixed ids (`#bkit-design` … `#bkit-ship`, `#pipeline-map`, `#ci-scaffold`, `#frameworks`, `#patterns`), so rewording a heading no longer breaks links. `bkit upgrade` adds the new file.
30
+ - **Shared agent rules cover trackers, test reporting, worktrees, guarded migrations and secrets.** `.agents/rules.md` `Universal Rules` gain: under `Workflows & Process`, `Tracker issue creation` (suggest, never file without a yes), `Tracker issue settings` (title max 70 characters; set every field the tracker offers), `Tracker issue mentions` (always with title and URL) and `Tracker work comments` (one outcome comment per landed unit outside `/bkit-*` workflows); under `Testing & Debugging`, `Name the suites you ran`, `One runner, two callers` (local and CI call the same tier script), `Tests move with code` and `New worktree` (`direnv allow` before the first command); under `Security & Data`, Migrations with `IF EXISTS`/`IF NOT EXISTS` MUST self-assert, `FK and immutability` and `Secrets sync` (through `scripts/secrets/bkit-secrets.mjs`, never a provider CLI). Delete any copies of these from your `Project Rules` after `bkit upgrade`.
31
+ - **Lite workflows live at `.bkit/lite.md`** (was `.agents/shortcuts.md`), each named for its phase: `lite:design`, `lite:plan`, `lite:build`, `lite:debug`, `lite:ship`. Each paste prompt now dispatches every kept subagent step to its `bkit-*` subagent on its `.bkit/prompts.md` § Models model and never inlines that work (a host with no subagent tool runs the subagent's prompt file in-session), and the paste section says to start the session on the phase's § Orchestrators model. The consumer section below `bkit:end` is `## Project Lite Workflows`. `@bkit-audit-generate`'s `Next Step` values are `lite:build` / `lite:debug` (were `shortcut:build` / `shortcut:debug`), and `@bkit-utility-update-roadmap` names the `lite:<phase>` it recommends. `bkit upgrade` moves an existing `.agents/shortcuts.md`: anything you added below `<!-- bkit:end -->` lands below it in `.bkit/lite.md`, and the old file is deleted.
32
+ - **Workflow tips heading is `## bkit Tips`** (was `## Setup Tips`). `bkit tips` output now ends with "Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!", after the tips and outside the cap, so every workflow close shows it last. Add `star` to `bkit.ignoreAdvisories` to switch it off. It never appears in `.bkit/advisories.md` or the install banner.
33
+ - **Cursor and OpenCode get the same GitHub MCP tools as Claude Code.** The `github` entry bkit writes into `.cursor/mcp.json` now sends `X-MCP-Toolsets` (it sent none, so Cursor got GitHub's default set), and the one in `.opencode/opencode.json` adds `actions`. Every host now enables `context,issues,pull_requests,repos,users,projects,actions`, so CI logs and artifacts (`actions_list`, `get_job_logs`, `download_workflow_run_artifact`) are reachable from Cursor and OpenCode too, not only from `.mcp.json`. Existing installs pick it up on the next `bkit install` / `bkit upgrade`.
34
+ - **You can add to bkit's tracker MCP entry without drift.** bkit used to own every byte of the `github` / `linear` entry in `.mcp.json`, `.cursor/mcp.json` and `.opencode/opencode.json`: one extra toolset failed `bkit check` (so pre-push and CI) and the next install deleted it. bkit now owns only what its template sets. Extra keys and headers are yours, and `X-MCP-Toolsets` keeps your list and gains any toolset bkit's template has that yours lacks. A changed URL or `Authorization` value is still reset. `.bkit/providers.md` § MCP server config. #613
35
+ - **Audit and ledger-update summaries offer a plain-English explanation too.** `@bkit-audit-generate`, `@bkit-utility-update-roadmap`, `@bkit-utility-update-documentation` and the four `.jsonl` updaters (`decisions`, `deferrals`, `failures`, `knowledge`) now end their summary with `Would you like me to explain this in plain English?`, as the phase workflows do. The shared `.bkit/wording.md` clause is renamed `plain-english-append` and covers prompts as well as workflows.
36
+ - **Audit and ledger-update summaries show a setup tip too.** `@bkit-audit-generate` runs `bkit tips --workflow=audit`, and `@bkit-utility-update-roadmap` and the four `.jsonl` updaters run `bkit tips --workflow=utility`. Each appends what it prints under `## bkit Tips`, just before the plain-English question, as the phase workflows do. `audit` puts Serena, the CI workflow, graphify, the dependency updater and Trivy first; `utility` puts Serena first. The tracker, GitHub token, `.bkit/.env` and direnv tips still lead everywhere until fixed. Neither ends with the star line, because these agents often run back to back. `@bkit-utility-update-documentation` has no Bash, so it shows no tip. The three `workflow-setup-tips-*` clauses in `.bkit/wording.md` now cover prompts too. #543
37
+ - **The coverage template shows your floor in every run summary.** In the `bkit-stub:coverage` block of `.github/workflows/bkit-ci.yml`, the unit report step is now `Report Unit Coverage`. It runs on every push and pull request, including when the unit run fails, and writes the measured coverage next to the 🎯 floor into the run's job summary. It still comments only on pull requests from the same repo. The stub now puts the floor in a `vitest.unit.config.ts` that only the unit run loads (`-c`), and the report reads it from there through `vite-config-path`; a `--coverage.thresholds.branches` flag still gates but cannot be shown. The template is copy-and-own: an adopted copy changes only if you copy the new step.
38
+ - **`/bkit-build` with no plan proves test-first for an issue's Tasks.** When the build input carries `- [ ] **Task N:**` lines with `**Test first:**` (the change-issue shape), each named test must now fail before its code exists, as with a plan: the execute agent works those Tasks by number, Step 7.6 runs `bkit tests green --brief=<build input>`, and a test that never failed is a FAIL. `bkit tests green` gains `--brief`, used only when no `--plan` file exists. A brief without Task lines still builds from its outcomes and is not checked; a missing `Done when` is not a FAIL. `lite:build` checks neither. #626
39
+
40
+ ### Fixed
41
+
42
+ - **graphify: no false "graph-repair" warning on a repaired graph.** `bkit-graph-eager.py` and `bkit-graphify-rollup.py` warned `graph.json carries no graph-repair edges ... ~540 imports` whenever no injected link was left, which also happens when graphify already resolves every import or when clustering merges the injected link into graphify's own (two files importing each other). They now re-derive the imports from source and warn only when graph.json actually lacks some, with the real count. The `docs/capabilities.md` header names `pnpm graph:refresh`. Copy-and-own → re-copy `scripts/graphify/bkit-graph-imports.py`, `bkit-graph-eager.py`, `bkit-graphify-rollup.py`, `bkit-graph-repair.py`, `bkit-graphify.sh`. `.bkit/templates.md` § graphify.
43
+ - **Pushes no longer fail when a pre-push hook prints more than 1MB.** `runGit` captured git's output under Node's 1MB default, so a chatty hook (e.g. a full unit run with coverage) got `git push` killed mid-hook and `bkit branches push` / `land` / ship's `dev` sync exited 8 with a cut-off log and no cause. `runGit` now shares `runTool`'s 64 MiB limit, and both put any spawn error at the top of `stderr`, naming `ENOBUFS` and the limit. `runTool` reports `found: false` ("not found on PATH") only when the binary could not be started, so an overflow no longer sends `gh` callers down the MCP fallback. Output past the limit always counts as a failure, also when the program exits 0 before Node stops reading; `bkit ledgers` git reads follow the same rule. #586
44
+ - **`/bkit-plan` on the design's own issue now plans from that design.** The plan already reused the design's FID there, but loaded the design only through a `**Parent design:**` line, so with none it planned from the issue text alone. Step 1 now falls back to the new `bkit fids design --fid=<FID>`, which finds `docs/plans/{YYYYMM}/{FID}-design.md`. `.bkit/workflows.md` no longer says design and plan never share a FID. #624
45
+ - **`/bkit-debug` pushes a fix only when a fix step ran.** Step 3 decided "a fix preceded this pass" by counting test runs, so on the `[repro]` path a reproduce test that failed once and then passed on the re-run went to Step 9 Push Remediation with a `test({FID})` commit as HEAD. Step 3 now routes on which steps ran: a remediate or soak row → Step 9; a reproduce row with no fix since → Step 10 Summary, graded `CONCERNS`. `bkit counters route --of=<step>,<step>:count` sums the rows of several steps in one call.
46
+ - **The network allowlist is `.bkit/allowlist.json`, written on every install.** The guardrail hooks for Cursor, Codex, Claude and Antigravity read the hosts `curl` / `wget` may reach from `.cursor/allowlist.json`, which only the Cursor module wrote, so a Codex-only or Antigravity-only install (or `bkit uninstall --cursor`) flagged every fetch while `bkit check` stayed green. Core now writes `.bkit/allowlist.json` whatever hosts you install; `bkit check` reports it missing or stale. `bkit upgrade` deletes a `.cursor/allowlist.json` that `.bkit/version` records as bkit's; one bkit never recorded is left alone. `docs/migrations.md`.
47
+ - **Antigravity's guardrail hook finds the allowlist.** Antigravity runs plugin hooks from `.agents/plugins/bkit/`, so the hook never found the allowlist and flagged fetches to allowed hosts. Hooks now look from the workspace folders the event names, then their own folder, walking up to the `.git` root.
48
+ - **Claude Code and opencode deny more force-push forms.** New deny globs cover a git option before `push` (`git -C dir push --force`, `git -c k=v push origin +main`) and `f` second in a short-flag cluster (`git push -uf`). `--force-with-lease` stays allowed. `f` third or later in a cluster (`-uvf`) still passes on these two hosts; the Cursor, Codex and Antigravity hooks parse the command and deny it. `.bkit/providers.md` § Permissions.
49
+ - **The Claude Code on the web setup script installs Node 24.** It installed vale, gh and jq but left the image's Node 20 / 22, below bkit's `>=24`. It now installs Node 24.21.0 into `/usr/local`, sha256-checked, at the same version and checksum as the Cursor Dockerfile, before corepack runs. A test fails when the two pins differ. Re-paste the setup script from `.claude/bkit-cloud.md`.
50
+ - **The cloud notes say where `.envrc` comes from.** With no `.envrc`, they said `bkit install` seeds one; it does not. They now say to copy `.bkit/templates/.envrc` to the repo root.
51
+ - **`bkit status` / `doctor` show the opencode model.** They read a top-level model from `.opencode/opencode.json`, which bkit never writes, so they always printed "model: unknown". They now read each agent's `model:` from `.opencode/agents/`.
52
+ - **Switching `--tracker` removes the old tracker's MCP entry.** Going from `linear` to `github` kept the `linear` entry in `.mcp.json`, `.cursor/mcp.json` and `.opencode/opencode.json`. Install now removes it when it still equals bkit's template; an entry you edited stays, with a warning. The `github` entry always stays: workflows fall back to it when `gh` is missing.
53
+ - **`bkit uninstall --opencode=<provider>` on the active provider keeps `bkit check` green.** It left that provider's model pins, so `bkit check` exited 1 until `bkit upgrade`. It now re-pins the opencode agents and commands to the first remaining provider.
54
+ - **`bkit upgrade --to=<version>` installs when only the source differs.** With `package.json` pointing bkit at a `file:` tarball, link, git or other non-registry spec of the same version, it printed "already at" and skipped `pnpm add`. It now bumps.
55
+ - **`bkit doctor` and `bkit check` help no longer says read-only.** Both rewrite `.bkit/advisories.md`; the help, `docs/setup.md` and `docs/deployments.md` now say so.
56
+ - **The pipeline reference lists the utility subagents.** `.bkit/pipeline.md` gains a Utilities section with the seven `bkit-utility-*` subagents, matching its "49 in total" count.
57
+
11
58
  ## [5.2.4] — 2026-10-17
12
59
 
13
60
  ### Added
@@ -997,7 +1044,7 @@ Patch release. bkit's canonical reference docs now land in a consumer's `.bkit/`
997
1044
 
998
1045
  ### Changed
999
1046
 
1000
- - **Schema-invariant DB checks reframed — pick the route by deploy topology, not by local pgTAP availability (consumer feedback from gether; refines [#203](https://github.com/cbartens/bkit/issues/203)).** pgTAP and the `@live` catalog-RPC are now presented as two co-equal routes rather than "canonical" vs "remote-only fallback". pgTAP runs against a CI-local fixture built from `supabase/migrations` (fast, hermetic, offline — but can stay green while prod drifts); the `@live` catalog-RPC validates the **real deployed schema** in `bkit-tests-live` and is the recommended default once a consumer has a deploy + `@live` tier (RLS/tenancy invariants especially). Reworded across the three surfaces — the template `ci.yml` stubs (incl. the JOB 3 `@live` block), the `test-db` install/check advisory, and `docs/testing.md` (+ template). Framing/docs only; no scaffold behaviour change.
1047
+ - **Schema-invariant DB checks reframed — pick the route by deploy topology, not by local pgTAP availability (consumer feedback from consumer-a; refines [#203](https://github.com/cbartens/bkit/issues/203)).** pgTAP and the `@live` catalog-RPC are now presented as two co-equal routes rather than "canonical" vs "remote-only fallback". pgTAP runs against a CI-local fixture built from `supabase/migrations` (fast, hermetic, offline — but can stay green while prod drifts); the `@live` catalog-RPC validates the **real deployed schema** in `bkit-tests-live` and is the recommended default once a consumer has a deploy + `@live` tier (RLS/tenancy invariants especially). Reworded across the three surfaces — the template `ci.yml` stubs (incl. the JOB 3 `@live` block), the `test-db` install/check advisory, and `docs/testing.md` (+ template). Framing/docs only; no scaffold behaviour change.
1001
1048
 
1002
1049
  ---
1003
1050
 
@@ -1084,7 +1131,7 @@ Major consolidation release. Three structural shifts land together: bkit's own m
1084
1131
  ### Fixed
1085
1132
 
1086
1133
  - **2.8.0 shipped prose that failed bkit's own Vale write-good gate, blocking consumer upgrade commits (issue [#195](https://github.com/cbartens/bkit/issues/195)).** `docs/deployments.md` contained a sentence-initial "So" — a pattern flagged by the write-good `StartsWith` rule that bkit ships and consumers run on every commit/push. The root cause was a lint asymmetry: bkit's own `lint:prose` script covered only `docs/knowledge.md`, not the full `docs/*.md` corpus, so the prose bkit was authoring and shipping was never linted by the same gate bkit imposes on consumers. Fixed by rewording the offending sentence ("So" → "This means") in both `docs/deployments.md` and its shipped template source, and widening `lint:prose` in bkit's own `package.json` to cover `docs/*.md` and `.agents/templates/docs/**` (parity with the consumer gate). Consumers re-run `pnpm bkit upgrade` to reconverge `docs/deployments.md` with zero drift (verified live).
1087
- - **bkit's own `lint:prose` did not cover the shipped template docs (issue [#195](https://github.com/cbartens/bkit/issues/195)).** `.agents/templates/docs/**` was absent from the Vale glob, meaning prose regressions in template sources were invisible until a consumer installed them. The template docs are now included in bkit's lint pass. KN-29 records the lint-asymmetry root cause and Vale `gether` config learnings for future reference.
1134
+ - **bkit's own `lint:prose` did not cover the shipped template docs (issue [#195](https://github.com/cbartens/bkit/issues/195)).** `.agents/templates/docs/**` was absent from the Vale glob, meaning prose regressions in template sources were invisible until a consumer installed them. The template docs are now included in bkit's lint pass. KN-29 records the lint-asymmetry root cause and Vale `consumer-a` config learnings for future reference.
1088
1135
  - **Shipped `.vale.ini` lacked write-good exemptions for `docs/plans/**`and`docs/notes.md`(issue [#195](https://github.com/cbartens/bkit/issues/195)).** LLM-generated plan documents and notes routinely contain phrasing that triggers write-good/LLMSlop rules. Without exemptions, consumers running`pnpm lint:prose`on a repo with bkit-generated plan docs would get false-positive failures. The shipped`.vale.ini`template (a`seedOrPrint`file — reaches new consumers on seed; existing consumers merge manually) now excludes`docs/plans/\*\*`and`docs/notes.md` from the write-good and LLMSlop style checks.
1089
1136
 
1090
1137
  ---
@@ -1436,7 +1483,7 @@ Major consolidation release. Three structural shifts land together: bkit's own m
1436
1483
  ### Added
1437
1484
 
1438
1485
  - **`utility-new-release` agent prompt** (`.claude/agents/utility-new-release.md` + `.agents/templates/`) — codifies the dev → main → tag → publish flow so future cuts avoid the KN-20 silent-skip trap (explicit scrubbed squash body, post-tag Release-workflow verification).
1439
- - **`lint-staged` adoption** — bkit pre-commit hook (consumer template + bkit-repo) now runs `pnpm lint-staged` so staged files are formatted via `prettier --write` at commit time. Pre-push keeps `pnpm format:check` as the safety net for hook-bypass cases (--no-verify, GitHub web edits, stale local config). Matches gether's pattern.
1486
+ - **`lint-staged` adoption** — bkit pre-commit hook (consumer template + bkit-repo) now runs `pnpm lint-staged` so staged files are formatted via `prettier --write` at commit time. Pre-push keeps `pnpm format:check` as the safety net for hook-bypass cases (--no-verify, GitHub web edits, stale local config). Matches consumer-a's pattern.
1440
1487
  - **`.lintstagedrc.json` seed** — `bkit install` writes the lint-staged config (`"*": "prettier --write --ignore-unknown"`) as Tier-3 (seed-or-print) and adds `lint-staged` to consumer devDependencies so the new pre-commit call resolves without manual setup.
1441
1488
 
1442
1489
  ### Changed