@cbartens/bkit 6.1.0 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -141,8 +141,23 @@ export interface RowBy {
141
141
  * exactly when `subagent` is set.
142
142
  */
143
143
  model?: string;
144
+ /**
145
+ * Where `model` came from: `observed` (the host reported it) or `unavailable` (the host
146
+ * reported nothing, so `model` is absent). Absent on rows written before provenance.
147
+ */
148
+ modelSource?: ModelSource;
149
+ /** The pin the subagent was launched with; never the model it ran on. Subagent rows only. */
150
+ configuredModel?: string;
151
+ /** The host that ran the subagent, when known. */
152
+ host?: string;
153
+ /** Fields a newer writer adds survive normalization. */
154
+ [field: string]: unknown;
144
155
  }
145
156
 
157
+ /** Provenance of a subagent row's model: the host reported it, or reported nothing. */
158
+ export type ModelSource = "observed" | "unavailable";
159
+ export const MODEL_SOURCES: ReadonlySet<string> = new Set<ModelSource>(["observed", "unavailable"]);
160
+
146
161
  /** The bkit that wrote a row; `chat` rows add what the chat did with bkit. */
147
162
  export interface BkitBlock {
148
163
  /** bkit version stamped on every row for regression attribution; null on a chat / run row when unknown. */
@@ -182,6 +197,8 @@ export interface TelemetryEnvelope {
182
197
  * never an identity: `ts` (with `key` for keyed kinds) identifies the row.
183
198
  */
184
199
  references?: string[];
200
+ /** Lifecycle or triage status on the kinds that carry one; narrowed by each payload. */
201
+ status?: string;
185
202
  }
186
203
 
187
204
  /** The identity block of every row that belongs to one workflow run. */
@@ -429,17 +446,8 @@ export const KIND_WRITERS: Record<AppendKind, KindWriters> = {
429
446
  // Utility: a direct chat outside any workflow (`by.step` `manual`), the owner deciding in it.
430
447
  deferral: { subagents: DEFERRAL_WRITERS, orchestrators: new Set(["build", "ship", "utility"]) },
431
448
  failure: { subagents: ANY_WRITER, orchestrators: ANY_WRITER },
432
- knowledge: {
433
- subagents: new Set([
434
- "bkit-build-plan-tests",
435
- "bkit-build-plan-tasks",
436
- "bkit-build-plan-gaps-remediate",
437
- "bkit-debug-failure-remediate",
438
- "bkit-utility-update-knowledge",
439
- ]),
440
- // Utility: a direct chat outside any workflow (`by.step` `manual`), the owner deciding in it.
441
- orchestrators: new Set(["utility"]),
442
- },
449
+ // Any agent on a discovered gotcha (`.agents/rules.md` Discovered gotchas).
450
+ knowledge: { subagents: ANY_WRITER, orchestrators: ANY_WRITER },
443
451
  friction: {
444
452
  subagents: new Set(),
445
453
  // Utility: a direct chat outside any workflow (`by.step` `manual`) that meets friction.
@@ -472,7 +480,8 @@ export function writerProblem(row: Record<string, unknown>): string | undefined
472
480
  if (typeof subagent !== "string" || subagent === "") {
473
481
  return "by.subagent must be a non-empty string";
474
482
  }
475
- if (typeof by["model"] !== "string" || by["model"] === "") {
483
+ const unavailable = by["modelSource"] === "unavailable" && by["model"] === undefined;
484
+ if (!unavailable && (typeof by["model"] !== "string" || by["model"] === "")) {
476
485
  return `subagent ${subagent} row missing by.model (its prompt's frontmatter model:)`;
477
486
  }
478
487
  if (writers.subagents === ANY_WRITER || writers.subagents.has(subagent)) return undefined;
@@ -1571,7 +1580,7 @@ export function validate(event: unknown): ValidationResult {
1571
1580
  if (typeof by["step"] !== "string" || by["step"] === "") {
1572
1581
  return { ok: false, reason: "by.step must be a non-empty string" };
1573
1582
  }
1574
- for (const f of ["workflow", "subagent", "model"]) {
1583
+ for (const f of ["workflow", "subagent", "model", "configuredModel", "host"]) {
1575
1584
  if (by[f] !== undefined && (typeof by[f] !== "string" || by[f] === "")) {
1576
1585
  return { ok: false, reason: `by.${f} must be a non-empty string when present` };
1577
1586
  }
@@ -1579,6 +1588,26 @@ export function validate(event: unknown): ValidationResult {
1579
1588
  if (by["model"] !== undefined && by["subagent"] === undefined) {
1580
1589
  return { ok: false, reason: "by.model is set only on subagent rows" };
1581
1590
  }
1591
+ if (by["modelSource"] !== undefined) {
1592
+ if (typeof by["modelSource"] !== "string" || !MODEL_SOURCES.has(by["modelSource"])) {
1593
+ return { ok: false, reason: "by.modelSource must be observed|unavailable when present" };
1594
+ }
1595
+ if (by["subagent"] === undefined) {
1596
+ return { ok: false, reason: "by.modelSource is set only on subagent rows" };
1597
+ }
1598
+ if (by["modelSource"] === "unavailable" && by["model"] !== undefined) {
1599
+ return {
1600
+ ok: false,
1601
+ reason: "by.model must be absent when by.modelSource is unavailable",
1602
+ };
1603
+ }
1604
+ if (by["modelSource"] === "observed" && by["model"] === undefined) {
1605
+ return { ok: false, reason: "by.modelSource observed needs by.model" };
1606
+ }
1607
+ }
1608
+ if (by["configuredModel"] !== undefined && by["subagent"] === undefined) {
1609
+ return { ok: false, reason: "by.configuredModel is set only on subagent rows" };
1610
+ }
1582
1611
  if (e["references"] !== undefined && !Array.isArray(e["references"])) {
1583
1612
  return { ok: false, reason: "references must be an array when present" };
1584
1613
  }
@@ -1930,6 +1959,79 @@ export function fold(events: TelemetryEvent[]): FoldedState {
1930
1959
  return state;
1931
1960
  }
1932
1961
 
1962
+ // ---------------------------------------------------------------------------
1963
+ // Query — canonical winners, filtered after the fold, with located line diagnostics
1964
+ // ---------------------------------------------------------------------------
1965
+
1966
+ /** A ledger line the query could not read as a row. */
1967
+ export interface LineDiagnostic {
1968
+ /** 1-based line number in the file as read. */
1969
+ line: number;
1970
+ reason: "malformed-json" | "not-an-object" | "invalid-timestamp" | "invalid-identity";
1971
+ }
1972
+
1973
+ export interface LedgerQuery {
1974
+ key?: string;
1975
+ status?: string;
1976
+ }
1977
+
1978
+ export interface LedgerQueryResult {
1979
+ /** The fold winners that pass the filter, oldest `ts` first, equal `ts` by identity. */
1980
+ rows: TelemetryEvent[];
1981
+ diagnostics: LineDiagnostic[];
1982
+ /** Non-blank lines read. */
1983
+ lines: number;
1984
+ /** Rows read before folding. */
1985
+ readRows: number;
1986
+ }
1987
+
1988
+ /** Statuses of the keyed lifecycle kinds: a row with no `status` is ACTIVE. */
1989
+ const DEFAULT_ACTIVE_KINDS: ReadonlySet<string> = new Set(["decision", "knowledge"]);
1990
+
1991
+ /**
1992
+ * The canonical ledger read: parse every line (reporting each unreadable one with its line
1993
+ * number), fold with {@link fold}, and only then apply `filter` to the winners, so an older
1994
+ * row a newer winner superseded is never resurrected. Pure and read-only.
1995
+ */
1996
+ export function queryLedger(raw: string, filter: LedgerQuery = {}): LedgerQueryResult {
1997
+ const diagnostics: LineDiagnostic[] = [];
1998
+ const events: TelemetryEvent[] = [];
1999
+ let lines = 0;
2000
+ raw.split("\n").forEach((text, i) => {
2001
+ const trimmed = text.trim();
2002
+ if (trimmed === "") return;
2003
+ lines++;
2004
+ const obj = parseJson(trimmed);
2005
+ if (!obj.ok) diagnostics.push({ line: i + 1, reason: "malformed-json" });
2006
+ else if (obj.value === null || typeof obj.value !== "object" || Array.isArray(obj.value))
2007
+ diagnostics.push({ line: i + 1, reason: "not-an-object" });
2008
+ else {
2009
+ const row = obj.value as Record<string, unknown>;
2010
+ const ts = row["ts"];
2011
+ if (typeof ts !== "number" || !Number.isFinite(ts))
2012
+ diagnostics.push({ line: i + 1, reason: "invalid-timestamp" });
2013
+ else if (
2014
+ typeof row["kind"] !== "string" ||
2015
+ (AGED_KINDS.has(row["kind"]) && (typeof row["key"] !== "string" || row["key"] === ""))
2016
+ )
2017
+ diagnostics.push({ line: i + 1, reason: "invalid-identity" });
2018
+ events.push(obj.value as TelemetryEvent);
2019
+ }
2020
+ });
2021
+ const winners = [...fold(events).entries()].sort(
2022
+ ([ia, a], [ib, b]) => compareTs(a, b) || (ia < ib ? -1 : ia > ib ? 1 : 0),
2023
+ );
2024
+ const rows = winners
2025
+ .map(([, e]) => e)
2026
+ .filter((e) => {
2027
+ if (filter.key !== undefined && e.key !== filter.key) return false;
2028
+ if (filter.status === undefined) return true;
2029
+ const status = e.status ?? (DEFAULT_ACTIVE_KINDS.has(String(e.kind)) ? "ACTIVE" : undefined);
2030
+ return status === filter.status;
2031
+ });
2032
+ return { rows, diagnostics, lines, readRows: events.length };
2033
+ }
2034
+
1933
2035
  // ---------------------------------------------------------------------------
1934
2036
  // Lineage — the entry age + row count a fold winner carries (AGED_KINDS)
1935
2037
  // ---------------------------------------------------------------------------
@@ -75,7 +75,8 @@ function block(name: string): string {
75
75
  * (Standalone `false` blocks not attached to a pair are handled in pass 2.)
76
76
  */
77
77
  const GROUP_RE = new RegExp(
78
- block("github") +
78
+ "([ \\t]*)" +
79
+ block("github") +
79
80
  "\\s*" +
80
81
  block("linear") +
81
82
  "(?:\\s*" +
@@ -88,7 +89,7 @@ const GROUP_RE = new RegExp(
88
89
 
89
90
  /** Conditional-keep block, KEEP form (markers stripped, content trimmed in place). */
90
91
  function condKeepRe(name: "true" | "false"): RegExp {
91
- return new RegExp(block(name), "g");
92
+ return new RegExp("([ \\t]*)" + block(name), "g");
92
93
  }
93
94
  /** Conditional-keep block, REMOVE form (consumes the leading newline + indent). */
94
95
  function condDropRe(name: "true" | "false"): RegExp {
@@ -110,6 +111,14 @@ function trimKeptContent(s: string): string {
110
111
  return s.replace(/^\r?\n[ \t]*/, "").replace(/\r?\n[ \t]*$/, "");
111
112
  }
112
113
 
114
+ /** Retain indentation only when the replacement leaves content on its line. */
115
+ function attachPrefix(prefix: string, body: string, head: string, tail: string): string {
116
+ // Only the current line of `head` matters; scanning the whole document prefix is quadratic.
117
+ const lastLine = head.slice(Math.max(head.lastIndexOf("\n"), head.lastIndexOf("\r")) + 1);
118
+ const hardBreak = / {2,}$/.test(prefix) && /\S/.test(lastLine);
119
+ return !hardBreak && /^[ \t]*(?:\r?\n|$)/.test(body + tail) ? body : prefix + body;
120
+ }
121
+
113
122
  // ---------------------------------------------------------------------------
114
123
  // Resolution
115
124
  // ---------------------------------------------------------------------------
@@ -137,13 +146,31 @@ export function substituteWorkflow(
137
146
  let pairs = 0;
138
147
  let output = workflowContent.replace(
139
148
  GROUP_RE,
140
- (match, gh: string, ln: string, jira: string | undefined, falseBody: string | undefined) => {
149
+ (
150
+ match,
151
+ prefix: string,
152
+ gh: string,
153
+ ln: string,
154
+ jira: string | undefined,
155
+ falseBody: string | undefined,
156
+ offset: number,
157
+ ) => {
141
158
  if (tracker === "jira" && jira === undefined) return match;
142
159
  pairs++;
143
- if (tracker === "github") return trimKeptContent(gh);
144
- if (tracker === "linear") return trimKeptContent(ln);
145
- if (tracker === "jira") return trimKeptContent(jira!);
146
- return falseBody !== undefined ? trimKeptContent(falseBody) : NONE_STUB;
160
+ const body =
161
+ tracker === "github"
162
+ ? gh
163
+ : tracker === "linear"
164
+ ? ln
165
+ : tracker === "jira"
166
+ ? jira!
167
+ : (falseBody ?? NONE_STUB);
168
+ return attachPrefix(
169
+ prefix,
170
+ trimKeptContent(body),
171
+ workflowContent.slice(0, offset),
172
+ workflowContent.slice(offset + match.length),
173
+ );
147
174
  },
148
175
  );
149
176
 
@@ -153,10 +180,18 @@ export function substituteWorkflow(
153
180
  for (const name of ["true", "false"] as const) {
154
181
  const active = name === "true" ? wired : !wired;
155
182
  if (active) {
156
- output = output.replace(condKeepRe(name), (_m, content: string) => {
157
- conditionals++;
158
- return trimKeptContent(content);
159
- });
183
+ output = output.replace(
184
+ condKeepRe(name),
185
+ (match, prefix: string, content: string, offset: number) => {
186
+ conditionals++;
187
+ return attachPrefix(
188
+ prefix,
189
+ trimKeptContent(content),
190
+ output.slice(0, offset),
191
+ output.slice(offset + match.length),
192
+ );
193
+ },
194
+ );
160
195
  } else {
161
196
  output = output.replace(condDropRe(name), () => {
162
197
  conditionals++;
@@ -19,9 +19,13 @@ export const PACKAGE_RUNNER = "pnpm";
19
19
  /** argv for running one `package.json` script, e.g. `bkit:gate:static-unit`. */
20
20
  export const scriptCommand = (script: string): string[] => [PACKAGE_RUNNER, script];
21
21
 
22
- /** argv for installing dependencies; `frozen` refuses to change the lockfile. */
23
- export const installCommand = (opts: { frozen: boolean }): string[] =>
24
- opts.frozen ? [PACKAGE_RUNNER, "install", "--frozen-lockfile"] : [PACKAGE_RUNNER, "install"];
22
+ /** argv for installing dependencies; `frozen` refuses to change the lockfile, `preferOffline` reads the local store first. */
23
+ export const installCommand = (opts: { frozen: boolean; preferOffline?: boolean }): string[] => [
24
+ PACKAGE_RUNNER,
25
+ "install",
26
+ ...(opts.frozen ? ["--frozen-lockfile"] : []),
27
+ ...(opts.preferOffline ? ["--prefer-offline"] : []),
28
+ ];
25
29
 
26
30
  /**
27
31
  * argv that regenerates a lockfile from its manifest, keyed by lockfile name.
@@ -88,6 +88,7 @@ export interface TaskCaps {
88
88
  export const ASK_POINTS = [
89
89
  "design.grill",
90
90
  "build.verify",
91
+ "build.holistic",
91
92
  "build.challenge",
92
93
  "build.tests",
93
94
  "debug.fix",
@@ -131,7 +132,7 @@ export interface BkitConfig {
131
132
  ciRequired: string[];
132
133
  /**
133
134
  * Globs (`:(glob)` git pathspecs) for paths a push may carry, on top of what bkit's
134
- * workflows write (ship's bookkeeping allow-list, `docs/plans/**`, `ciSkipPaths`), and
135
+ * workflows write (ship's bookkeeping allow-list, `docs/plans/**`, `docs/audits/**`, `ciSkipPaths`), and
135
136
  * still run only `bkit:gate:min` in `.husky/pre-push`; empty = that floor alone.
136
137
  */
137
138
  minPushPaths: string[];
@@ -163,6 +164,8 @@ export interface BkitConfig {
163
164
  depUpdater: DepUpdater | "none" | null;
164
165
  /** `bkit.tracker.default` is set, so `none` is a choice; absent or `""` (what install seeds) = undecided. */
165
166
  issueTrackerExplicit: boolean;
167
+ /** `bkit.tracker.default` as written when it is set but names no tracker bkit knows; else null. */
168
+ issueTrackerUnknown: string | null;
166
169
  /** `bkit.cloud.agent` is set, so `none` is a choice; absent or `""` (what install seeds) = undecided. */
167
170
  cloudAgentsExplicit: boolean;
168
171
  }
@@ -207,6 +210,7 @@ export const CONFIG_DEFAULTS: Readonly<BkitConfig> = {
207
210
  asks: {
208
211
  "design.grill": { ask: true, max: 6 },
209
212
  "build.verify": { ask: true, max: 2 },
213
+ "build.holistic": { ask: true, max: 2 },
210
214
  "build.challenge": { ask: true, max: 2 },
211
215
  "build.tests": { ask: true, max: 2 },
212
216
  "debug.fix": { ask: true, max: 2 },
@@ -218,6 +222,7 @@ export const CONFIG_DEFAULTS: Readonly<BkitConfig> = {
218
222
  buildPublish: { remote: true, local: true },
219
223
  depUpdater: null,
220
224
  issueTrackerExplicit: false,
225
+ issueTrackerUnknown: null,
221
226
  cloudAgentsExplicit: false,
222
227
  };
223
228
 
@@ -413,6 +418,12 @@ export function readBkitConfig(root: string): BkitConfig {
413
418
  buildPublish: buildPublish(record(workflows.build).publish),
414
419
  depUpdater: parseDepUpdater(record(bkit.dependencies).updater),
415
420
  issueTrackerExplicit: tracker.default !== undefined && tracker.default !== "",
421
+ issueTrackerUnknown:
422
+ tracker.default !== undefined &&
423
+ tracker.default !== "" &&
424
+ parseIssueTracker(tracker.default) === null
425
+ ? String(tracker.default)
426
+ : null,
416
427
  cloudAgentsExplicit: cloud.agent !== undefined && cloud.agent !== "",
417
428
  };
418
429
  }
@@ -29,6 +29,20 @@ const isRecord = (v: unknown): v is Record<string, unknown> =>
29
29
  const escapeLine = (s: string): string =>
30
30
  s.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
31
31
 
32
+ /**
33
+ * A free-text value for one line of Markdown: each run of line breaks, tabs and other
34
+ * control characters becomes one space, and the ends are trimmed. With `max`, a longer
35
+ * result is cut to `max` characters, the last one `…`.
36
+ */
37
+ export function oneLine(value: string, max?: number): string {
38
+ const isControl = (ch: string): boolean => ch < " " || ch === "\u007f";
39
+ const folded = Array.from(value, (ch) => (isControl(ch) ? "\n" : ch))
40
+ .join("")
41
+ .replace(/\n+/g, " ")
42
+ .trim();
43
+ return max !== undefined && folded.length > max ? `${folded.slice(0, max - 1)}…` : folded;
44
+ }
45
+
32
46
  const scalarText = (v: Scalar): string => (v === null ? "null" : String(v));
33
47
 
34
48
  const NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
@@ -303,6 +303,7 @@ export function syncRules(store: string, masters: RuleMasters): string {
303
303
  /** Hook files whose messages `## Hook Text` copies. */
304
304
  export const HOOK_SOURCES = [
305
305
  ".bkit/core/hooks/gateguard-engine.js",
306
+ ".bkit/core/hooks/guardrails-deny.js",
306
307
  ".bkit/core/hooks/guardrails-read.js",
307
308
  ".bkit/core/hooks/guardrails-shell.js",
308
309
  ".bkit/core/hooks/guardrails-tiers.js",
@@ -252,7 +252,6 @@ const DOC_DIRS = [
252
252
  ".bkit/core/.agents",
253
253
  ".bkit/core/.bkit",
254
254
  ".bkit/shared",
255
- ".bkit/shared/docs",
256
255
  ".bkit/shared/.cursor/rules",
257
256
  ];
258
257
  const DOC_FILE = /\.mdc?$/;
@@ -651,8 +650,13 @@ function siblingsOf(canonical: string, allTexts: Set<string>): string[] {
651
650
  }
652
651
  let hit = byText.get(canonical);
653
652
  if (!hit) {
653
+ const { words, counts } = canonicalParts(canonical);
654
654
  hit = [...allTexts].filter(
655
- (t) => t !== canonical && !compileText(t).slotted && similarity(t, canonical) >= NEAR_COPY,
655
+ (t) =>
656
+ t !== canonical &&
657
+ !compileText(t).slotted &&
658
+ nearCandidate(canonicalParts(t).words, words, counts) &&
659
+ similarity(t, canonical) >= NEAR_COPY,
656
660
  );
657
661
  byText.set(canonical, hit);
658
662
  }
@@ -1343,42 +1347,72 @@ function citeFiles(ix: CoverageIndex, name: string): CorpusFile[] {
1343
1347
  const lineHolds = (file: CorpusFile, line: number, excerpt: string) =>
1344
1348
  (file.content.split("\n")[line - 1] ?? "").includes(excerpt);
1345
1349
 
1346
- /** Findings for the both-ways check of the store against the corpus. */
1347
- export function checkCoverage(store: string, corpus: CorpusFile[]): string[] {
1348
- const out: string[] = [];
1349
- const ix = coverageIndex(store, corpus);
1350
- const partialOf = new Map<string, string[]>();
1350
+ /** File id → the sentences of each rule the file carries partially. */
1351
+ function partialSentences(ix: CoverageIndex): Map<string, string[]> {
1352
+ const out = new Map<string, string[]>();
1351
1353
  for (const r of ix.rules) {
1352
1354
  for (const { file } of ruleCarriers(ix, r, ["partial"])) {
1353
- partialOf.set(file.id, [...(partialOf.get(file.id) ?? []), ...splitSentences(r.text)]);
1355
+ out.set(file.id, [...(out.get(file.id) ?? []), ...splitSentences(r.text)]);
1354
1356
  }
1355
1357
  }
1356
- const localOf = new Map<string, LocalEntry[]>();
1358
+ return out;
1359
+ }
1360
+
1361
+ /** File id → its own local entries plus the shared lines that list it as a carrier. */
1362
+ function localEntriesOf(ix: CoverageIndex, out?: string[]): Map<string, LocalEntry[]> {
1363
+ const byFile = new Map<string, LocalEntry[]>();
1357
1364
  for (const e of ix.local) {
1358
- if (e.file !== undefined) localOf.set(e.file, [...(localOf.get(e.file) ?? []), e]);
1365
+ if (e.file !== undefined) byFile.set(e.file, [...(byFile.get(e.file) ?? []), e]);
1359
1366
  else {
1360
1367
  for (const [surface, names] of sharedCarriers(e.carriers ?? "", ix.namesOf)) {
1361
1368
  for (const n of names) {
1362
1369
  const f = ix.byName(surface, n);
1363
1370
  if (!f) {
1364
- out.push(`shared line: carrier \`${n}\` is no ${surface} file: ${e.text}`);
1371
+ out?.push(`shared line: carrier \`${n}\` is no ${surface} file: ${e.text}`);
1365
1372
  continue;
1366
1373
  }
1367
- localOf.set(f.id, [...(localOf.get(f.id) ?? []), e]);
1374
+ byFile.set(f.id, [...(byFile.get(f.id) ?? []), e]);
1368
1375
  }
1369
1376
  }
1370
1377
  }
1371
1378
  }
1379
+ return byFile;
1380
+ }
1381
+
1382
+ /** The standing lines of `f` that no local entry, clause, rule or partial rule sentence covers. */
1383
+ function uncoveredLines(
1384
+ ix: CoverageIndex,
1385
+ f: CorpusFile,
1386
+ local: LocalEntry[],
1387
+ partial: string[],
1388
+ ): { line: number; text: string }[] {
1389
+ const own = new Set(local.map((e) => e.text));
1390
+ return ix.standing
1391
+ .get(f.id)!
1392
+ .filter(
1393
+ ({ text }) =>
1394
+ !own.has(text) &&
1395
+ !ix.clauseForms.some((c) => c.re.test(text)) &&
1396
+ !ix.rules.some((r) => text.includes(r.text)) &&
1397
+ !partial.some((s) => text.includes(s)),
1398
+ );
1399
+ }
1400
+
1401
+ /** Findings for the both-ways check of the store against the corpus. */
1402
+ export function checkCoverage(store: string, corpus: CorpusFile[]): string[] {
1403
+ const out: string[] = [];
1404
+ const ix = coverageIndex(store, corpus);
1405
+ const partialOf = partialSentences(ix);
1406
+ const localOf = localEntriesOf(ix, out);
1372
1407
 
1373
1408
  // Nothing missing.
1374
1409
  for (const f of ix.files) {
1375
- const own = new Set((localOf.get(f.id) ?? []).map((e) => e.text));
1376
- const partial = partialOf.get(f.id) ?? [];
1377
- for (const { line, text } of ix.standing.get(f.id)!) {
1378
- if (own.has(text)) continue;
1379
- if (ix.clauseForms.some((c) => c.re.test(text))) continue;
1380
- if (ix.rules.some((r) => text.includes(r.text))) continue;
1381
- if (partial.some((s) => text.includes(s))) continue;
1410
+ for (const { line, text } of uncoveredLines(
1411
+ ix,
1412
+ f,
1413
+ localOf.get(f.id) ?? [],
1414
+ partialOf.get(f.id) ?? [],
1415
+ )) {
1382
1416
  out.push(`${f.id}:${line}: no entry — add under #### ${f.name}: ${text}`);
1383
1417
  }
1384
1418
  }
@@ -1652,6 +1686,65 @@ export function similarEntries(store: string): string[] {
1652
1686
  return out;
1653
1687
  }
1654
1688
 
1689
+ /** How alike a reworded line must stay to its stored copy for `refreshLocal` to pair them. */
1690
+ export const REFRESH_MIN = 0.5;
1691
+
1692
+ /**
1693
+ * The store with each per-file local entry whose line was reworded in place rewritten to the
1694
+ * new wording, tags kept, and one `{file}: {old} → {new}` note per rewrite. A stale entry pairs
1695
+ * with an uncovered line of its file only when the line sits between the file lines of the
1696
+ * nearest unchanged entries before and after it in the store, is at least `REFRESH_MIN` alike,
1697
+ * and no other pairing scores the same for either side; pairs never cross. A deleted line, a
1698
+ * new line and a shared line stay as findings for a person to settle.
1699
+ */
1700
+ export function refreshLocal(
1701
+ store: string,
1702
+ corpus: CorpusFile[],
1703
+ ): { store: string; refreshed: string[] } {
1704
+ const ix = coverageIndex(store, corpus);
1705
+ const partialOf = partialSentences(ix);
1706
+ const localOf = localEntriesOf(ix);
1707
+ const lines = store.split("\n");
1708
+ const refreshed: string[] = [];
1709
+ for (const f of ix.files) {
1710
+ const own = ix.local.filter((e) => e.file === f.id).sort((a, b) => a.at - b.at);
1711
+ const standing = ix.standing.get(f.id)!;
1712
+ const lineOf = own.map((e) => standing.find((s) => s.text === e.text)?.line);
1713
+ const uncovered = uncoveredLines(ix, f, localOf.get(f.id) ?? [], partialOf.get(f.id) ?? []);
1714
+ const pairs: { entry: number; line: number; text: string; score: number }[] = [];
1715
+ own.forEach((e, i) => {
1716
+ if (lineOf[i] !== undefined) return;
1717
+ const before = lineOf.slice(0, i).filter((n): n is number => n !== undefined);
1718
+ const after = lineOf.slice(i + 1).find((n): n is number => n !== undefined);
1719
+ const lo = before.length > 0 ? Math.max(...before) : 0;
1720
+ const hi = after ?? Infinity;
1721
+ for (const u of uncovered) {
1722
+ if (u.line <= lo || u.line >= hi) continue;
1723
+ const score = similarity(e.text, u.text);
1724
+ if (score >= REFRESH_MIN) pairs.push({ entry: i, line: u.line, text: u.text, score });
1725
+ }
1726
+ });
1727
+ const tied = (p: (typeof pairs)[number]) =>
1728
+ pairs.some(
1729
+ (q) => q !== p && q.score === p.score && (q.entry === p.entry || q.line === p.line),
1730
+ );
1731
+ const taken: typeof pairs = [];
1732
+ for (const p of [...pairs].sort((a, b) => b.score - a.score)) {
1733
+ if (tied(p)) continue;
1734
+ if (taken.some((t) => t.entry === p.entry || t.line === p.line)) continue;
1735
+ if (taken.some((t) => t.entry < p.entry !== t.line < p.line)) continue;
1736
+ taken.push(p);
1737
+ }
1738
+ for (const p of taken.sort((a, b) => a.entry - b.entry)) {
1739
+ const e = own[p.entry]!;
1740
+ const at = lines[e.at]!;
1741
+ lines[e.at] = at.slice(0, at.length - e.text.length) + p.text;
1742
+ refreshed.push(`${f.name}: ${e.text} → ${p.text}`);
1743
+ }
1744
+ }
1745
+ return { store: lines.join("\n"), refreshed };
1746
+ }
1747
+
1655
1748
  /** The store with shared-line carriers and drift line numbers recomputed from the corpus. */
1656
1749
  export function syncCoverage(store: string, corpus: CorpusFile[]): string {
1657
1750
  const ix = coverageIndex(store, corpus);
@@ -1763,7 +1856,10 @@ function main(argv: string[]): number {
1763
1856
  console.error(`[bkit-instructions] rewrote ${id}`);
1764
1857
  }
1765
1858
  files = loadCorpus(root);
1766
- const synced = syncCoverage(syncStore(store, files), files);
1859
+ const fresh = refreshLocal(syncStore(store, files), files);
1860
+ for (const r of fresh.refreshed)
1861
+ console.error(`[bkit-instructions] refreshed local entry ${r}`);
1862
+ const synced = syncCoverage(fresh.store, files);
1767
1863
  if (synced !== store) {
1768
1864
  fs.writeFileSync(storeFile, synced, "utf-8");
1769
1865
  console.error(`[bkit-instructions] rewrote ${STORE_PATH}`);
@@ -60,6 +60,19 @@ function agRetryFile(hook, sessionId) {
60
60
  * its own process, so a deny it cannot record would block every retry.
61
61
  */
62
62
  function adviseOnce(hook, sessionId, signature, advisory) {
63
+ return adviseOnceDelivery(hook, sessionId, signature, advisory).decision;
64
+ }
65
+
66
+ const AG_RETRY_SUFFIX =
67
+ "\nThis call was held once so you see this advisory. Repeat the same call to proceed.";
68
+
69
+ /**
70
+ * `adviseOnce` with its transport outcome: `{ decision, delivered }`. `delivered` is true
71
+ * only when the call was denied with the advisory as the reason. An identical retry or an
72
+ * unusable retry store returns the bare allow with `delivered` false, so the caller leaves
73
+ * the advised targets unacknowledged.
74
+ */
75
+ function adviseOnceDelivery(hook, sessionId, signature, advisory) {
63
76
  const file = agRetryFile(hook, sessionId);
64
77
  // One-way digest of the call signature: the retry store is world-readable and has no
65
78
  // TTL, so no tool argument (a shell command line with an inline secret, a file path)
@@ -69,15 +82,18 @@ function adviseOnce(hook, sessionId, signature, advisory) {
69
82
  const last = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
70
83
  if (last === digest) {
71
84
  fs.rmSync(file, { force: true });
72
- return { decision: "allow" };
85
+ return { decision: { decision: "allow" }, delivered: false };
73
86
  }
74
87
  fs.mkdirSync(path.dirname(file), { recursive: true });
75
88
  fs.writeFileSync(file, digest, "utf-8");
76
89
  } catch {
77
- return { decision: "allow" };
90
+ return { decision: { decision: "allow" }, delivered: false };
78
91
  }
79
92
  return {
80
- decision: "deny",
81
- reason: `${advisory}\nThis call was held once so you see this advisory. Repeat the same call to proceed.`,
93
+ decision: {
94
+ decision: "deny",
95
+ reason: `${advisory}${AG_RETRY_SUFFIX}`,
96
+ },
97
+ delivered: true,
82
98
  };
83
99
  }
@@ -1,6 +1,8 @@
1
- // Edit / Write / MultiEdit payload adapter, shared by the Claude Code and Cursor hooks:
2
- // `{ tool_name, tool_input: { file_path | path }, session_id }`.
3
- const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
1
+ // Edit / Write / MultiEdit / NotebookEdit / Delete payload adapter, shared by the Claude Code
2
+ // and Cursor hooks: `{ tool_name, tool_input: { file_path | path | notebook_path }, session_id,
3
+ // cwd }`. `NotebookEdit` (Claude) names its target `notebook_path`; `Delete` (Cursor) uses
4
+ // `file_path`.
5
+ const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit", "Delete"]);
4
6
 
5
7
  // Pure: takes the already-parsed hook payload, returns the advisory to emit or
6
8
  // null. Never touches process.stdin / process.stdout — the driver below owns both.
@@ -10,9 +12,10 @@ const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
10
12
  function bkitGateguard(payload) {
11
13
  if (!EDIT_TOOLS.has(payload.tool_name)) return null;
12
14
  const input = payload.tool_input || {};
13
- const filePath = input.file_path || input.path;
15
+ const filePath = input.file_path || input.path || input.notebook_path;
14
16
  // A Write to a not-yet-existing path is a NEW file and gets the reuse checklist.
15
17
  const isNewFile =
16
18
  payload.tool_name === "Write" && typeof filePath === "string" && !fs.existsSync(filePath);
17
- return firstTouchAdvice(filePath, dedupKey(payload.session_id, payload.agent_id), isNewFile);
19
+ const cwd = typeof payload.cwd === "string" ? payload.cwd : undefined;
20
+ return firstTouchAdvice(filePath, dedupKey(payload.session_id, payload.agent_id), isNewFile, cwd);
18
21
  }