@cbartens/bkit 5.1.0 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +90 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  136. package/.bkit/templates/.prettierignore +1 -1
  137. package/.bkit/templates/context/bkit-expo.md +22 -13
  138. package/.bkit/templates/context/bkit-github.md +20 -6
  139. package/.bkit/templates/context/bkit-inngest.md +10 -4
  140. package/.bkit/templates/context/bkit-maestro.md +5 -5
  141. package/.bkit/templates/context/bkit-playwright.md +3 -3
  142. package/.bkit/templates/context/bkit-sentry.md +6 -5
  143. package/.bkit/templates/context/bkit-stripe.md +31 -8
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  145. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  147. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  148. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  149. package/.bkit/templates/slop-scan.config.json +7 -2
  150. package/CHANGELOG.md +42 -0
  151. package/LICENSE.md +21 -161
  152. package/README.md +58 -28
  153. package/dist/checks/after/auth.js +28 -0
  154. package/dist/checks/after/github.js +4 -4
  155. package/dist/checks/after/index.js +29 -45
  156. package/dist/checks/after/managed.js +40 -1
  157. package/dist/checks/before/index.js +5 -4
  158. package/dist/checks/before/mcp.js +53 -53
  159. package/dist/checks/status-holes.js +1 -1
  160. package/dist/checks/tips/catalogue.js +297 -0
  161. package/dist/checks/tips/detect.js +130 -0
  162. package/dist/checks/tips/index.js +146 -0
  163. package/dist/cli.js +47 -9
  164. package/dist/commands/install/doctor.js +5 -1
  165. package/dist/commands/install/install.js +27 -7
  166. package/dist/commands/install/uninstall.js +31 -16
  167. package/dist/commands/install/upgrade.js +15 -32
  168. package/dist/commands/launch.js +27 -11
  169. package/dist/commands/tips.js +10 -0
  170. package/dist/commands/workflow/runs.js +52 -16
  171. package/dist/commands/workflow/runtime.js +8 -0
  172. package/dist/commands/workflow/steps.js +1 -0
  173. package/dist/commands/workflow/tests.js +541 -4
  174. package/dist/commands/workflow/workstreams.js +4 -4
  175. package/dist/install/cloud-env.js +3 -14
  176. package/dist/install/hosts.js +22 -0
  177. package/dist/install/managed-block.js +36 -0
  178. package/dist/install/manifest.js +45 -4
  179. package/dist/install/modules/antigravity.js +8 -7
  180. package/dist/install/modules/claude.js +6 -6
  181. package/dist/install/modules/cloud.js +2 -2
  182. package/dist/install/modules/codex.js +5 -5
  183. package/dist/install/modules/core.js +14 -5
  184. package/dist/install/modules/cursor.js +6 -6
  185. package/dist/install/modules/opencode.js +4 -4
  186. package/dist/install/payload-links.js +5 -5
  187. package/dist/install/placeholders.js +1 -1
  188. package/dist/install/version-file.js +12 -3
  189. package/dist/install/write.js +61 -2
  190. package/dist/shared/package-roots.js +8 -11
  191. package/package.json +4 -6
  192. package/.bkit/core/LICENSE.md +0 -149
  193. package/.bkit/shared/LICENSE.md +0 -22
  194. package/.bkit/templates/LICENSE.md +0 -22
@@ -39,19 +39,13 @@ const BASELINE_TOKEN_PLACEHOLDERS = [
39
39
  "<PAT — fine-grained one owner / classic across owners; see .bkit/cloud.md § BKIT_GH_TOKEN token permissions>",
40
40
  ],
41
41
  ];
42
- // Earlier-compaction override — a bkit constant, not a secret. Appended to the
43
- // block when not already resolved from a source file. Claude-harness-only knob —
44
- // Cursor has no equivalent, so it is NOT in the Cursor policy's constants.
45
- const AUTOCOMPACT_KEY = "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE";
46
- const AUTOCOMPACT_VALUE = "70";
47
- // Claude Code on the web: GitHub tracker, autocompact override.
42
+ // Claude Code on the web: GitHub tracker.
48
43
  export const CLAUDE_CLOUD_POLICY = {
49
44
  baseline: BASELINE_TOKEN_PLACEHOLDERS,
50
- constants: [[AUTOCOMPACT_KEY, AUTOCOMPACT_VALUE]],
51
45
  };
52
46
  // Cursor Background Agents: `BKIT_LINEAR_API_KEY` prepended for the Linear tracker
53
47
  // (bkit-preflight.sh calls the Linear GraphQL API and hard-fails without it); GitHub
54
- // tracker uses the same GH baseline as Claude, minus the autocompact knob.
48
+ // tracker uses the same GH baseline as Claude.
55
49
  const CURSOR_LINEAR_PLACEHOLDER = [
56
50
  "BKIT_LINEAR_API_KEY",
57
51
  "<Linear personal API key — https://linear.app/settings/api>",
@@ -61,7 +55,6 @@ export function cursorCloudPolicy(tracker) {
61
55
  baseline: tracker === "linear"
62
56
  ? [CURSOR_LINEAR_PLACEHOLDER, ...BASELINE_TOKEN_PLACEHOLDERS]
63
57
  : BASELINE_TOKEN_PLACEHOLDERS,
64
- constants: [],
65
58
  };
66
59
  }
67
60
  /** Strip one layer of matching surrounding single/double quotes. */
