@cbartens/bkit 5.1.0 → 5.2.1

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 (193) 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 +92 -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 +10 -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/.prettierignore +1 -1
  136. package/.bkit/templates/context/bkit-expo.md +22 -13
  137. package/.bkit/templates/context/bkit-github.md +20 -6
  138. package/.bkit/templates/context/bkit-inngest.md +10 -4
  139. package/.bkit/templates/context/bkit-maestro.md +5 -5
  140. package/.bkit/templates/context/bkit-playwright.md +3 -3
  141. package/.bkit/templates/context/bkit-sentry.md +6 -5
  142. package/.bkit/templates/context/bkit-stripe.md +31 -8
  143. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  145. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  147. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  148. package/.bkit/templates/slop-scan.config.json +7 -2
  149. package/CHANGELOG.md +50 -0
  150. package/LICENSE.md +21 -161
  151. package/README.md +61 -28
  152. package/dist/checks/after/auth.js +28 -0
  153. package/dist/checks/after/github.js +4 -4
  154. package/dist/checks/after/index.js +29 -45
  155. package/dist/checks/after/managed.js +40 -1
  156. package/dist/checks/before/index.js +5 -4
  157. package/dist/checks/before/mcp.js +53 -53
  158. package/dist/checks/status-holes.js +1 -1
  159. package/dist/checks/tips/catalogue.js +297 -0
  160. package/dist/checks/tips/detect.js +130 -0
  161. package/dist/checks/tips/index.js +146 -0
  162. package/dist/cli.js +47 -9
  163. package/dist/commands/install/doctor.js +5 -1
  164. package/dist/commands/install/install.js +27 -7
  165. package/dist/commands/install/uninstall.js +31 -16
  166. package/dist/commands/install/upgrade.js +15 -32
  167. package/dist/commands/launch.js +27 -11
  168. package/dist/commands/tips.js +10 -0
  169. package/dist/commands/workflow/runs.js +52 -16
  170. package/dist/commands/workflow/runtime.js +8 -0
  171. package/dist/commands/workflow/steps.js +1 -0
  172. package/dist/commands/workflow/tests.js +541 -4
  173. package/dist/commands/workflow/workstreams.js +4 -4
  174. package/dist/install/cloud-env.js +3 -14
  175. package/dist/install/hosts.js +22 -0
  176. package/dist/install/managed-block.js +36 -0
  177. package/dist/install/manifest.js +45 -4
  178. package/dist/install/modules/antigravity.js +8 -7
  179. package/dist/install/modules/claude.js +6 -6
  180. package/dist/install/modules/cloud.js +2 -2
  181. package/dist/install/modules/codex.js +5 -5
  182. package/dist/install/modules/core.js +14 -5
  183. package/dist/install/modules/cursor.js +6 -6
  184. package/dist/install/modules/opencode.js +4 -4
  185. package/dist/install/payload-links.js +5 -5
  186. package/dist/install/placeholders.js +1 -1
  187. package/dist/install/version-file.js +12 -3
  188. package/dist/install/write.js +61 -2
  189. package/dist/shared/package-roots.js +8 -11
  190. package/package.json +4 -6
  191. package/.bkit/core/LICENSE.md +0 -149
  192. package/.bkit/shared/LICENSE.md +0 -22
  193. package/.bkit/templates/LICENSE.md +0 -22
@@ -0,0 +1,60 @@
1
+ #!/usr/bin/env node
2
+ // bkit-readguard.cjs — bkit ReadGuard advisory hook (Claude Code).
3
+ //
4
+ // Fires before Read and Bash. When an agent reads a line range of a file it already
5
+ // read in this conversation, and the file has not changed since (same mtime and size),
6
+ // it injects a note so the agent uses the earlier output instead of paying for the
7
+ // same lines again. Shell reads are recognised in their plain forms only: `cat FILE`,
8
+ // `sed -n 'A,Bp' FILE`, `head` / `tail` with a line count. Pipes, globs, lists and
9
+ // substitutions are not tracked. On PreCompact it forgets the session's reads: the
10
+ // summary drops the earlier output, so re-reading is right again.
11
+ //
12
+ // CONTRACT — do not regress:
13
+ // - ADVISORY ONLY: emits `additionalContext`, never blocks.
14
+ // - FAIL OPEN: a single top-level catch swallows every error (exit 0, nothing emitted).
15
+ // - PER AGENT: the log is keyed by (session_id, agent_id). A subagent shares its
16
+ // parent's session_id and has its own agent_id, so it never inherits the parent's
17
+ // reads.
18
+ // - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
19
+ //
20
+ // MODES (BKIT_READGUARD env var): unset → advisory [DEFAULT] | "off" → no-op.
21
+ //
22
+ // Host note: one engine, five hosts. bkit generates this hook at install from bkit's
23
+ // `core/hooks/readguard-engine.js` and `readguard-payload.js`. See .bkit/providers.md
24
+ // § ReadGuard.
25
+ //
26
+ // OWNERSHIP: everything between the markers below is bkit-managed and is
27
+ // overwritten on every `bkit install` / `bkit upgrade`. It is a pure advisory
28
+ // engine only — no stdin read, no stdout write, no top-level invocation. Add your
29
+ // own logic in the driver that follows the managed block: call
30
+ // `bkitReadguard(payload)`, fold in your own checks, and call `emit()` once.
31
+
32
+ "use strict";
33
+
34
+ // bkit:start
35
+
36
+ // {{BKIT_MANAGED_MARKER}}
37
+
38
+ const fs = require("node:fs");
39
+ const os = require("node:os");
40
+ const path = require("node:path");
41
+
42
+ // {{BKIT_PART readguard-engine.js}}
43
+
44
+ // {{BKIT_PART readguard-payload.js}}
45
+
46
+ // bkit:end
47
+
48
+ function emit(payload) {
49
+ process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
50
+ }
51
+
52
+ try {
53
+ const raw = fs.readFileSync(0, "utf-8");
54
+ if (raw.trim()) {
55
+ const context = bkitReadguard(JSON.parse(raw));
56
+ if (context) emit({ hookEventName: "PreToolUse", additionalContext: context });
57
+ }
58
+ } catch {
59
+ process.exitCode = 0; // fail open — never block, never error out
60
+ }
@@ -21,7 +21,8 @@
21
21
  // - ADVISORY BY DEFAULT: emits `additionalContext` only, never blocks. BKIT_GATEGUARD=deny