@@ -185,7 +178,7 @@ export function resolveCloudEnvVars(cwd, policy = CLAUDE_CLOUD_POLICY) {
185
178
  }
186
179
  /**
187
180
  * Render the `.env`-format paste block: resolved KEY=value lines, then placeholder
188
- * lines for any absent baseline token, then the autocompact override if unset.
181
+ * lines for any absent baseline token.
189
182
  */
190
183
  export function renderCloudEnvBlock(res, policy = CLAUDE_CLOUD_POLICY) {
191
184
  const lines = [];
@@ -195,10 +188,6 @@ export function renderCloudEnvBlock(res, policy = CLAUDE_CLOUD_POLICY) {
195
188
  if (res.placeholders.includes(name))
196
189
  lines.push(`${name}=${placeholder}`);
197
190
  }
198
- for (const [key, value] of policy.constants) {
199
- if (!res.included.some(([k]) => k === key))
200
- lines.push(`${key}=${value}`);
201
- }
202
191
  return lines.join("\n");
203
192
  }
204
193
  function fmtList(items) {
@@ -0,0 +1,22 @@
1
+ // install/hosts.ts — which host modules a consumer has installed.
2
+ import * as fs from "node:fs";
3
+ import * as path from "node:path";
4
+ /**
5
+ * Detect which host modules a consumer has installed, by the presence of each host's
6
+ * source-rendered agents directory. `bkit upgrade` re-renders only these hosts — never
7
+ * force-creating an opencode/cursor tree — and setup tips key host-specific advice on them.
8
+ */
9
+ export function detectInstalledHostModules(cwd) {
10
+ const mods = new Set();
11
+ if (fs.existsSync(path.join(cwd, ".claude", "agents")))
12
+ mods.add("claude");
13
+ if (fs.existsSync(path.join(cwd, ".cursor", "agents")))
14
+ mods.add("cursor");
15
+ if (fs.existsSync(path.join(cwd, ".opencode", "agents")))
16
+ mods.add("opencode");
17
+ if (fs.existsSync(path.join(cwd, ".codex", "agents")))
18
+ mods.add("codex");
19
+ if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
20
+ mods.add("antigravity");
21
+ return mods;
22
+ }
@@ -118,6 +118,42 @@ export function detectMarkerStyle(content) {
118
118
  }
119
119
  return null;
120
120
  }