22
22
  // flips it to a deny ramp; that is a config change, NOT a code change.
23
23
  // - FAIL OPEN: one top-level catch swallows every error and exits 0.
24
- // - SUBAGENTS INCLUDED: a subagent edit is an edit; each carries its own session id.
24
+ // - SUBAGENTS INCLUDED: a subagent edit is an edit. Codex reports the parent's
25
+ // session_id inside a subagent and no agent id, so dedup cannot separate them.
25
26
  // - DEDUP: warns once per (session, file), state in the OS temp dir, GC'd after 24h.
26
27
  //
27
28
  // MODES (BKIT_GATEGUARD): unset → advisory [DEFAULT] | "off" → no-op | "deny" → block first
@@ -49,13 +50,14 @@ const EDIT_TOOLS = new Set(["apply_patch", "Edit", "Write"]);
49
50
  // Codex does NOT send a file path: `apply_patch` puts a V4A patch envelope in
50
51
  // `tool_input.command`. Pull the touched paths out of it. Grammar (codex-rs/apply-patch):
51
52
  // *** Add File: <path> | *** Update File: <path> | *** Delete File: <path>
53
+ // (an Update may be followed by *** Move to: <path>, a target too)
52
54
  // Paths are always repo-relative, so they are resolved against the payload cwd.
53
55
  // Returns [{ file, isNew }] in patch order; [] when nothing parses.