121
+ // Verbatim long lines a text must share with a block, beside its title, to count as a copy.
122
+ const COPY_MIN_SHARED_LINES = 10;
123
+ // Shortest trimmed line counted as shared; shorter lines (rules, `>`, table dividers) recur by chance.
124
+ const COPY_MIN_LINE_LENGTH = 40;
125
+ // Lines outside fenced code blocks; a shell comment in a fence (`# Vercel errors`) is no heading.
126
+ function proseLines(text) {
127
+ const out = [];
128
+ let inFence = false;
129
+ for (const line of text.split("\n")) {
130
+ if (line.trimStart().startsWith("```")) {
131
+ inFence = !inFence;
132
+ continue;
133
+ }
134
+ if (!inFence)
135
+ out.push(line);
136
+ }
137
+ return out;
138
+ }
139
+ // The block's `# ` title when `text` holds an older unmarked copy of the same markdown block:
140
+ // the title line plus COPY_MIN_SHARED_LINES long lines verbatim, all outside fenced code.
141
+ // Null otherwise, including for a block with no title.
142
+ export function findUnmarkedCopy(text, block) {
143
+ const blockLines = proseLines(block);
144
+ const title = blockLines.find((l) => /^# \S/.test(l));
145
+ if (title === undefined)
146
+ return null;
147
+ const textLines = proseLines(text);
148
+ if (!textLines.includes(title))
149
+ return null;
150
+ const long = new Set(blockLines.map((l) => l.trim()).filter((l) => l.length >= COPY_MIN_LINE_LENGTH));
151
+ let shared = 0;
152
+ for (const l of new Set(textLines.map((t) => t.trim())))
153
+ if (long.has(l))
154
+ shared++;
155
+ return shared >= COPY_MIN_SHARED_LINES ? title : null;
156
+ }
121
157
  // Remove the bkit-managed block (including marker lines) from a string,
122
158
  // preserving all consumer-owned content outside the block.
123
159
  //
@@ -85,9 +85,8 @@ const CORE_MANIFEST = [
85
85
  { path: ".bkit/comparison.md", format: "byte-equal-text", module: "core" },
86
86
  { path: ".bkit/install.md", format: "byte-equal-text", module: "core" },
87
87
  { path: ".bkit/jsonl.md", format: "byte-equal-text", module: "core" },
88
- // The PolyForm notice that travels with every file bkit writes (the managed-version
89
- // marker names the licence and its URL; this file carries both full texts and the
90
- // Required Notice). Sourced from `.bkit/core/.bkit/LICENSE.md`.
88
+ // The MIT notice that travels with the files bkit writes: the full text and copyright
89
+ // notice. Sourced from `.bkit/core/.bkit/LICENSE.md`.
91
90
  { path: ".bkit/LICENSE.md", format: "byte-equal-text", module: "core" },
92
91
  { path: ".bkit/providers.md", format: "byte-equal-text", module: "core" },
93
92
  { path: ".bkit/prompts.md", format: "markered-text", module: "core" },
@@ -113,6 +112,13 @@ const CLAUDE_MANIFEST = [
113
112
  format: "markered-text",
114
113
  module: "claude",
115
114
  },
115
+ // ReadGuard advisory repeat-read hook — same ownership split as GateGuard. Wired in
116
+ // .claude/settings.json → PreToolUse (matcher `Read|Bash`) and PreCompact.
117
+ {
118
+ path: ".claude/hooks/bkit-readguard.cjs",
119
+ format: "markered-text",
120
+ module: "claude",
121
+ },
116
122
  // bkit-guardrails.cjs — Tier-2 markered-text, twin of the Cursor/Codex hooks.
117
123
  // PreToolUse matcher `Bash`. ADVISORY ONLY: covers URL hosts and shell-as-edit-channel;
118
124
  // never denies or asks.
@@ -211,6 +217,13 @@ export const BKIT_BUILD_GATES = [
211
217
  "bkit:gate:static-unit-integration",
212
218
  "bkit:gate:static-unit",
213
219
  ];
220
+ /**
221
+ * Runs ONE test file — `pnpm bkit:test:file <repo-relative path>` — and writes a JUnit
222
+ * report to `$BKIT_TEST_REPORT`. `/bkit-build` records each task's red and audits its
223
+ * green through it. Never seeded: no default works on every stack; install advises
224
+ * when it is missing (detectGateAdvisories).
225
+ */
226
+ export const BKIT_TEST_FILE_SCRIPT = "bkit:test:file";
214
227
  /**
215
228
  * The deeper gates, shallowest first, with what declaring each one costs.
216
229
  *
@@ -257,6 +270,14 @@ const CURSOR_MANIFEST = [
257
270
  format: "markered-text",
258
271
  module: "cursor",
259
272
  },
273
+ // ReadGuard for Cursor — same managed block as the Claude twin. Wired in
274
+ // .cursor/hooks.json → preToolUse (matcher "Read|Shell") and preCompact, without
275
+ // failClosed.
276
+ {
277
+ path: ".cursor/hooks/bkit-readguard.cjs",
278
+ format: "markered-text",
279
+ module: "cursor",
280
+ },
260
281
  // Curl/wget host allowlist read at runtime by bkit-guardrails.cjs. No template backs it —
261
282
  // `writeNetworkAllowlistArtifact` (install/cloud-env.ts) computes the domain set from the
262
283
  // consumer's own config, so it is `generated` and its hash is in `canonicalHashes`.
@@ -293,6 +314,12 @@ export const OPENCODE_MANIFEST = [
293
314
  format: "markered-text",
294
315
  module: "opencode",
295
316
  },
317
+ // bkit-readguard.js — same split as bkit-gateguard.js.
318
+ {
319
+ path: ".opencode/plugin/bkit-readguard.js",
320
+ format: "markered-text",
321
+ module: "opencode",
322
+ },
296
323
  // Agent and command mirrors are managed dynamically (not listed individually here —
297
324
  // the exact set depends on the bkit-prefix prompt/workflow files at install time).
298
325
  // Uninstall uses the BKIT_PREFIX filter for .opencode/agents/ and .opencode/commands/.
@@ -312,6 +339,13 @@ export const CODEX_MANIFEST = [
312
339
  format: "markered-text",
313
340
  module: "codex",
314
341
  },
342
+ // bkit-readguard.cjs — Tier-2 markered-text, twin of the Claude hook. Registered on
343
+ // PreToolUse matcher `Bash` (Codex has no read tool) and PreCompact.
344
+ {
345
+ path: ".codex/hooks/bkit-readguard.cjs",
346
+ format: "markered-text",
347
+ module: "codex",
348
+ },
315
349
  // bkit-guardrails.cjs — Tier-2 markered-text, twin of the Cursor hook (same decision
316
350
  // engine). Registered on matcher `Bash`, Codex's shell tool name. Codex parses but
317
351
  // does not implement `permissionDecision: "ask"`, so the deny tier blocks for real
@@ -344,8 +378,15 @@ export const ANTIGRAVITY_MANIFEST = [
344
378
  format: "markered-text",
345
379
  module: "antigravity",
346
380
  },
381
+ // bkit-readguard.cjs — Tier-2 markered-text, twin of the Claude hook. Registered on
382
+ // matcher `view_file|run_command`.
383
+ {
384
+ path: ".agents/plugins/bkit/hooks/bkit-readguard.cjs",
385
+ format: "markered-text",
386
+ module: "antigravity",
387
+ },
347
388
  // bkit-guardrails.cjs — Tier-2 markered-text, twin of the Cursor/Codex hook. Registered
348
- // on matcher `run_command`, Antigravity's shell tool name.
389
+ // on matcher `view_file|run_command`, Antigravity's file-read and shell tool names.
349
390
  {
350
391
  path: ".agents/plugins/bkit/hooks/bkit-guardrails.cjs",
351
392
  format: "markered-text",
@@ -172,10 +172,10 @@ export function runAntigravityModule(ctx) {
172
172
  console.log(`${logPrefix} ${tag}antigravity: ${jsonDst}`);
173
173
  }
174
174
  }
175
- // --- bkit-gateguard.cjs — Tier-2 markered-text, twin of the Claude/Codex hook ---
176
- {
177
- const hookSrc = path.join(pluginHooksSrc, "bkit-gateguard.cjs");
178
- const hookDst = path.join(ANTIGRAVITY_HOOKS_DIR, "bkit-gateguard.cjs");
175
+ // --- bkit-gateguard.cjs / bkit-readguard.cjs — Tier-2 markered-text, twins of the Claude/Codex hooks ---
176
+ for (const hook of ["bkit-gateguard.cjs", "bkit-readguard.cjs"]) {
177
+ const hookSrc = path.join(pluginHooksSrc, hook);
178
+ const hookDst = path.join(ANTIGRAVITY_HOOKS_DIR, hook);
179
179
  if (fs.existsSync(hookSrc)) {
180
180
  if (!dryRun)
181
181
  ensureDir(path.dirname(hookDst));
@@ -186,8 +186,9 @@ export function runAntigravityModule(ctx) {
186
186
  }
187
187
  }
188
188
  // --- bkit-guardrails.cjs — Tier-2 markered-text, twin of the Cursor/Codex hook ---
189
- // Registered on matcher `run_command` in hooks.json above. Same decision engine as the
190
- // other hosts; the deny tier blocks for real.
189
+ // Registered on matcher `view_file|run_command` in hooks.json above. Same decision engine
190
+ // as the other hosts (shell tiers; read tiers shared with Cursor); the deny tier blocks
191
+ // for real.
191
192
  {
192
193
  const railSrc = path.join(pluginHooksSrc, "bkit-guardrails.cjs");
193
194
  const railDst = path.join(ANTIGRAVITY_HOOKS_DIR, "bkit-guardrails.cjs");
@@ -207,7 +208,7 @@ export function runAntigravityModule(ctx) {
207
208
  action: "Three things that differ from the other hosts:\n" +
208
209
  "1. Workflows are SKILLS here, not slash commands: Antigravity discovers them under `.agents/plugins/bkit/skills/bkit-<wf>/SKILL.md` (the plugin activates per project — no toggle).\n" +
209
210
  "2. There is no native subagent tool. The orchestrator loads each subagent prompt from `.agents/plugins/bkit/agents/` with `view_file` and executes it in-session; isolated runs use `run_command` (`agy`).\n" +
210
- "3. GateGuard and guardrails are wired from `.agents/plugins/bkit/hooks.json` (PreToolUse on `write_to_file` / `replace_file_content` / `run_command`). See .bkit/providers.md.",
211
+ "3. GateGuard, ReadGuard and guardrails are wired from `.agents/plugins/bkit/hooks.json` (PreToolUse on `write_to_file` / `replace_file_content` / `view_file` / `run_command`). See .bkit/providers.md.",
211
212
  });
212
213
  // Both hosts installed: Antigravity's skill selector lists TWO sets of bkit-* skills.
213
214
  // Codex does not merge same-named skills; Antigravity lists both. Warn which to pick.
@@ -98,13 +98,13 @@ export function runClaudeModule(ctx) {
98
98
  }
99
99
  }
100
100
  }
101
- // markered-text (slash-comment) — GateGuard advisory PreToolUse hook. bkit owns
101
+ // markered-text (slash-comment) — GateGuard and ReadGuard advisory hooks. bkit owns
102
102
  // only the advisory engine between the markers; consumers own the stdin/stdout
103
- // driver from first install onward (env vars BKIT_GATEGUARD / BKIT_ALLOW_CONFIG_EDIT
104
- // still tune behaviour, same as before).
105
- {
106
- const src = path.join(claudeHooks, "bkit-gateguard.cjs");
107
- const dst = ".claude/hooks/bkit-gateguard.cjs";
103
+ // driver from first install onward (env vars BKIT_GATEGUARD / BKIT_ALLOW_CONFIG_EDIT /
104
+ // BKIT_READGUARD still tune behaviour).
105
+ for (const hook of ["bkit-gateguard.cjs", "bkit-readguard.cjs"]) {
106
+ const src = path.join(claudeHooks, hook);
107
+ const dst = `.claude/hooks/${hook}`;
108
108
  if (fs.existsSync(src)) {
109
109
  const prevLen = ws.writes.length;
110
110
  writeTier2(src, dst, tokens, "slash-comment", dryRun, ws);
@@ -89,8 +89,8 @@ export function runCloudModule(ctx) {
89
89
  "IN CLAUDE APP (claude.ai/code → environment selector → + Add environment):\n" +
90
90
  " - Name: the repo name (e.g. `acme-web`) — one environment per repo, since secrets are per-repo.\n" +
91
91
  " - Setup script: paste from bkit's `cloud.md` § Setup script (installs vale + gh + corepack-pinned pnpm — exact versions live in cloud.md, not duplicated here).\n" +
92
- " - Environment variables: `BKIT_GH_TOKEN` (fine-grained for one owner, classic across owners — GitHub MCP), `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70`.\n" +
93
- " - Tracker env vars (GitHub): No tracker PAT needed. Run `gh auth login` once for CLI surface. MCP auth is browser OAuth (automatic on first tool call). Set `BKIT_GH_TOKEN` (fine-grained for one owner, classic across owners — GitHub MCP server).\n" +
92
+ " - Environment variables: `BKIT_GH_TOKEN` (fine-grained for one owner, classic across owners — GitHub MCP).\n" +
93
+ " - Tracker env vars (GitHub): `BKIT_GH_TOKEN` above is the only tracker credential — the GitHub MCP server sends it on every call, and the bootstrap hook signs `gh` in with it.\n" +
94
94
  " - Network access: `Trusted` (default). One environment per repo (secrets differ per repo); the setup script + variable *names* are identical across repos, only the values change. See cloud.md § Sharing across repos → Claude.",
95
95
  });
96
96
  }
@@ -155,10 +155,10 @@ export function runCodexModule(ctx) {
155
155
  console.log(`${logPrefix} ${tag}codex: ${jsonDst}`);
156
156
  }
157
157
  }
158
- // --- bkit-gateguard.cjs — Tier-2 markered-text, twin of the Claude hook ---
159
- {
160
- const hookSrc = path.join(codexHooks, "bkit-gateguard.cjs");
161
- const hookDst = ".codex/hooks/bkit-gateguard.cjs";
158
+ // --- bkit-gateguard.cjs / bkit-readguard.cjs — Tier-2 markered-text, twins of the Claude hooks ---
159
+ for (const hook of ["bkit-gateguard.cjs", "bkit-readguard.cjs"]) {
160
+ const hookSrc = path.join(codexHooks, hook);
161
+ const hookDst = `.codex/hooks/${hook}`;
162
162
  if (fs.existsSync(hookSrc)) {
163
163
  if (!dryRun)
164
164
  ensureDir(path.dirname(hookDst));
@@ -189,7 +189,7 @@ export function runCodexModule(ctx) {
189
189
  severity: "advisory",
190
190
  detect: "codex host installed (.codex/agents + .agents/skills/bkit-*).",
191
191
  action: "Three things that differ from the other hosts:\n" +
192
- "1. TRUST THE LAYER. Codex loads project-local hooks only once the `.codex/` layer is trusted. Until then GateGuard is installed and never fires.\n" +
192
+ "1. TRUST THE LAYER. Codex loads project-local hooks only once the `.codex/` layer is trusted. Until then GateGuard and ReadGuard are installed and never fire.\n" +
193
193
  "2. Workflows are SKILLS here, not slash commands: invoke `$bkit-design`, not `/bkit-design`.\n" +
194
194
  "3. Per-agent `tools:` is NOT enforced. Codex has no tool allowlist, so every agent gets the full built-in tool set. See .bkit/providers.md.",
195
195
  });
@@ -8,7 +8,7 @@ import { readBkitVersion, writeBkitVersion, hashFile, mergeCanonicalHashes, } fr
8
8
  import { listFilesRecursive, syncTemplateCopies } from "../template-copies.js";
9
9
  import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
10
10
  import { getPkgRoot, getCoreRoot, getSharedRoot, getBkitDocsRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
11
- import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES } from "../manifest.js";
11
+ import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
12
12
  export function listMdFiles(dir, prefix) {
13
13
  if (!fs.existsSync(dir))
14
14
  return [];
@@ -173,9 +173,8 @@ function runCoreTemplates(dryRun, tokens, ws, logPrefix) {
173
173
  // them, so a consumer edit is replaced. Source of truth is the package's own
174
174
  // `.bkit/core/.bkit/<name>`. (`advisories.md` is a regenerated runtime artifact,
175
175
  // `wording.md` is repo-only tooling and `friction.md` is a consumer-owned seed —
176
- // none belongs here. `LICENSE.md` is the PolyForm notice that travels with every
177
- // file bkit writes: PolyForm's Notices section requires a passed-on copy to carry
178
- // the terms or their URL and the Required Notice line.)
176
+ // none belongs here. `LICENSE.md` is the MIT notice that travels with the files bkit
177
+ // writes: MIT requires the copyright and permission notice in every copy.)
179
178
  export const BKIT_CANONICAL_DOCS = [
180
179
  "cloud.md",
181
180
  "comparison.md",
@@ -350,6 +349,16 @@ export function detectGateAdvisories(cwd) {
350
349
  "\n\nOrder matters — each chains the one above it. Omit a level deliberately to keep it CI-only (E2E in the build loop costs a production build on every remediation attempt). `.bkit/templates.md` lists the tool scripts the gates chain.",
351
350
  });
352
351
  }
352
+ // /bkit-build records each task's red through this script; without it test-first is
353
+ // reported as not enforced. bkit cannot seed it: what runs one file is the stack's.
354
+ if (!(BKIT_TEST_FILE_SCRIPT in declared)) {
355
+ findings.push({
356
+ id: "test-file-script-missing",
357
+ severity: "advisory",
358
+ detect: `package.json does not declare \`${BKIT_TEST_FILE_SCRIPT}\`, so \`/bkit-build\` cannot check that each task's tests fail before its code is written.`,
359
+ action: `Add \`${BKIT_TEST_FILE_SCRIPT}\` to package.json: it runs the ONE test file bkit appends as its argument (repo-relative path) and writes a JUnit report to the path in \`$BKIT_TEST_REPORT\`. Vitest example:\n\n "${BKIT_TEST_FILE_SCRIPT}": "vitest run --reporter=default --reporter=junit --outputFile.junit=\\"$BKIT_TEST_REPORT\\""\n\nCall the runner directly, not through a task runner that caches results or runs dependent packages first. A monorepo routes the path to the package and config that own it.`,
360
+ });
361
+ }
353
362
  return findings;
354
363
  }
355
364
  /** One command that cannot fail: `true`, `:`, `exit 0`, or an `echo`. */
@@ -430,7 +439,7 @@ export function runCoreModule(ctx) {
430
439
  // installed package (browse-only, gitignored; no-op in dogfood). A real
431
440
  // directory or file at either path is never clobbered (advisory); a platform
432
441
  // refusal is an advisory, never a failure.
433
- const linkChanges = syncPayloadLinks(cwd, { dryRun, ws });
442
+ const linkChanges = syncPayloadLinks(cwd, { dryRun });
434
443
  for (const rel of linkChanges.created) {
435
444
  console.log(`${logPrefix} ${tag}payload link: ${rel}`);
436
445
  }
@@ -117,12 +117,12 @@ export function runCursorModule(ctx) {
117
117
  }
118
118
  }
119
119
  }
120
- // markered-text (slash-comment) — GateGuard advisory PreToolUse hook for Cursor.
121
- // Same managed block as the Claude twin; the driver outside it adapts Cursor's
122
- // payload (relative file_path, no subagent marker) and emits Cursor's shape.
123
- {
124
- const src = path.join(cursorHooks, "bkit-gateguard.cjs");
125
- const dst = ".cursor/hooks/bkit-gateguard.cjs";
120
+ // markered-text (slash-comment) — GateGuard and ReadGuard advisory hooks for Cursor.
121
+ // Same managed blocks as the Claude twins; the drivers outside them adapt Cursor's
122
+ // payload (relative file_path, no subagent marker) and emit Cursor's shape.
123
+ for (const hook of ["bkit-gateguard.cjs", "bkit-readguard.cjs"]) {
124
+ const src = path.join(cursorHooks, hook);
125
+ const dst = `.cursor/hooks/${hook}`;
126
126
  if (fs.existsSync(src)) {
127
127
  const prevLen = ws.writes.length;
128
128
  writeTier2(src, dst, tokens, "slash-comment", dryRun, ws);
@@ -470,11 +470,11 @@ export function runOpencodeModule(ctx) {
470
470
  }
471
471
  }
472
472
  }
473
- // --- bkit-gateguard.js — Tier-2 markered-text (slash-comment); see install/manifest.ts ---
474
- {
473
+ // --- bkit-gateguard.js / bkit-readguard.js — Tier-2 markered-text (slash-comment); see install/manifest.ts ---
474
+ for (const plugin of ["bkit-gateguard.js", "bkit-readguard.js"]) {
475
475
  const opencodeCore = path.join(getCoreRoot(), ".opencode", "plugin");
476
- const pluginSrc = path.join(opencodeCore, "bkit-gateguard.js");
477
- const pluginDst = ".opencode/plugin/bkit-gateguard.js";
476
+ const pluginSrc = path.join(opencodeCore, plugin);
477
+ const pluginDst = `.opencode/plugin/${plugin}`;
478
478
  if (fs.existsSync(pluginSrc)) {
479
479
  // dryRun-gated — writeTier2 honours dryRun, so the dir is only needed for a real
480
480
  // write; `bkit check` stays read-only when gateguard's parent dir is absent.
@@ -36,10 +36,11 @@ export function createPayloadLink(targetAbs, linkAbs, symlinkFn = fs.symlinkSync
36
36
  // Create or refresh the consumer's `.bkit/core` + `.bkit/shared` view links into
37
37
  // the package payload. Idempotent: a correct link is kept, a dangling or
38
38
  // mis-pointed symlink is re-pointed, a real directory or file is NEVER clobbered
39
- // (skippedRealDir) and a platform refusal is only recorded (failed). Every create
40
- // or repair pushes a ws write in dry-run and live alike, so `bkit check` flags a
41
- // missing or broken link as drift. No-op in dogfood: there `.bkit/core` IS the
42
- // package source, never a view onto it.
39
+ // (skippedRealDir) and a platform refusal is only recorded (failed). Links are
40
+ // convenience views, not managed content: they never join the install WriteSet, so
41
+ // a missing or broken link is never `bkit check` drift (a fresh clone or worktree
42
+ // has none). Dry-run reports what a live run would do and touches nothing. No-op
43
+ // in dogfood: there `.bkit/core` IS the package source, never a view onto it.
43
44
  export function syncPayloadLinks(cwd, opts) {
44
45
  const changes = {
45
46
  created: [],
@@ -97,7 +98,6 @@ export function syncPayloadLinks(cwd, opts) {
97
98
  }
98
99
  }
99
100
  (st !== null ? changes.repaired : changes.created).push(relPath);
100
- opts.ws.writes.push({ path: relPath, action: "write" });
101
101
  }
102
102
  return changes;
103
103
  }
@@ -81,7 +81,7 @@ export function applyTokens(content, tokens) {
81
81
  const version = tokens.BKIT_VERSION ?? readInstallingBkitVersion();
82
82
  out = out
83
83
  .replace(/^\/\/ \{\{BKIT_MANAGED_MARKER\}\}/gm, () => managedVersionMarker(version, "slash"))
84
- .replace(/\{\{BKIT_MANAGED_MARKER\}\}/g, () => managedVersionMarker(version));
84
+ .replace(/\{\{BKIT_MANAGED_MARKER\}\}/g, () => managedVersionMarker(version, "html"));
85
85
  }
86
86
  return out;
87
87
  }
@@ -115,14 +115,23 @@ export function isConsumerModified(relPath, absolutePath, canonicalHashes) {
115
115
  * cases; the latter survive the absent-path prune because the adopted copy stays on
116
116
  * disk).
117
117
  *
118
+ * `removing` lists paths (or directories) a dry run would delete: they count as absent, so a
119
+ * dry run prunes the same entries the real run does.
120
+ *
118
121
  * `pruned` counts the dropped entries so callers can treat a prune-only merge as a
119
122
  * change that is still worth writing.
120
123
  */
121
- export function mergeCanonicalHashes(cwd, existing, fresh) {
124
+ export function mergeCanonicalHashes(cwd, existing, fresh, removing = []) {
122
125
  const canonicalHashes = {};
126
+ const isRemoving = (relPath) => removing.some((r) => {
127
+ const dir = r.replace(/[\\/]+$/, "");
128
+ return relPath === dir || relPath.startsWith(`${dir}/`);
129
+ });
123
130
  let pruned = 0;
124
131
  for (const [relPath, hash] of Object.entries(existing)) {
125
- if (!fs.existsSync(path.join(cwd, relPath)) || isTemplateSetPath(relPath)) {
132
+ if (!fs.existsSync(path.join(cwd, relPath)) ||
133
+ isRemoving(relPath) ||
134
+ isTemplateSetPath(relPath)) {
126
135
  pruned++;
127
136
  continue;
128
137
  }
@@ -161,7 +170,7 @@ export const MANAGED_MARKER_LINE_RE = /^(?:<!-- |# <!-- |\/\/ )bkit:managed v[^\
161
170
  export const MANAGED_MARKER_VERSION_RE = /bkit:managed v(\S+)/;
162
171
  /** Build the managed-version marker for a given version, in the given comment syntax. */
163
172
  export function managedVersionMarker(version, form = "html") {
164
- const text = `bkit:managed v${version} — PolyForm Noncommercial 1.0.0 / Small Business 1.0.0 (https://polyformproject.org/licenses/) — do not edit; run \`bkit upgrade\` to refresh`;
173
+ const text = `bkit:managed v${version} — do not edit; run \`bkit upgrade\` to refresh`;
165
174
  if (form === "slash")
166
175
  return `// ${text}`;
167
176
  return form === "hash" ? `# <!-- ${text} -->` : `<!-- ${text} -->`;
@@ -1,8 +1,9 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
- import { updateManagedBlock, extractFullManagedBlock, extractManagedBlock, findLineAnchoredMarkers, selectMarkers, } from "./managed-block.js";
3
+ import { updateManagedBlock, extractFullManagedBlock, extractManagedBlock, findLineAnchoredMarkers, findUnmarkedCopy, selectMarkers, } from "./managed-block.js";
4
4
  import { readTemplate } from "../render/parts.js";
5
5
  import { applyTokens } from "./placeholders.js";
6
+ import { sha256 } from "./version-file.js";
6
7
  export function deepContains(template, consumer, pathPrefix = "") {
7
8
  const missing = [];
8
9
  const mismatched = [];
@@ -141,7 +142,7 @@ export function deepMergeJson(base, override) {
141
142
  // - dest present, valid JSON, template contained → no-op (idempotent)
142
143
  // - dest present, valid JSON, containment fails → deepMergeJson(existing, template)
143
144
  // (template wins on key collisions; consumer-only keys outside template tree preserved)
144
- // - dest present, malformed JSON → overwrite with template
145
+ // - dest present, malformed JSON → throw; the consumer fixes it by hand
145
146
  // - schemaFlipped: true when a path value changed type during deep-merge
146
147
  // ---------------------------------------------------------------------------
147
148
  export function writeTier2JsonContained(srcPath, dstPath, dryRun, ws) {
@@ -225,12 +226,65 @@ export function writeTier1(srcPath, dstPath, tokens, dryRun, ws) {
225
226
  // - dest absent → write whole file (with token substitution)
226
227
  // - dest has markers → update only the bkit block (tokens applied to new block content)
227
228
  // - dest present, no marks → append full block at EOF; preserve consumer content above
229
+ // - no marks, markdown dest already holds an unmarked copy of the block (findUnmarkedCopy)
230
+ // → warn + skip; appending would leave a frozen duplicate above it
228
231
  //
229
232
  // markerStyle: "html-comment" for markdown, shell and `.gitignore` (`# ` prefix allowed);
230
233
  // "slash-comment" for JS.
231
234
  // ---------------------------------------------------------------------------
235
+ /**
236
+ * sha256 of the driver (everything outside the managed block) of hook files a bkit
237
+ * release shipped with a host contract the host does not accept, keyed by consumer path.
238
+ * Register: docs/migrations.md.
239
+ */
240
+ export const RETIRED_DRIVER_HASHES = {
241
+ // 5.1.0: Claude-shaped `hookSpecificOutput`; Antigravity reads `{ decision, reason }`.
242
+ ".agents/plugins/bkit/hooks/bkit-gateguard.cjs": [
243
+ "544dbcc2bab81875789563a2925bb5dc7b5dbbcf185f216fb3281cfa01ec030d",
244
+ ],
245
+ ".agents/plugins/bkit/hooks/bkit-guardrails.cjs": [
246
+ "8e5d75f7e1a4527889dafa6a250ae370e2acf1b5fc7d58929dfc759489746e14",
247
+ ],
248
+ };
249
+ /** The text outside a file's single managed block, or null without exactly one block. */
250
+ export function driverText(content, markerStyle) {
251
+ const [startMarker, endMarker] = selectMarkers(markerStyle);
252
+ const starts = findLineAnchoredMarkers(content, startMarker);
253
+ const ends = findLineAnchoredMarkers(content, endMarker);
254
+ if (starts.length !== 1 || ends.length !== 1 || ends[0] < starts[0])
255
+ return null;
256
+ return content.slice(0, starts[0]) + content.slice(ends[0]);
257
+ }
258
+ /**
259
+ * True when `dstPath` still carries a retired bkit driver the consumer never edited. An
260
+ * edited driver still on the retired output shape is kept and gets a printed fix.
261
+ */
262
+ function hasRetiredDriver(dstPath, content, markerStyle) {
263
+ const posix = dstPath.replace(/\\/g, "/");
264
+ const key = Object.keys(RETIRED_DRIVER_HASHES).find((rel) => posix === rel || posix.endsWith(`/${rel}`));
265
+ if (key === undefined)
266
+ return false;
267
+ const driver = driverText(content, markerStyle);
268
+ if (driver === null)
269
+ return false;
270
+ if (RETIRED_DRIVER_HASHES[key].includes(sha256(driver)))
271
+ return true;
272
+ if (driver.includes("hookSpecificOutput")) {
273
+ console.warn(`[bkit] ${dstPath}: your driver below \`// bkit:end\` writes Claude-shaped \`hookSpecificOutput\`, which Antigravity ignores — the hook never takes effect. Emit the managed block's result as Antigravity's \`{ "decision": "allow" | "deny" | "ask", "reason": "…" }\` (only a deny's reason reaches the model), or delete the file and re-run \`bkit install --antigravity\` to get bkit's driver.`);
274
+ }
275
+ return false;
276
+ }
232
277
  export function writeTier2(srcPath, dstPath, tokens, markerStyle, dryRun, ws) {
233
278
  const srcRaw = readTemplate(srcPath);
279
+ // A retired, unedited bkit driver is bkit's code, not the consumer's: replace the
280
+ // whole file so the new driver ships with the new block.
281
+ if (fs.existsSync(dstPath) &&
282
+ hasRetiredDriver(dstPath, fs.readFileSync(dstPath, "utf-8"), markerStyle)) {
283
+ if (!dryRun)
284
+ fs.writeFileSync(dstPath, applyTokens(srcRaw, tokens), "utf-8");
285
+ ws.writes.push({ path: dstPath, action: "write" });
286
+ return;
287
+ }
234
288
  if (!fs.existsSync(dstPath)) {
235
289
  // dest missing → write whole template (with tokens applied)
236
290
  const content = applyTokens(srcRaw, tokens);
@@ -264,6 +318,11 @@ export function writeTier2(srcPath, dstPath, tokens, markerStyle, dryRun, ws) {
264
318
  }
265
319
  // dest has no markers → append full block at EOF (with tokens applied)
266
320
  const appliedBlock = applyTokens(fullBlock, tokens);
321
+ const copyTitle = dstPath.endsWith(".md") ? findUnmarkedCopy(destContent, appliedBlock) : null;
322
+ if (copyTitle !== null) {
323
+ console.warn(`[bkit] ${dstPath} has no managed-block markers but already holds an older bkit copy (\`${copyTitle}\`) — skipping, so it is not duplicated. Delete the file and re-run install; then re-add any lines you wrote yourself below \`<!-- bkit:end -->\`.`);
324
+ return;
325
+ }
267
326
  const sep = destContent.length === 0
268
327
  ? ""
269
328
  : destContent.endsWith("\n\n")
@@ -39,16 +39,15 @@ export function getPkgRoot() {
39
39
  : path.resolve(engineDir, "..");
40
40
  }
41
41
  // ---------------------------------------------------------------------------
42
- // The three payload roots. Each folder carries one licence and one install
43
- // behaviour; a file's path inside its folder is where it lands in the consumer
44
- // repo.
42
+ // The three payload roots. Each folder carries one install behaviour; a file's
43
+ // path inside its folder is where it lands in the consumer repo.
45
44
  //
46
- // core/ PolyForm. Written and kept current. engine/, workflows/,
47
- // prompts/, .bkit/, hooks/ and every LICENSE.md are skipped
48
- // by install; the rest is copied at its folder-relative path.
49
- // shared/ MIT-0. Written and kept current: bkit's blocks and keys inside
45
+ // core/ Written and kept current. engine/, workflows/, prompts/,
46
+ // .bkit/ and hooks/ are skipped by install; the rest is copied
47
+ // at its folder-relative path.
48
+ // shared/ Written and kept current: bkit's blocks and keys inside
50
49
  // files the consumer also edits, plus small whole files.
51
- // templates/ MIT-0. Copy-and-own only: never applied to the repo, copied raw
50
+ // templates/ Copy-and-own only: never applied to the repo, copied raw
52
51
  // into the consumer's `.bkit/templates/` by syncTemplateCopies.
53
52
  // ---------------------------------------------------------------------------
54
53
  export function getCoreRoot() {
@@ -96,11 +95,9 @@ export function templateRelPath(dest) {
96
95
  /**
97
96
  * The absolute source path backing a consumer-relative dest, or `null` when no
98
97
  * payload root carries it. Checks `shared/` then `core/`, applying the dotfile
99
- * remap. Root-level `LICENSE.md` files are never install sources.
98
+ * remap.
100
99
  */
101
100
  export function findTemplateSource(relPath) {
102
- if (path.basename(relPath) === "LICENSE.md")
103
- return null;
104
101
  const rel = templateRelPath(relPath);
105
102
  for (const root of [getSharedRoot(), getCoreRoot()]) {
106
103
  const p = path.join(root, rel);