54
56
  function parseApplyPatchTargets(command, cwd) {
55
57
  if (typeof command !== "string") return [];
56
58
  const out = [];
57
59
  for (const line of command.split("\n")) {
58
- const m = /^\*\*\* (Add|Update|Delete) File: (.+?)\s*$/.exec(line);
60
+ const m = /^\*\*\* (?:(Add|Update|Delete) File|Move to): (.+?)\s*$/.exec(line);
59
61
  if (!m) continue;
60
62
  const rel = m[2];
61
63
  out.push({ file: cwd ? path.resolve(cwd, rel) : rel, isNew: m[1] === "Add" });
@@ -67,16 +69,16 @@ function parseApplyPatchTargets(command, cwd) {
67
69
 
68
70
  // Pure: takes the already-parsed hook payload, returns the advisory to emit or
69
71
  // null. Never touches process.stdin / process.stdout — the driver below owns both.
70
- // Subagents are NOT exempt: dedup is per (session, file) and a subagent carries its
71
- // own session id, so it gets the checklist once for a file the orchestrator already
72
- // touched.
72
+ // Subagents are NOT exempt: dedup is per (session, agent, file). Codex tool payloads
73
+ // carry the parent's session_id inside a subagent and no agent id, so a Codex subagent
74
+ // is not told apart from its parent.
73
75
  function bkitGateguard(payload) {
74
76
  if (process.env.BKIT_GATEGUARD === "off") return null;
75
77
  if (!EDIT_TOOLS.has(payload.tool_name)) return null;
76
78
 
77
79
  const input = payload.tool_input || {};
78
80
  const cwd = typeof payload.cwd === "string" ? payload.cwd : "";
79
- const sessionId = typeof payload.session_id === "string" ? payload.session_id : "no-session";
81
+ const sessionId = dedupKey(payload.session_id, payload.agent_id);
80
82
  // One patch can touch several files. Advises on the first not-yet-warned target, so a
81
83
  // new file after an already-warned one still gets its advisory.
82
84
  const target = parseApplyPatchTargets(input.command, cwd).find(
@@ -0,0 +1,58 @@
1
+ #!/usr/bin/env node
2
+ // bkit-readguard.cjs — bkit ReadGuard advisory hook (Codex CLI).
3
+ //
4
+ // Twin of `.claude/hooks/bkit-readguard.cjs`, same stdin envelope and stdout shape.
5
+ // Codex has no file-read tool, so every read arrives as a shell command (`Bash`, argv
6
+ // `["bash", "-lc", "<cmd>"]` unwrapped). When an agent re-reads a line range of a file
7
+ // it already read in this conversation, and the file has not changed since, it injects
8
+ // a note so the agent uses the earlier output. Plain forms only: `cat FILE`,
9
+ // `sed -n 'A,Bp' FILE`, `head` / `tail` with a line count. On PreCompact it forgets the
10
+ // session's reads.
11
+ //
12
+ // REGISTRATION: `.codex/hooks.json`, PreToolUse matcher `Bash` plus PreCompact. Codex
13
+ // loads project-local hooks only once the project `.codex/` layer is TRUSTED.
14
+ // See .bkit/providers.md § ReadGuard.
15
+ //
16
+ // CONTRACT — do not regress:
17
+ // - ADVISORY ONLY: emits `additionalContext`, never blocks.
18
+ // - FAIL OPEN: one top-level catch swallows every error and exits 0.
19
+ // - PER AGENT: keyed by (session_id, agent_id when present). Codex tool payloads
20
+ // carry the parent's session_id inside subagents and no agent id, so a subagent can
21
+ // see the parent's reads; the note tells the agent to re-read when the earlier
22
+ // output is not in its context.
23
+ // - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
24
+ //
25
+ // MODES (BKIT_READGUARD): unset → advisory [DEFAULT] | "off" → no-op.
26
+ //
27
+ // OWNERSHIP: everything between the markers is bkit-managed and overwritten on every
28
+ // `bkit install` / `bkit upgrade`. Add your own logic in the driver below the block.
29
+
30
+ "use strict";
31
+
32
+ // bkit:start
33
+
34
+ // {{BKIT_MANAGED_MARKER}}
35
+
36
+ const fs = require("node:fs");
37
+ const os = require("node:os");
38
+ const path = require("node:path");
39
+
40
+ // {{BKIT_PART readguard-engine.js}}
41
+
42
+ // {{BKIT_PART readguard-payload.js}}
43
+
44
+ // bkit:end
45
+
46
+ function emit(payload) {
47
+ process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
48
+ }
49
+
50
+ try {
51
+ const raw = fs.readFileSync(0, "utf-8");
52
+ if (raw.trim()) {
53
+ const context = bkitReadguard(JSON.parse(raw));
54
+ if (context) emit({ hookEventName: "PreToolUse", additionalContext: context });
55
+ }
56
+ } catch {
57
+ process.exitCode = 0; // fail open — never block, never error out
58
+ }
@@ -11,8 +11,8 @@
11
11
  // Fail-open: a single top-level catch allows on unexpected errors (same shape as gateguard).
12
12
  //
13
13
  // bkit generates the managed block at install: the shell detection and the deny / ask
14
- // tiers are shared with the Claude and Codex hooks (bkit's `core/hooks/`); the output
15
- // shape and the read gate below are Cursor's own.
14
+ // tiers are shared with the Claude and Codex hooks, the read tiers with the Antigravity
15
+ // hook (bkit's `core/hooks/`); the output shape is Cursor's own.
16
16
  //
17
17
  // OWNERSHIP: everything between the markers below is bkit-managed and is
18
18
  // overwritten on every `bkit install` / `bkit upgrade`. It is a pure decision
@@ -33,6 +33,8 @@ const path = require("node:path");
33
33
 
34
34
  // {{BKIT_PART guardrails-tiers.js}}
35
35
 
36
+ // {{BKIT_PART guardrails-read.js}}
37
+
36
38
  function allow() {
37
39
  return { permission: "allow" };
38
40
  }
@@ -80,27 +82,18 @@ function decideShell(cmd) {
80
82
 
81
83
  /** @param {string} filePath */
82
84
  function decideRead(filePath) {
83
- const p = filePath.replace(/\\/g, "/");
84
- if (!p) return allow();
85
-
86
- // Deny private-key material
87
- if (/\.pem$/i.test(p) || /\.p12$/i.test(p) || /(^|\/)id_rsa$/i.test(p)) {
85
+ const v = classifyRead(filePath);
86
+ if (!v) return allow();
87
+ if (v.tier === "deny") {
88
88
  return deny(
89
89
  "Blocked: reading private-key material is denied by bkit Cursor guardrails.",
90
- `Do not read ${p}. Ask the user to supply needed material out-of-band.`,
90
+ `Do not read ${v.path}. Ask the user to supply needed material out-of-band.`,
91
91
  );
92
92
  }
93
-
94
- // Ask on .env (allow .env.example)
95
- const base = p.split("/").pop() || p;
96
- if (base === ".env" || (/^\.env\./.test(base) && base !== ".env.example")) {
97
- return ask(
98
- "bkit Cursor guardrails: confirm reading an env/secrets file.",
99
- `Reading ${p} may expose secrets. Prefer direnv / documented non-secret examples.`,
100
- );
101
- }
102
-
103
- return allow();
93
+ return ask(
94
+ "bkit Cursor guardrails: confirm reading an env/secrets file.",
95
+ `Reading ${v.path} may expose secrets. Prefer direnv / documented non-secret examples.`,
96
+ );
104
97
  }
105
98
 
106
99
  /**
@@ -0,0 +1,59 @@
1
+ #!/usr/bin/env node
2
+ // bkit-readguard.cjs — bkit ReadGuard advisory hook for Cursor.
3
+ //
4
+ // Fires on preToolUse for `Read` and `Shell`. When an agent re-reads a line range of a
5
+ // file it already read in this conversation, and the file has not changed since (same
6
+ // mtime and size), it adds a note so the agent uses the earlier output instead. Shell
7
+ // reads are recognised in their plain forms only: `cat FILE`, `sed -n 'A,Bp' FILE`,
8
+ // `head` / `tail` with a line count. On preCompact it forgets the conversation's reads.
9
+ //
10
+ // CONTRACT — do not regress:
11
+ // - ADVISORY ONLY: returns `permission: "allow"` with `additional_context` (the same
12
+ // channel GateGuard uses on Cursor), never denies.
13
+ // - FAIL OPEN: top-level try/catch emits a bare allow on any error.
14
+ // - PER CONVERSATION: keyed by `conversation_id`; Cursor's tool payload carries no
15
+ // subagent marker. The note tells the agent to re-read when the earlier output is
16
+ // not in its context.
17
+ // - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
18
+ //
19
+ // MODES (BKIT_READGUARD env var): unset → advisory [DEFAULT] | "off" → no-op.
20
+ //
21
+ // Wired from `.cursor/hooks.json` → preToolUse (matcher "Read|Shell") and preCompact,
22
+ // without failClosed. bkit generates the managed block from the same shared parts as
23
+ // `.claude/hooks/bkit-readguard.cjs`, so the two are byte-identical between the markers.
24
+ // See .bkit/providers.md § ReadGuard.
25
+ //
26
+ // OWNERSHIP: everything between the markers below is bkit-managed and is
27
+ // overwritten on every `bkit install` / `bkit upgrade`. Add your own logic in the
28
+ // driver that follows the managed block, and emit EXACTLY ONE JSON document.
29
+
30
+ "use strict";
31
+
32
+ // bkit:start
33
+
34
+ // {{BKIT_MANAGED_MARKER}}
35
+
36
+ const fs = require("node:fs");
37
+ const os = require("node:os");
38
+ const path = require("node:path");
39
+
40
+ // {{BKIT_PART readguard-engine.js}}
41
+
42
+ // {{BKIT_PART readguard-payload.js}}
43
+
44
+ // bkit:end
45
+
46
+ function emit(decision) {
47
+ process.stdout.write(JSON.stringify(decision));
48
+ }
49
+
50
+ try {
51
+ const raw = fs.readFileSync(0, "utf-8");
52
+ const payload = raw.trim() ? JSON.parse(raw) : {};
53
+ const context = bkitReadguard(payload);
54
+ if (payload.hook_event_name === "preCompact") emit({});
55
+ else emit(context ? { permission: "allow", additional_context: context } : { permission: "allow" });
56
+ } catch {
57
+ // Fail open — any error emits a bare allow.
58
+ emit({ permission: "allow" });
59
+ }
@@ -30,8 +30,10 @@
30
30
  //
31
31
  // BKIT_ALLOW_CONFIG_EDIT=1 → suppress the gate-config advisory (sanctioned edit).
32
32
  //
33
- // opencode tool names: the edit surface is `write`, `edit` and `patch`. The terminal
34
- // tool (`shell` in v2, `bash` before v2) is NOT guarded.
33
+ // opencode tool names: the edit surface is `write`, `edit` and `patch` (`apply_patch`
34
+ // on 1.x model-specific tool sets). `patch` carries a multi-file patch in `patchText`,
35
+ // so one call can touch several files. The terminal tool (`shell` in v2, `bash` before
36
+ // v2) is NOT guarded.
35
37
  //
36
38
  // The engine inside the managed block is generated at install from bkit's
37
39
  // `core/hooks/gateguard-engine.js`, the same source as the Claude, Cursor and Codex hooks.
@@ -52,19 +54,21 @@ import * as path from "node:path";
52
54
 
53
55
  // opencode edit-like tool names, lowercase in opencode's plugin API.
54
56
  // The terminal tool (`shell` in v2, `bash` before v2) is NOT in this list.
55
- const EDIT_TOOLS = new Set(["write", "edit", "patch"]);
57
+ const EDIT_TOOLS = new Set(["write", "edit", "patch", "apply_patch"]);
56
58
 
57
59
  // {{BKIT_PART gateguard-engine.js}}
58
60
 
59
- // Pure: takes the tool name, the already-extracted file path, and the session id;
61
+ // Pure: takes the tool name, the already-extracted file path, and the session id
62
+ // (plus an optional new-file override for patch `*** Add File:` targets);
60
63
  // returns the advisory to emit or null. Never touches opencode's client, stderr,
61
64
  // or the throw path — the driver below owns all three, so it can fold in its own
62
65
  // checks without bkit's block needing to change.
63
- function bkitGateguard(toolName, filePath, sessionId) {
66
+ function bkitGateguard(toolName, filePath, sessionId, isNewOverride) {
64
67
  if (!EDIT_TOOLS.has(toolName)) return null;
65
68
  // A write to a not-yet-existing path is a NEW file and gets the reuse checklist.
66
69
  const isNewFile =
67
- toolName === "write" && typeof filePath === "string" && !fs.existsSync(filePath);
70
+ isNewOverride ??
71
+ (toolName === "write" && typeof filePath === "string" && !fs.existsSync(filePath));
68
72
  return firstTouchAdvice(filePath, sessionId, isNewFile);
69
73
  }
70
74
 
@@ -92,6 +96,8 @@ function bkitGateguard(toolName, filePath, sessionId) {
92
96
  // plugin, or hand-port this driver to the function shape.
93
97
  // ---------------------------------------------------------------------------
94
98
 
99
+ const PATCH_TOOLS = new Set(["patch", "apply_patch"]);
100
+
95
101
  /** Edit-tool args → the target file path, across 1.x and 2.0 argument keys. */
96
102
  function gateGuardFilePath(input) {
97
103
  return input && typeof input === "object"
@@ -99,6 +105,30 @@ function gateGuardFilePath(input) {
99
105
  : undefined;
100
106
  }
101
107
 
108
+ // `patch` takes one `patchText` argument: a multi-file envelope of
109
+ // *** Add File: <path> | *** Update File: <path> (optional *** Move to: <path>) | *** Delete File: <path>
110
+ // Returns [{ file, isNew }] in patch order; [] for a missing, non-string or unparseable patch.
111
+ function parsePatchTargets(patchText) {
112
+ if (typeof patchText !== "string") return [];
113
+ const out = [];
114
+ for (const line of patchText.split("\n")) {
115
+ const m = /^\*\*\* (Add File|Update File|Delete File|Move to):\s*(.+?)\s*$/.exec(line);
116
+ if (m) out.push({ file: m[2], isNew: m[1] === "Add File" });
117
+ }
118
+ return out;
119
+ }
120
+
121
+ /** Every file one edit-tool call touches: all patch targets, or the single path. */
122
+ function gateGuardTargets(tool, input) {
123
+ if (PATCH_TOOLS.has(tool)) {
124
+ const patchText =
125
+ input && typeof input === "object" ? (input.patchText ?? input.patch_text) : undefined;
126
+ return parsePatchTargets(patchText);
127
+ }
128
+ const file = gateGuardFilePath(input);
129
+ return typeof file === "string" ? [{ file, isNew: undefined }] : [];
130
+ }
131
+
102
132
  /** True only for this plugin's deny-mode throw, so fail-open swallows nothing else. */
103
133
  function isDenyThrow(err) {
104
134
  return (
@@ -130,24 +160,35 @@ function takeNewFile(callID) {
130
160
  * DENY MODE (execute.before — the only hook that can block). First touch of a file
131
161
  * per session throws the checklist as the reason; the dedup lets the retry through.
132
162
  * The before hook sees the file before a write creates it, so existence is accurate.
163
+ * A multi-file patch checks every target (each is marked warned) and throws once with
164
+ * all their checklists, so the retry is not blocked again file by file.
133
165
  */
134
- function denyFirstTouch(tool, filePath, sessionID) {
166
+ function denyFirstTouch(tool, targets, sessionID) {
135
167
  if (process.env.BKIT_GATEGUARD !== "deny") return;
136
- const result = bkitGateguard(tool, filePath, sessionID);
137
- if (result && result.mode === "deny") throw new Error(result.context);
168
+ const contexts = [];
169
+ for (const { file, isNew } of targets) {
170
+ const result = bkitGateguard(tool, file, sessionID, isNew);
171
+ if (result && result.mode === "deny") contexts.push(result.context);
172
+ }
173
+ if (contexts.length > 0) throw new Error(contexts.join("\n\n"));
138
174
  }
139
175
 
140
176
  /**
141
177
  * ADVISORY MODE (execute.after). Returns the checklist to append to the tool result,
142
- * or null when off / deny / already warned / no advice for this path. `isNewFile` is
143
- * the pre-write snapshot (see NEW_FILE_BY_CALL), not the post-write filesystem.
178
+ * or null when off / deny / already warned / no advice for any target. `isNewFile` is
179
+ * the pre-write snapshot (see NEW_FILE_BY_CALL), not the post-write filesystem; a patch
180
+ * target carries its own new-file flag from its `*** Add File:` header.
144
181
  */
145
- function advisoryFor(tool, filePath, sessionID, isNewFile) {
182
+ function advisoryFor(tool, targets, sessionID, isNewFile) {
146
183
  const mode = process.env.BKIT_GATEGUARD;
147
184
  if (mode === "off" || mode === "deny") return null;
148
185
  if (!EDIT_TOOLS.has(tool)) return null;
149
- const result = firstTouchAdvice(filePath, sessionID, isNewFile);
150
- return result ? result.context : null;
186
+ const contexts = [];
187
+ for (const target of targets) {
188
+ const result = firstTouchAdvice(target.file, sessionID, target.isNew ?? isNewFile);
189
+ if (result) contexts.push(result.context);
190
+ }
191
+ return contexts.length > 0 ? contexts.join("\n\n") : null;
151
192
  }
152
193
 
153
194
  /** OpenCode 1.x before hook: `(input, output)`, tool args on `output.args`. */
@@ -155,9 +196,9 @@ async function bkitGateGuardBeforeV1(hookInput, output) {
155
196
  try {
156
197
  const { tool, sessionID, callID } = hookInput ?? {};
157
198
  if (!EDIT_TOOLS.has(tool)) return;
158
- const filePath = gateGuardFilePath(output?.args);
159
- snapshotNewFile(callID, tool, filePath);
160
- denyFirstTouch(tool, filePath, sessionID);
199
+ const targets = gateGuardTargets(tool, output?.args);
200
+ snapshotNewFile(callID, tool, targets[0]?.file);
201
+ denyFirstTouch(tool, targets, sessionID);
161
202
  } catch (err) {
162
203
  if (isDenyThrow(err)) throw err;
163
204
  }
@@ -170,7 +211,12 @@ async function bkitGateGuardAfterV1(hookInput, output) {
170
211
  const isNewFile = takeNewFile(callID);
171
212
  if (!EDIT_TOOLS.has(tool)) return;
172
213
  if (!output || typeof output !== "object") return;
173
- const context = advisoryFor(tool, gateGuardFilePath(args ?? output.args), sessionID, isNewFile);
214
+ const context = advisoryFor(
215
+ tool,
216
+ gateGuardTargets(tool, args ?? output.args),
217
+ sessionID,
218
+ isNewFile,
219
+ );
174
220
  if (!context) return;
175
221
  const existing = typeof output.output === "string" ? output.output : "";
176
222
  output.output = existing.length > 0 ? `${existing}\n\n${context}` : context;
@@ -184,9 +230,9 @@ async function bkitGateGuardBeforeV2(event) {
184
230
  try {
185
231
  const tool = event?.tool;
186
232
  if (!EDIT_TOOLS.has(tool)) return;
187
- const filePath = gateGuardFilePath(event?.input);
188
- snapshotNewFile(event?.id, tool, filePath);
189
- denyFirstTouch(tool, filePath, event?.sessionID);
233
+ const targets = gateGuardTargets(tool, event?.input);
234
+ snapshotNewFile(event?.id, tool, targets[0]?.file);
235
+ denyFirstTouch(tool, targets, event?.sessionID);
190
236
  } catch (err) {
191
237
  if (isDenyThrow(err)) throw err;
192
238
  }
@@ -199,7 +245,12 @@ async function bkitGateGuardAfterV2(event) {
199
245
  const isNewFile = takeNewFile(event?.id);
200
246
  if (!EDIT_TOOLS.has(tool)) return;
201
247
  if (event?.status !== "completed" || !event.result) return;
202
- const context = advisoryFor(tool, gateGuardFilePath(event?.input), event?.sessionID, isNewFile);
248
+ const context = advisoryFor(
249
+ tool,
250
+ gateGuardTargets(tool, event?.input),
251
+ event?.sessionID,
252
+ isNewFile,
253
+ );
203
254
  if (!context) return;
204
255
  const content = Array.isArray(event.result.content) ? event.result.content : [];
205
256
  event.result.content = [...content, { type: "text", text: context }];
@@ -0,0 +1,126 @@
1
+ // bkit-readguard.js — bkit ReadGuard plugin for opencode.
2
+ //
3
+ // When an agent re-reads a line range of a file it already read in this session, and
4
+ // the file has not changed since (same mtime and size), it appends a note to the tool
5
+ // result so the next read uses the earlier output instead. Covers the `read` tool and
6
+ // plain shell reads (`cat FILE`, `sed -n 'A,Bp' FILE`, `head` / `tail` with a line
7
+ // count) through the terminal tool (`shell` in v2, `bash` before v2).
8
+ //
9
+ // CONTRACT — do not regress:
10
+ // - ADVISORY ONLY: appends the note to the tool RESULT in the after-execute hook.
11
+ // The before-execute hook can only allow or block, so ReadGuard does not use it;
12
+ // the note arrives with the repeated read, not before it.
13
+ // - FAIL OPEN: every hook swallows its own errors.
14
+ // - PER SESSION: keyed by sessionID. A subagent runs in its own session, so it never
15
+ // inherits its parent's reads.
16
+ // - COMPACTION: 1.x forgets a session's reads on `session.compacted`. 2.0 exposes no
17
+ // event subscription to this plugin, so its log is not cleared on a summary; the
18
+ // note tells the agent to re-read when the earlier output is no longer in context.
19
+ // - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
20
+ //
21
+ // MODES (BKIT_READGUARD env var): unset → advisory [DEFAULT] | "off" → no-op.
22
+ //
23
+ // The engine inside the managed block is generated at install from bkit's
24
+ // `core/hooks/readguard-engine.js`, the same source as the Claude, Cursor, Codex and
25
+ // Antigravity hooks. See .bkit/providers.md § ReadGuard.
26
+ //
27
+ // OWNERSHIP: everything between the markers below is bkit-managed and is
28
+ // overwritten on every `bkit install` / `bkit upgrade`. It is a pure advisory
29
+ // engine only — no client calls, no stderr write, no throw — so it composes
30
+ // with your own checks in the exported plugin that follows the managed block.
31
+
32
+ // bkit:start
33
+
34
+ // {{BKIT_MANAGED_MARKER}}
35
+
36
+ import * as fs from "node:fs";
37
+ import * as os from "node:os";
38
+ import * as path from "node:path";
39
+
40
+ // opencode tool names, lowercase in opencode's plugin API.
41
+ const READ_TOOLS = new Set(["read"]);
42
+ const SHELL_TOOLS = new Set(["shell", "bash"]);
43
+
44
+ // {{BKIT_PART readguard-engine.js}}
45
+
46
+ // Pure: takes the tool name, its arguments and the session id; returns the note to
47
+ // append or null. `read` takes `path` (2.0) or `filePath` (1.x); 1-based `offset` plus
48
+ // `limit`, the whole file when neither is given. The terminal tool takes `command` and
49
+ // an optional `workdir`.
50
+ function bkitReadguard(tool, args, sessionID) {
51
+ const input = args && typeof args === "object" ? args : {};
52
+ const cwd = typeof input.workdir === "string" ? input.workdir : process.cwd();
53
+ let targets = [];
54
+ if (READ_TOOLS.has(tool)) {
55
+ const paged = input.offset !== undefined || input.limit !== undefined;
56
+ targets = toolReadTarget(
57
+ input.path ?? input.filePath,
58
+ cwd,
59
+ input.offset,
60
+ input.limit,
61
+ paged ? undefined : OPEN_END,
62
+ );
63
+ } else if (SHELL_TOOLS.has(tool)) {
64
+ targets = shellReadTargets(typeof input.command === "string" ? input.command : "", cwd);
65
+ }
66
+ return repeatReadAdvice(targets, sessionID, undefined, cwd);
67
+ }
68
+
69
+ // bkit:end
70
+
71
+ // ---------------------------------------------------------------------------
72
+ // Driver — the one export shape OpenCode 1.x and 2.0 both load (same as
73
+ // `bkit-gateguard.js`): 2.0 calls `setup(ctx)` and registers `execute.after`; 1.18.29+
74
+ // calls `server()` and uses `"tool.execute.after"` plus the `event` hook.
75
+ // ---------------------------------------------------------------------------
76
+
77
+ /** OpenCode 1.x after hook: append the note to `output.output`, the result text. */
78
+ async function bkitReadGuardAfterV1(hookInput, output) {
79
+ try {
80
+ const { tool, sessionID, args } = hookInput ?? {};
81
+ if (!output || typeof output !== "object") return;
82
+ const context = bkitReadguard(tool, args ?? output.args, sessionID);
83
+ if (!context) return;
84
+ const existing = typeof output.output === "string" ? output.output : "";
85
+ output.output = existing.length > 0 ? `${existing}\n\n${context}` : context;
86
+ } catch {
87
+ // fail-open: never let an advisory error reach the host
88
+ }
89
+ }
90
+
91
+ /** OpenCode 1.x event hook: forget a session's reads once it is compacted. */
92
+ async function bkitReadGuardEventV1({ event } = {}) {
93
+ try {
94
+ if (event?.type === "session.compacted") resetReadLog(event.properties?.sessionID);
95
+ } catch {
96
+ // fail-open: never let an advisory error reach the host
97
+ }
98
+ }
99
+
100
+ /** OpenCode 2.0 after hook: append the note to `event.result.content`. */
101
+ async function bkitReadGuardAfterV2(event) {
102
+ try {
103
+ if (event?.status !== "completed" || !event.result) return;
104
+ const context = bkitReadguard(event.tool, event.input, event.sessionID);
105
+ if (!context) return;
106
+ const content = Array.isArray(event.result.content) ? event.result.content : [];
107
+ event.result.content = [...content, { type: "text", text: context }];
108
+ } catch {
109
+ // fail-open: never let an advisory error reach the host
110
+ }
111
+ }
112
+
113
+ const bkitReadGuardPlugin = {
114
+ id: "bkit-readguard",
115
+ async setup(ctx) {
116
+ await ctx.tool.hook("execute.after", bkitReadGuardAfterV2);
117
+ },
118
+ async server() {
119
+ return {
120
+ "tool.execute.after": bkitReadGuardAfterV1,
121
+ event: bkitReadGuardEventV1,
122
+ };
123
+ },
124
+ };
125
+
126
+ export default bkitReadGuardPlugin;
@@ -33,7 +33,7 @@ bkit ships three folders. Path inside a folder = path it lands at in the repo.
33
33
  <!-- prettier-ignore -->
34
34
  | Package folder | Install does | Repo gets |
35
35
  | --- | --- | --- |
36
- | `.bkit/core/` | Writes, keeps current; `engine/`, `workflows/`, `prompts/`, `LICENSE.md` never written as-is (workflows + prompts render to host agent and command copies) | Whole files, managed blocks, hooks, reference docs in `.bkit/`, audit and plan templates |
36
+ | `.bkit/core/` | Writes, keeps current; `engine/`, `workflows/`, `prompts/` never written as-is (workflows + prompts render to host agent and command copies) | Whole files, managed blocks, hooks, reference docs in `.bkit/`, audit and plan templates |
37
37
  | `.bkit/shared/` | Writes, keeps current | bkit blocks and keys inside files you also edit (`docs/*.md`, `.gitignore`, settings, tool-server config) |
38
38
  | `.bkit/templates/` | Never writes into the repo; raw copy at `.bkit/templates/`, `bkit upgrade` lists changed paths | Nothing until you copy one and own it |
39
39
 
@@ -103,7 +103,7 @@ Verify only when applicable.
103
103
  ### Probe Steps
104
104
 
105
105
  - [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. Carry each `Adoption` verdict forward with its age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
106
- - [ ] **Step 2 — Inventory:** List every file in the package's `core/`, `shared/`, `templates/`. Landing path = path inside the folder; `core/engine/`, `core/workflows/`, `core/prompts/`, each `LICENSE.md` → no landing (workflows + prompts → Step 5 host copies). Join: package file · landing path present · in `canonicalHashes` · repo `.bkit/templates/` copy matches package `templates/`. Kind per file: whole file / managed block / owned keys / template. Findings: `core/` or `shared/` file with landing path absent; `canonicalHashes` entry the package no longer ships; repo `.bkit/templates/` differing from package. Group a folder into one row only when every file shares one verdict. **Done when:** `Inventory` row per shipped file or uniform folder: folder · landing path · kind · present · recorded.
106
+ - [ ] **Step 2 — Inventory:** List every file in the package's `core/`, `shared/`, `templates/`. Landing path = path inside the folder; `core/engine/`, `core/workflows/`, `core/prompts/` → no landing (workflows + prompts → Step 5 host copies). Join: package file · landing path present · in `canonicalHashes` · repo `.bkit/templates/` copy matches package `templates/`. Kind per file: whole file / managed block / owned keys / template. Findings: `core/` or `shared/` file with landing path absent; `canonicalHashes` entry the package no longer ships; repo `.bkit/templates/` differing from package. Group a folder into one row only when every file shares one verdict. **Done when:** `Inventory` row per shipped file or uniform folder: folder · landing path · kind · present · recorded.
107
107
  - [ ] **Step 3 — Version:** `pinnedVersion` vs installed package vs registry latest; pinned ≠ installed = package bumped without `bkit upgrade`. Behind → release count; release-note changes touching this repo; template paths changed since pinned version. **Done when:** `Version` names all three versions and every relevant release-note change.
108
108
  - [ ] **Step 4 — Check and Doctor:** `bkit check`: exit code, each drift line → cause. `bkit doctor`: each advisory → adopt / reject (why) / not applicable; previous report's reject carried forward, re-raised only when the advisory text changed. **Done when:** `Check and Doctor` row per drift line and advisory.
109
109
  - [ ] **Step 5 — Hosts:** Agent hosts in use (repo config dirs, team use; newest `bkit-audit-agents` `Hosts` as cross-check, not source) vs bkit hosts installed. Per installed host: one agent copy per `core/prompts/` source, one command copy per `core/workflows/` source, every `core/` hook file present, executable, and wired in that host's settings. Findings: host in use with no bkit install (agents there run without bkit gates); missing or extra copy; hook file present but unwired, or wired but absent. Whether hooks fire and agree across hosts → `bkit-audit-agents`. **Done when:** `Hosts` row per host: in use · installed · agent copies · command copies · hooks wired.
@@ -404,16 +404,19 @@ _No DB changes: "Code-only — `git revert` sufficient."_
404
404
  > **Tests ship with their task.** Task adding / changing logic → names its own unit tests in `Done when`, matrix row or not; tests it breaks → fixed in same task. never defer task tests to later tasks to avoid splits that leave untested code and drop coverage gates.
405
405
  >
406
406
  > **Build order and test source.** Order tasks by build dependency (schema → API → UI). Behaviour tests only from `Derived Test Matrix` rows — do not invent. Boundary-crossing tasks (DB / API / model / network / migration) carry paired non-mock `Done when` tests; pure-function tasks exempt from pairing, not from unit tests.
407
+ >
408
+ > **Test first.** Every task MUST include `**Test first:**` after `Done when`. Behaviour change at unit / integration tier → one or more tests, `;`-separated, each `` `{test file}` `` `` `{test name}` `` fails on {assertion} — repo-relative test files, test names as the runner reports them or their last segments, no `;` in assertion text; build sees each fail against stubs before writing the task's code. No behaviour change (docs, config, pure refactor) or E2E / `@live` tier only → `n/a — {reason naming which}`.
407
409
 
408
- - [ ] **Task 1:** [e.g., Create DB migration (`npx supabase db diff`)]. **Done when:** [e.g., `supabase/migrations/{timestamp}_add_items_status.sql` exists; `npx supabase db push --local` applies cleanly].
409
- - [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes].
410
- - [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state].
410
+ - [ ] **Task 1:** [e.g., Create DB migration (`npx supabase db diff`)]. **Done when:** [e.g., `supabase/migrations/{timestamp}_add_items_status.sql` exists; `npx supabase db push --local` applies cleanly]. **Test first:** [e.g., n/a — migration; fresh-DB replay tier].
411
+ - [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes]. **Test first:** [e.g., `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on the thrown validation error — stub accepts any status; `packages/api/items.integration.test.ts` `persists the new status` fails on the stored row — stub writes nothing].
412
+ - [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state]. **Test first:** [e.g., n/a — E2E tier only; runs in CI].
411
413
 
412
414
  ### 🔒 Gate 2: Code Implementation Check
413
415
 
414
416
  **CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Testing & Documentation`.
415
417
 
416
418
  - [ ] **No bolt-on / no gate-weakening:** every `[NEW]` traces to a `Reuse Inventory` `NEW` row and its search still holds — reusable artifact found mid-build → add a row, fold code into it; every `EXTEND` landed as a modification of the named artifact, not a parallel file. No type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), empty `catch` / error-swallowing introduced to make a gate pass.
419
+ - [ ] **Test first:** every task naming `Test first` tests recorded a red per test before its code; tests unchanged since except added tests / formatting.
417
420
  - [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off against the plan.
418
421
 
419
422
  > [!IMPORTANT]